11# How to write documentation
22
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+
312This 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
13+ how to write **good** documentation. It is important to be as clear
714as you can, and as complete as possible. As a rule of thumb: the more
815documentation you write for your crate the better. If an item is public
916then it should be documented.
1017
11- ## Basic structure
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,ignore
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 abstract function to do this specific thing.
68+ pub fn abstract() {}
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!
1283
1384It is recommended that each item's documentation follows this basic structure:
1485
@@ -23,9 +94,9 @@ It is recommended that each item's documentation follows this basic structure:
2394```
2495
2596This 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.
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.
29100
30101Let's see an example coming from the [standard library] by taking a look at the
31102[`std::env::args()`][env::args] function:
@@ -62,21 +133,40 @@ for argument in env::args() {
62133[`args_os`]: ./fn.args_os.html
63134``````
64135
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+
65150As you can see, it follows the structure detailed above: it starts with a short
66151sentence explaining what the functions does, then it provides more information
67152and finally provides a code example.
68153
69154## Markdown
70155
71- `rustdoc` is using the [commonmark markdown specification]. You might be
156+ `rustdoc` uses the [commonmark markdown specification]. You might be
72157interested into taking a look at their website to see what's possible to do.
158+ - [commonmark quick reference]
159+ - [current spec]
73160
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].
78161
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
162+ [`backtrace`]: https://docs.rs/backtrace/0.3.50/backtrace/
81163[commonmark markdown specification]: https://commonmark.org/
82- [rustdoc-lints]: lints.md
164+ [commonmark quick reference]: https://commonmark.org/help/
165+ [env::args]: https://doc.rust-lang.org/stable/std/env/fn.args.html
166+ [`Future`]: https://doc.rust-lang.org/std/future/trait.Future.html
167+ [`futures`]: https://docs.rs/futures/0.3.5/futures/
168+ [`hashbrown`]: https://docs.rs/hashbrown/0.8.2/hashbrown/
169+ [`regex`]: https://docs.rs/regex/1.3.9/regex/
170+ [standard library]: https://doc.rust-lang.org/stable/std/index.html
171+ [current spec]: https://spec.commonmark.org/current/
172+ [`std::env`]: https://doc.rust-lang.org/stable/std/env/index.html#functions
0 commit comments