]>
Commit | Line | Data |
---|---|---|
29967ef6 XL |
1 | # What to include (and exclude) |
2 | ||
3 | It is easy to say everything must be documented in a project and often times | |
4 | that is correct, but how can we get there, and are there things that don't | |
5 | belong? | |
6 | ||
7 | At the top of the `src/lib.rs` or `main.rs` file in your binary project, include | |
8 | the following attribute: | |
9 | ||
10 | ```rust | |
11 | #![warn(missing_docs)] | |
12 | ``` | |
13 | ||
14 | Now run `cargo doc` and examine the output. Here's a sample: | |
15 | ||
16 | ```text | |
17 | Documenting docdemo v0.1.0 (/Users/username/docdemo) | |
18 | warning: missing documentation for the crate | |
19 | --> src/main.rs:1:1 | |
20 | | | |
21 | 1 | / #![warn(missing_docs)] | |
22 | 2 | | | |
23 | 3 | | fn main() { | |
24 | 4 | | println!("Hello, world!"); | |
25 | 5 | | } | |
26 | | |_^ | |
27 | | | |
28 | note: the lint level is defined here | |
29 | --> src/main.rs:1:9 | |
30 | | | |
31 | 1 | #![warn(missing_docs)] | |
32 | | ^^^^^^^^^^^^ | |
33 | ||
34 | warning: 1 warning emitted | |
35 | ||
36 | Finished dev [unoptimized + debuginfo] target(s) in 2.96s | |
37 | ``` | |
38 | ||
39 | As a library author, adding the lint `#![deny(missing_docs)]` is a great way to | |
40 | ensure the project does not drift away from being documented well, and | |
6a06907d | 41 | `#![warn(missing_docs)]` is a good way to move towards comprehensive |
29967ef6 XL |
42 | documentation. In addition to docs, `#![deny(missing_doc_code_examples)]` |
43 | ensures each function contains a usage example. In our example above, the | |
6a06907d | 44 | warning is resolved by adding crate level documentation. |
29967ef6 XL |
45 | |
46 | There are more lints in the upcoming chapter [Lints][rustdoc-lints]. | |
47 | ||
48 | ## Examples | |
49 | ||
50 | Of course this is contrived to be simple, but part of the power of documentation | |
51 | is showing code that is easy to follow, rather than being realistic. Docs often | |
52 | take shortcuts with error handling because examples can become complicated to | |
53 | follow with all the necessary set up required for a simple example. | |
54 | ||
55 | `Async` is a good example of this. In order to execute an `async` example, an | |
56 | executor needs to be available. Examples will often shortcut this, and leave | |
57 | users to figure out how to put the `async` code into their own runtime. | |
58 | ||
59 | It is preferred that `unwrap()` not be used inside an example, and some of the | |
60 | error handling components be hidden if they make the example too difficult to | |
6a06907d | 61 | follow. |
29967ef6 XL |
62 | |
63 | ``````text | |
64 | /// Example | |
65 | /// ```rust | |
66 | /// let fourtytwo = "42".parse::<u32>()?; | |
67 | /// println!("{} + 10 = {}", fourtytwo, fourtytwo+10); | |
68 | /// ``` | |
6a06907d | 69 | `````` |
29967ef6 | 70 | |
6a06907d | 71 | When rustdoc wraps that in a main function, it will fail to compile because the |
29967ef6 XL |
72 | `ParseIntError` trait is not implemented. In order to help both your audience |
73 | and your test suite, this example needs some additional code: | |
74 | ||
75 | ``````text | |
76 | /// Example | |
77 | /// ```rust | |
78 | /// # main() -> Result<(), std::num::ParseIntError> { | |
79 | /// let fortytwo = "42".parse::<u32>()?; | |
80 | /// println!("{} + 10 = {}", fortytwo, fortytwo+10); | |
81 | /// # Ok(()) | |
82 | /// # } | |
83 | /// ``` | |
6a06907d | 84 | `````` |
29967ef6 XL |
85 | |
86 | The example is the same on the doc page, but has that extra information | |
6a06907d XL |
87 | available to anyone trying to use your crate. More about tests in the |
88 | upcoming [Documentation tests] chapter. | |
29967ef6 XL |
89 | |
90 | ## What to Exclude | |
91 | ||
92 | Certain parts of your public interface may be included by default in the output | |
93 | of rustdoc. The attribute `#[doc(hidden)]` can hide implementation details | |
6a06907d | 94 | to encourage idiomatic use of the crate. |
29967ef6 XL |
95 | |
96 | For example, an internal `macro!` that makes the crate easier to implement can | |
97 | become a footgun for users when it appears in the public documentation. An | |
98 | internal `Error` type may exist, and `impl` details should be hidden, as | |
99 | detailed in the [API Guidelines]. | |
100 | ||
101 | ## Customizing the output | |
102 | ||
103 | It is possible to pass a custom css file to `rustdoc` and style the | |
6a06907d | 104 | documentation. |
29967ef6 XL |
105 | |
106 | ```bash | |
107 | rustdoc --extend-css custom.css src/lib.rs | |
6a06907d | 108 | ``` |
29967ef6 XL |
109 | |
110 | A good example of using this feature to create a dark theme is documented [on | |
111 | this blog]. Just remember, dark theme is already included in the rustdoc output | |
112 | by clicking on the paintbrush. Adding additional options to the themes are | |
113 | as easy as creating a custom theme `.css` file and using the following syntax: | |
114 | ||
115 | ```bash | |
116 | rustdoc --theme awesome.css src/lib.rs | |
117 | ``` | |
118 | ||
119 | Here is an example of a new theme, [Ayu]. | |
120 | ||
121 | [Ayu]: https://github.com/rust-lang/rust/blob/master/src/librustdoc/html/static/themes/ayu.css | |
122 | [API Guidelines]: https://rust-lang.github.io/api-guidelines/documentation.html#rustdoc-does-not-show-unhelpful-implementation-details-c-hidden | |
123 | [Documentation tests]: documentation-tests.md | |
124 | [on this blog]: https://blog.guillaume-gomez.fr/articles/2016-09-16+Generating+doc+with+rustdoc+and+a+custom+theme | |
6a06907d | 125 | [rustdoc-lints]: lints.md |