There are a few tenets to Rust documentation that can help guide anyone through
the process of documenting libraries so that everyone has an ample opportunity
-to use the code.
+to use the code.
This chapter covers not only how to write documentation but specifically
how to write **good** documentation. It is important to be as clear
Documenting a crate should begin with front-page documentation. As an
example, the [`hashbrown`] crate level documentation summarizes the role of
-the crate, provides links to explain technical details, and explains why you
-would want to use the crate.
+the crate, provides links to explain technical details, and explains why you
+would want to use the crate.
-After introducing the crate, it is important that the front-page gives
+After introducing the crate, it is important that the front-page gives
an example of how to use the crate in a real world setting. Stick to the
library's role in the example, but do so without shortcuts to benefit users who
-may copy and paste the example to get started.
+may copy and paste the example to get started.
[`futures`] uses inline comments to explain line by line
-the complexities of using a [`Future`], because a person's first exposure to
+the complexities of using a [`Future`], because a person's first exposure to
rust's [`Future`] may be this example.
-The [`backtrace`] documentation walks through the whole process, explaining
+The [`backtrace`] documentation walks through the whole process, explaining
changes made to the `Cargo.toml` file, passing command line arguments to the
-compiler, and shows a quick example of backtrace in the wild.
+compiler, and shows a quick example of backtrace in the wild.
Finally, the front-page can eventually become a comprehensive reference
how to use a crate, like [`regex`]. In this front page, all
-requirements are outlined, the edge cases shown, and practical examples
+requirements are outlined, the edge cases shown, and practical examples
provided. The front page goes on to show how to use regular expressions
then concludes with crate features.
Don't worry about comparing your crate, which is just beginning, to other more
developed crates. To get the documentation to something more polished, start
-incrementally and put in an introduction, example, and features. Rome was not
+incrementally and put in an introduction, example, and features. Rome was not
built in a day!
The first lines within the `lib.rs` will compose the front-page, and they
start with `//!` which indicate module-level or crate-level documentation.
Here's a quick example of the difference:
-```rust,ignore
+```rust,no_run
//! Fast and easy queue abstraction.
//!
//! Provides an abstraction over a queue. When the abstraction is used
/// This module makes it easy.
pub mod easy {
- /// Use the abstract function to do this specific thing.
- pub fn abstract() {}
+ /// Use the abstraction function to do this specific thing.
+ pub fn abstraction() {}
}
```
-Ideally, this first line of documentation is a sentence without highly
+Ideally, this first line of documentation is a sentence without highly
technical details, but with a good description of where this crate fits
within the rust ecosystem. Users should know whether this crate meets their use
case after reading this line.
This basic structure should be straightforward to follow when writing your
documentation; while you might think that a code example is trivial,
-the examples are really important because they can help users understand
+the examples are really important because they can help users understand
what an item is, how it is used, and for what purpose it exists.
Let's see an example coming from the [standard library] by taking a look at the
[`std::env::args()`][env::args] function:
-``````text
+``````markdown
Returns the arguments which this program was started with (normally passed
via the command line).
[`args_os`]: ./fn.args_os.html
``````
-Everything before the first empty line will be reused to describe the component
+Everything before the first empty line will be reused to describe the component
in searches and module overviews. For example, the function `std::env::args()`
-above will be shown on the [`std::env`] module documentation. It is good
+above will be shown on the [`std::env`] module documentation. It is good
practice to keep the summary to one line: concise writing is a goal of good
documentation.
## Markdown
-`rustdoc` uses the [CommonMark markdown specification]. You might be
-interested into taking a look at their website to see what's possible to do.
- - [commonmark quick reference]
+`rustdoc` uses the [CommonMark Markdown specification]. You might be
+interested in taking a look at their website to see what's possible:
+
+ - [CommonMark quick reference]
- [current spec]
In addition to the standard CommonMark syntax, `rustdoc` supports several
See the specification for the [GitHub Tables extension][tables] for more
details on the exact syntax supported.
+### Task lists
+
+Task lists can be used as a checklist of items that have been completed.
+Example:
+
+```md
+- [x] Complete task
+- [ ] IncComplete task
+```
+
+This will render as
+
+<ul>
+ <li><input type="checkbox"></li>
+ <li><input type="checkbox" checked></li>
+</ul>
+
+See the specification for the [task list extension] for more details.
+
+### Smart punctuation
+
+Some ASCII punctuation sequences will be automatically turned into fancy Unicode
+characters:
+
+| ASCII sequence | Unicode |
+|----------------|---------|
+| `--` | – |
+| `---` | — |
+| `...` | … |
+| `"` | “ or ”, depending on context |
+| `'` | ‘ or ’, depending on context |
+
+So, no need to manually enter those Unicode characters!
+
[`backtrace`]: https://docs.rs/backtrace/0.3.50/backtrace/
[commonmark markdown specification]: https://commonmark.org/
[commonmark quick reference]: https://commonmark.org/help/
[env::args]: https://doc.rust-lang.org/stable/std/env/fn.args.html
-[`Future`]: https://doc.rust-lang.org/std/future/trait.Future.html
+[`Future`]: https://doc.rust-lang.org/std/future/trait.Future.html
[`futures`]: https://docs.rs/futures/0.3.5/futures/
[`hashbrown`]: https://docs.rs/hashbrown/0.8.2/hashbrown/
[`regex`]: https://docs.rs/regex/1.3.9/regex/
[`std::env`]: https://doc.rust-lang.org/stable/std/env/index.html#functions
[strikethrough]: https://github.github.com/gfm/#strikethrough-extension-
[tables]: https://github.github.com/gfm/#tables-extension-
+[task list extension]: https://github.github.com/gfm/#task-list-items-extension-
projects / rustc.git / blobdiff