|
| 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 |
0 commit comments