src/doc/rustdoc/src/how-to-read-rustdoc.md

   1 # How to read rustdoc output
   2
   3 Rustdoc's HTML output includes a friendly and useful navigation interface which
   4 makes it easier for users to navigate and understand your code.
   5 This chapter covers the major features of that interface,
   6 and is a great starting point for documentation authors and users alike.
   7
   8 ## Structure
   9
  10 The `rustdoc` output is divided into three sections.
  11 Along the left side of each page is a quick navigation bar,
  12 which shows contextual information about the current entry.
  13 The rest of the page is taken up by the search interface at the top
  14 and the documentation for the current item below that.
  15
  16 ## The Item Documentation
  17
  18 The majority of the screen is taken up with the documentation text for the item
  19 currently being viewed.
  20 At the top is some at-a-glance info and controls:
  21
  22 - the type and name of the item,
  23   such as "Struct `std::time::Duration`",
  24 - a button to copy the item's path to the clipboard,
  25   which is a clipboard item
  26 - a button to collapse or expand the top-level documentation for that item
  27   (`[+]` or `[-]`),
  28 - a link to the source code (`[src]`),
  29   if [configured](write-documentation/the-doc-attribute.html#html_no_source),
  30   and present (the source may not be available if
  31   the documentation was created with `cargo doc --no-deps`),
  32 - and the version in which the item became stable,
  33   if it's a stable item in the standard library.
  34
  35 Below this is the main documentation for the item,
  36 including a definition or function signature if appropriate,
  37 followed by a list of fields or variants for Rust types.
  38 Finally, the page lists associated functions and trait implementations,
  39 including automatic and blanket implementations that `rustdoc` knows about.
  40
  41 ### Navigation
  42
  43 Subheadings, variants, fields, and many other things in this documentation
  44 are anchors and can be clicked on and deep-linked to,
  45 which is a great way to communicate exactly what you're talking about.
  46 The typograpical character "§" appears next to lines with anchors on them
  47 when hovered or given keyboard focus.
  48
  49 ## The Navigation Bar
  50
  51 For example, when looking at documentation for the crate root,
  52 it shows all the crates documented in the documentation bundle,
  53 and quick links to the modules, structs, traits, functions, and macros available
  54 from the current crate.
  55 At the top, it displays a [configurable logo](write-documentation/the-doc-attribute.html#html_logo_url)
  56 alongside the current crate's name and version,
  57 or the current item whose documentation is being displayed.
  58
  59 ## The Theme Picker and Search Interface
  60
  61 When viewing `rustdoc`'s output in a browser with JavaScript enabled,
  62 a dynamic interface appears at the top of the page.
  63 To the left is the theme picker, denoted with a paint-brush icon,
  64 and the search interface, help screen, and options appear to the right of that.
  65
  66 ### The Theme Picker
  67
  68 Clicking on the theme picker provides a list of themes -
  69 by default `ayu`, `light`, and `dark` -
  70 which are available for viewing.
  71
  72 ### The Search Interface
  73
  74 Typing in the search bar instantly searches the available documentation for
  75 the string entered with a fuzzy matching algorithm that is tolerant of minor
  76 typos.
  77
  78 By default, the search results give are "In Names",
  79 meaning that the fuzzy match is made against the names of items.
  80 Matching names are shown on the left, and the first few words of their
  81 descriptions are given on the right.
  82 By clicking an item, you will navigate to its particular documentation.
  83
  84 There are two other sets of results, shown as tabs in the search results pane.
  85 "In Parameters" shows matches for the string in the types of parameters to
  86 functions, and "In Return Types" shows matches in the return types of functions.
  87 Both are very useful when looking for a function whose name you can't quite
  88 bring to mind when you know the type you have or want.
  89
  90 When typing in the search bar, you can prefix your search term with a type
  91 followed by a colon (such as `mod:`) to restrict the results to just that
  92 kind of item. (The available items are listed in the help popup.)
  93
  94 ### Shortcuts
  95
  96 Pressing `S` while focused elsewhere on the page will move focus to the
  97 search bar, and pressing `?` shows the help screen,
  98 which includes all these shortcuts and more.
  99 Pressing `T` focuses the theme picker.
 100
 101 When the search results are focused,
 102 the left and right arrows move between tabs and the up and down arrows move
 103 among the results.
 104 Pressing the enter or return key opens the highlighted result.
 105
 106 When looking at the documentation for an item, the plus and minus keys expand
 107 and collapse all sections in the document.