src/doc/rustdoc/src/how-to-write-documentation.md

   1 # How to write documentation
   2
   3 Good documentation is not natural.  There are opposing goals that make writing
   4 good documentation difficult.  It requires expertise in the subject but also
   5 writing to a novice perspective.  Documentation therefore often glazes over
   6 implementation detail, or leaves readers with unanswered questions.
   7
   8 There are a few tenets to Rust documentation that can help guide anyone through
   9 the process of documenting libraries so that everyone has an ample opportunity
  10 to use the code.
  11
  12 This chapter covers not only how to write documentation but specifically
  13 how to write **good** documentation.  It is important to be as clear
  14 as you can, and as complete as possible.  As a rule of thumb: the more
  15 documentation you write for your crate the better.  If an item is public
  16 then it should be documented.
  17
  18 ## Getting Started
  19
  20 Documenting a crate should begin with front-page documentation.  As an
  21 example, the [`hashbrown`] crate level documentation summarizes the role of
  22 the crate, provides links to explain technical details, and explains why you
  23 would want to use the crate.
  24
  25 After introducing the crate, it is important that the front-page gives
  26 an example of how to use the crate in a real world setting.  Stick to the
  27 library's role in the example, but do so without shortcuts to benefit users who
  28 may copy and paste the example to get started.
  29
  30 [`futures`] uses inline comments to explain line by line
  31 the complexities of using a [`Future`], because a person's first exposure to
  32 rust's [`Future`] may be this example.
  33
  34 The [`backtrace`] documentation walks through the whole process, explaining
  35 changes made to the `Cargo.toml` file, passing command line arguments to the
  36 compiler, and shows a quick example of backtrace in the wild.
  37
  38 Finally, the front-page can eventually become a comprehensive reference
  39 how to use a crate, like [`regex`].  In this front page, all
  40 requirements are outlined, the edge cases shown, and practical examples
  41 provided.  The front page goes on to show how to use regular expressions
  42 then concludes with crate features.
  43
  44 Don't worry about comparing your crate, which is just beginning, to other more
  45 developed crates.  To get the documentation to something more polished, start
  46 incrementally and put in an introduction, example, and features.  Rome was not
  47 built in a day!
  48
  49 The first lines within the `lib.rs` will compose the front-page, and they
  50 use a different convention than the rest of the rustdocs.  Lines should
  51 start with `//!` which indicate module-level or crate-level documentation.
  52 Here's a quick example of the difference:
  53
  54 ```rust,no_run
  55 //! Fast and easy queue abstraction.
  56 //!
  57 //! Provides an abstraction over a queue.  When the abstraction is used
  58 //! there are these advantages:
  59 //! - Fast
  60 //! - [`Easy`]
  61 //!
  62 //! [`Easy`]: http://thatwaseasy.example.com
  63
  64 /// This module makes it easy.
  65 pub mod easy {
  66
  67     /// Use the abstraction function to do this specific thing.
  68     pub fn abstraction() {}
  69
  70 }
  71 ```
  72
  73 Ideally, this first line of documentation is a sentence without highly
  74 technical details, but with a good description of where this crate fits
  75 within the rust ecosystem.  Users should know whether this crate meets their use
  76 case after reading this line.
  77
  78 ## Documenting components
  79
  80 Whether it is modules, structs, functions, or macros: the public
  81 API of all code should have documentation. Rarely does anyone
  82 complain about too much documentation!
  83
  84 It is recommended that each item's documentation follows this basic structure:
  85
  86 ```text
  87 [short sentence explaining what it is]
  88
  89 [more detailed explanation]
  90
  91 [at least one code example that users can copy/paste to try it]
  92
  93 [even more advanced explanations if necessary]
  94 ```
  95
  96 This basic structure should be straightforward to follow when writing your
  97 documentation; while you might think that a code example is trivial,
  98 the examples are really important because they can help users understand
  99 what an item is, how it is used, and for what purpose it exists.
 100
 101 Let's see an example coming from the [standard library] by taking a look at the
 102 [`std::env::args()`][env::args] function:
 103
 104 ``````text
 105 Returns the arguments which this program was started with (normally passed
 106 via the command line).
 107
 108 The first element is traditionally the path of the executable, but it can be
 109 set to arbitrary text, and may not even exist. This means this property should
 110 not be relied upon for security purposes.
 111
 112 On Unix systems shell usually expands unquoted arguments with glob patterns
 113 (such as `*` and `?`). On Windows this is not done, and such arguments are
 114 passed as-is.
 115
 116 # Panics
 117
 118 The returned iterator will panic during iteration if any argument to the
 119 process is not valid unicode. If this is not desired,
 120 use the [`args_os`] function instead.
 121
 122 # Examples
 123
 124 ```
 125 use std::env;
 126
 127 // Prints each argument on a separate line
 128 for argument in env::args() {
 129     println!("{}", argument);
 130 }
 131 ```
 132
 133 [`args_os`]: ./fn.args_os.html
 134 ``````
 135
 136 Everything before the first empty line will be reused to describe the component
 137 in searches and module overviews.  For example, the function `std::env::args()`
 138 above will be shown on the [`std::env`] module documentation.  It is good
 139 practice to keep the summary to one line: concise writing is a goal of good
 140 documentation.
 141
 142 Because the type system does a good job of defining what types a function
 143 passes and returns, there is no benefit of explicitly writing it
 144 into the documentation, especially since `rustdoc` adds hyper links to all types in the function signature.
 145
 146 In the example above, a 'Panics' section explains when the code might abruptly exit,
 147 which can help the reader prevent reaching a panic.  A panic section is recommended
 148 every time edge cases in your code can be reached if known.
 149
 150 As you can see, it follows the structure detailed above: it starts with a short
 151 sentence explaining what the functions does, then it provides more information
 152 and finally provides a code example.
 153
 154 ## Markdown
 155
 156 `rustdoc` uses the [CommonMark markdown specification]. You might be
 157 interested into taking a look at their website to see what's possible to do.
 158  - [commonmark quick reference]
 159  - [current spec]
 160
 161 In addition to the standard CommonMark syntax, `rustdoc` supports several
 162 extensions:
 163
 164 ### Strikethrough
 165
 166 Text may be rendered with a horizontal line through the center by wrapping the
 167 text with two tilde characters on each side:
 168
 169 ```text
 170 An example of ~~strikethrough text~~.
 171 ```
 172
 173 This example will render as:
 174
 175 > An example of ~~strikethrough text~~.
 176
 177 This follows the [GitHub Strikethrough extension][strikethrough].
 178
 179 ### Footnotes
 180
 181 A footnote generates a small numbered link in the text which when clicked
 182 takes the reader to the footnote text at the bottom of the item. The footnote
 183 label is written similarly to a link reference with a caret at the front. The
 184 footnote text is written like a link reference definition, with the text
 185 following the label. Example:
 186
 187 ```text
 188 This is an example of a footnote[^note].
 189
 190 [^note]: This text is the contents of the footnote, which will be rendered
 191     towards the bottom.
 192 ```
 193
 194 This example will render as:
 195
 196 > This is an example of a footnote[^note].
 197 >
 198 > [^note]: This text is the contents of the footnote, which will be rendered
 199 >     towards the bottom.
 200
 201 The footnotes are automatically numbered based on the order the footnotes are
 202 written.
 203
 204 ### Tables
 205
 206 Tables can be written using pipes and dashes to draw the rows and columns of
 207 the table. These will be translated to HTML table matching the shape. Example:
 208
 209 ```text
 210 | Header1 | Header2 |
 211 |---------|---------|
 212 | abc     | def     |
 213 ```
 214
 215 This example will render similarly to this:
 216
 217 > | Header1 | Header2 |
 218 > |---------|---------|
 219 > | abc     | def     |
 220
 221 See the specification for the [GitHub Tables extension][tables] for more
 222 details on the exact syntax supported.
 223
 224 ### Task lists
 225
 226 Task lists can be used as a checklist of items that have been completed.
 227 Example:
 228
 229 ```md
 230 - [x] Complete task
 231 - [ ] IncComplete task
 232 ```
 233
 234 This will render as
 235
 236 <ul>
 237     <li><input type="checkbox"></li>
 238     <li><input type="checkbox" checked></li>
 239 </ul>
 240
 241 See the specification for the [task list extension] for more details.
 242
 243 [`backtrace`]: https://docs.rs/backtrace/0.3.50/backtrace/
 244 [commonmark markdown specification]: https://commonmark.org/
 245 [commonmark quick reference]: https://commonmark.org/help/
 246 [env::args]: https://doc.rust-lang.org/stable/std/env/fn.args.html
 247 [`Future`]: https://doc.rust-lang.org/std/future/trait.Future.html
 248 [`futures`]: https://docs.rs/futures/0.3.5/futures/
 249 [`hashbrown`]: https://docs.rs/hashbrown/0.8.2/hashbrown/
 250 [`regex`]: https://docs.rs/regex/1.3.9/regex/
 251 [standard library]: https://doc.rust-lang.org/stable/std/index.html
 252 [current spec]: https://spec.commonmark.org/current/
 253 [`std::env`]: https://doc.rust-lang.org/stable/std/env/index.html#functions
 254 [strikethrough]: https://github.github.com/gfm/#strikethrough-extension-
 255 [tables]: https://github.github.com/gfm/#tables-extension-
 256 [task list extension]: https://github.github.com/gfm/#task-list-items-extension-