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

   1 # How to write documentation
   2
   3 This chapter covers not only how to write documentation but specifically
   4 how to write **good** documentation.  Something to keep in mind when
   5 writing documentation is that your audience is not just yourself but others
   6 who simply don't have the context you do.  It is important to be as clear
   7 as you can, and as complete as possible.  As a rule of thumb: the more
   8 documentation you write for your crate the better.  If an item is public
   9 then it should be documented.
  10
  11 ## Basic structure
  12
  13 It is recommended that each item's documentation follows this basic structure:
  14
  15 ```text
  16 [short sentence explaining what it is]
  17
  18 [more detailed explanation]
  19
  20 [at least one code example that users can copy/paste to try it]
  21
  22 [even more advanced explanations if necessary]
  23 ```
  24
  25 This basic structure should be straightforward to follow when writing your
  26 documentation and, while you might think that a code example is trivial,
  27 the examples are really important because they can help your users to
  28 understand what an item is, how it is used, and for what purpose it exists.
  29
  30 Let's see an example coming from the [standard library] by taking a look at the
  31 [`std::env::args()`][env::args] function:
  32
  33 ``````text
  34 Returns the arguments which this program was started with (normally passed
  35 via the command line).
  36
  37 The first element is traditionally the path of the executable, but it can be
  38 set to arbitrary text, and may not even exist. This means this property should
  39 not be relied upon for security purposes.
  40
  41 On Unix systems shell usually expands unquoted arguments with glob patterns
  42 (such as `*` and `?`). On Windows this is not done, and such arguments are
  43 passed as-is.
  44
  45 # Panics
  46
  47 The returned iterator will panic during iteration if any argument to the
  48 process is not valid unicode. If this is not desired,
  49 use the [`args_os`] function instead.
  50
  51 # Examples
  52
  53 ```
  54 use std::env;
  55
  56 // Prints each argument on a separate line
  57 for argument in env::args() {
  58     println!("{}", argument);
  59 }
  60 ```
  61
  62 [`args_os`]: ./fn.args_os.html
  63 ``````
  64
  65 As you can see, it follows the structure detailed above: it starts with a short
  66 sentence explaining what the functions does, then it provides more information
  67 and finally provides a code example.
  68
  69 ## Markdown
  70
  71 `rustdoc` is using the [commonmark markdown specification]. You might be
  72 interested into taking a look at their website to see what's possible to do.
  73
  74 ## Lints
  75
  76 To be sure that you didn't miss any item without documentation or code examples,
  77 you can take a look at the rustdoc lints [here][rustdoc-lints].
  78
  79 [standard library]: https://doc.rust-lang.org/stable/std/index.html
  80 [env::args]: https://doc.rust-lang.org/stable/std/env/fn.args.html
  81 [commonmark markdown specification]: https://commonmark.org/
  82 [rustdoc-lints]: lints.md