3 Documentation is an important part of any software project, and it's
4 first-class in Rust. Let's talk about the tooling Rust gives you to
9 The Rust distribution includes a tool, `rustdoc`, that generates documentation.
10 `rustdoc` is also used by Cargo through `cargo doc`.
12 Documentation can be generated in two ways: from source code, and from
13 standalone Markdown files.
15 ## Documenting source code
17 The primary way of documenting a Rust project is through annotating the source
18 code. You can use documentation comments for this purpose:
21 /// Constructs a new `Rc<T>`.
28 /// let five = Rc::new(5);
30 pub fn new(value: T) -> Rc<T> {
31 // implementation goes here
35 This code generates documentation that looks [like this][rc-new]. I've left the
36 implementation out, with a regular comment in its place. That's the first thing
37 to notice about this annotation: it uses `///`, instead of `//`. The triple slash
38 indicates a documentation comment.
40 Documentation comments are written in Markdown.
42 Rust keeps track of these comments, and uses them when generating
43 documentation. This is important when documenting things like enums:
46 /// The `Option` type. See [the module level documentation](../) for more.
55 The above works, but this does not:
58 /// The `Option` type. See [the module level documentation](../) for more.
61 Some(T), /// Some value `T`
68 hello.rs:4:1: 4:2 error: expected ident, found `}`
73 This [unfortunate error](https://github.com/rust-lang/rust/issues/22547) is
74 correct: documentation comments apply to the thing after them, and there's no
75 thing after that last comment.
77 [rc-new]: http://doc.rust-lang.org/nightly/std/rc/struct.Rc.html#method.new
79 ### Writing documentation comments
81 Anyway, let's cover each part of this comment in detail:
84 /// Constructs a new `Rc<T>`.
88 The first line of a documentation comment should be a short summary of its
89 functionality. One sentence. Just the basics. High level.
93 /// Other details about constructing `Rc<T>`s, maybe describing complicated
94 /// semantics, maybe additional options, all kinds of stuff.
99 Our original example had just a summary line, but if we had more things to say,
100 we could have added more explanation in a new paragraph.
102 #### Special sections
109 Next, are special sections. These are indicated with a header, `#`. There
110 are three kinds of headers that are commonly used. They aren't special syntax,
111 just convention, for now.
118 Unrecoverable misuses of a function (i.e. programming errors) in Rust are
119 usually indicated by panics, which kill the whole current thread at the very
120 least. If your function has a non-trivial contract like this, that is
121 detected/enforced by panics, documenting it is very important.
128 If your function or method returns a `Result<T, E>`, then describing the
129 conditions under which it returns `Err(E)` is a nice thing to do. This is
130 slightly less important than `Panics`, because failure is encoded into the type
131 system, but it's still a good thing to do.
138 If your function is `unsafe`, you should explain which invariants the caller is
139 responsible for upholding.
147 /// let five = Rc::new(5);
152 Third, `Examples`. Include one or more examples of using your function or
153 method, and your users will love you for it. These examples go inside of
154 code block annotations, which we'll talk about in a moment, and can have
155 more than one section:
160 /// Simple `&str` patterns:
163 /// let v: Vec<&str> = "Mary had a little lamb".split(' ').collect();
164 /// assert_eq!(v, vec!["Mary", "had", "a", "little", "lamb"]);
167 /// More complex patterns with a lambda:
170 /// let v: Vec<&str> = "abc1def2ghi".split(|c: char| c.is_numeric()).collect();
171 /// assert_eq!(v, vec!["abc", "def", "ghi"]);
176 Let's discuss the details of these code blocks.
178 #### Code block annotations
180 To write some Rust code in a comment, use the triple graves:
184 /// println!("Hello, world");
189 If you want something that's not Rust code, you can add an annotation:
193 /// printf("Hello, world\n");
198 This will highlight according to whatever language you're showing off.
199 If you're just showing plain text, choose `text`.
201 It's important to choose the correct annotation here, because `rustdoc` uses it
202 in an interesting way: It can be used to actually test your examples, so that
203 they don't get out of date. If you have some C code but `rustdoc` thinks it's
204 Rust because you left off the annotation, `rustdoc` will complain when trying to
205 generate the documentation.
207 ## Documentation as tests
209 Let's discuss our sample example documentation:
213 /// println!("Hello, world");
218 You'll notice that you don't need a `fn main()` or anything here. `rustdoc` will
219 automatically add a main() wrapper around your code, and in the right place.
226 /// let five = Rc::new(5);
231 This will end up testing:
236 let five = Rc::new(5);
240 Here's the full algorithm rustdoc uses to postprocess examples:
242 1. Any leading `#![foo]` attributes are left intact as crate attributes.
243 2. Some common `allow` attributes are inserted, including
244 `unused_variables`, `unused_assignments`, `unused_mut`,
245 `unused_attributes`, and `dead_code`. Small examples often trigger
247 3. If the example does not contain `extern crate`, then `extern crate
248 <mycrate>;` is inserted.
249 2. Finally, if the example does not contain `fn main`, the remainder of the
250 text is wrapped in `fn main() { your_code }`
252 Sometimes, this isn't enough, though. For example, all of these code samples
253 with `///` we've been talking about? The raw text:
256 /// Some documentation.
260 looks different than the output:
263 /// Some documentation.
267 Yes, that's right: you can add lines that start with `# `, and they will
268 be hidden from the output, but will be used when compiling your code. You
269 can use this to your advantage. In this case, documentation comments need
270 to apply to some kind of function, so if I want to show you just a
271 documentation comment, I need to add a little function definition below
272 it. At the same time, it's just there to satisfy the compiler, so hiding
273 it makes the example more clear. You can use this technique to explain
274 longer examples in detail, while still preserving the testability of your
275 documentation. For example, this code:
280 println!("{}", x + y);
283 Here's an explanation, rendered:
285 First, we set `x` to five:
290 # println!("{}", x + y);
293 Next, we set `y` to six:
298 # println!("{}", x + y);
301 Finally, we print the sum of `x` and `y`:
306 println!("{}", x + y);
309 Here's the same explanation, in raw text:
311 > First, we set `x` to five:
316 > # println!("{}", x + y);
319 > Next, we set `y` to six:
324 > # println!("{}", x + y);
327 > Finally, we print the sum of `x` and `y`:
332 > println!("{}", x + y);
335 By repeating all parts of the example, you can ensure that your example still
336 compiles, while only showing the parts that are relevant to that part of your
339 ### Documenting macros
341 Here’s an example of documenting a macro:
344 /// Panic with a given message unless an expression evaluates to true.
349 /// # #[macro_use] extern crate foo;
351 /// panic_unless!(1 + 1 == 2, “Math is broken.”);
356 /// # #[macro_use] extern crate foo;
358 /// panic_unless!(true == false, “I’m broken.”);
362 macro_rules! panic_unless {
363 ($condition:expr, $($rest:expr),+) => ({ if ! $condition { panic!($($rest),+); } });
368 You’ll note three things: we need to add our own `extern crate` line, so that
369 we can add the `#[macro_use]` attribute. Second, we’ll need to add our own
370 `main()` as well. Finally, a judicious use of `#` to comment out those two
371 things, so they don’t show up in the output.
373 ### Running documentation tests
375 To run the tests, either
378 $ rustdoc --test path/to/my/crate/root.rs
383 That's right, `cargo test` tests embedded documentation too.
385 There are a few more annotations that are useful to help `rustdoc` do the right
386 thing when testing your code:
395 The `ignore` directive tells Rust to ignore your code. This is almost never
396 what you want, as it's the most generic. Instead, consider annotating it
397 with `text` if it's not code, or using `#`s to get a working example that
398 only shows the part you care about.
407 `should_panic` tells `rustdoc` that the code should compile correctly, but
408 not actually pass as a test.
413 /// println!("Hello, world");
419 The `no_run` attribute will compile your code, but not run it. This is
420 important for examples such as "Here's how to start up a network service,"
421 which you would want to make sure compile, but might run in an infinite loop!
423 ### Documenting modules
425 Rust has another kind of doc comment, `//!`. This comment doesn't document the next item, but the enclosing item. In other words:
429 //! This is documentation for the `foo` module.
437 This is where you'll see `//!` used most often: for module documentation. If
438 you have a module in `foo.rs`, you'll often open its code and see this:
441 //! A module for using `foo`s.
443 //! The `foo` module contains a lot of useful functionality blah blah blah
446 ### Documentation comment style
448 Check out [RFC 505][rfc505] for full conventions around the style and format of
451 [rfc505]: https://github.com/rust-lang/rfcs/blob/master/text/0505-api-comment-conventions.md
453 ## Other documentation
455 All of this behavior works in non-Rust source files too. Because comments
456 are written in Markdown, they're often `.md` files.
458 When you write documentation in Markdown files, you don't need to prefix
459 the documentation with comments. For example:
467 /// let five = Rc::new(5);
480 let five = Rc::new(5);
484 when it's in a Markdown file. There is one wrinkle though: Markdown files need
485 to have a title like this:
490 This is the example documentation.
493 This `%` line needs to be the very first line of the file.
497 At a deeper level, documentation comments are sugar for documentation attributes:
507 are the same, as are these:
515 You won't often see this attribute used for writing documentation, but it
516 can be useful when changing some options, or when writing a macro.
520 `rustdoc` will show the documentation for a public re-export in both places:
528 This will create documentation for bar both inside the documentation for the
529 crate `foo`, as well as the documentation for your crate. It will use the same
530 documentation in both places.
532 This behavior can be suppressed with `no_inline`:
543 You can control a few aspects of the HTML that `rustdoc` generates through the
544 `#![doc]` version of the attribute:
547 #![doc(html_logo_url = "http://www.rust-lang.org/logos/rust-logo-128x128-blk-v2.png",
548 html_favicon_url = "http://www.rust-lang.org/favicon.ico",
549 html_root_url = "http://doc.rust-lang.org/")];
552 This sets a few different options, with a logo, favicon, and a root URL.
554 ## Generation options
556 `rustdoc` also contains a few other options on the command line, for further customiziation:
558 - `--html-in-header FILE`: includes the contents of FILE at the end of the
559 `<head>...</head>` section.
560 - `--html-before-content FILE`: includes the contents of FILE directly after
561 `<body>`, before the rendered content (including the search bar).
562 - `--html-after-content FILE`: includes the contents of FILE after all the rendered content.