3 `rustdoc` provides lints to help you writing and testing your documentation. You
4 can use them like any other lints by doing this:
7 #![allow(missing_docs)] // allowing the lint, no message
8 #![warn(missing_docs)] // warn if there is missing docs
9 #![deny(missing_docs)] // rustdoc will fail if there is missing docs
12 Here is the list of the lints provided by `rustdoc`:
14 ## broken_intra_doc_links
16 This lint **warns by default**. This lint detects when an [intra-doc link] fails to get resolved. For example:
18 [intra-doc link]: linking-to-items-by-name.html
21 /// I want to link to [`Nonexistent`] but it doesn't exist!
25 You'll get a warning saying:
28 warning: unresolved link to `Nonexistent`
31 1 | /// I want to link to [`Nonexistent`] but it doesn't exist!
32 | ^^^^^^^^^^^^^ no item named `Nonexistent` in `test`
35 It will also warn when there is an ambiguity and suggest how to disambiguate:
47 warning: `Foo` is both an enum and a function
51 | ^^^^^ ambiguous link
53 = note: `#[warn(broken_intra_doc_links)]` on by default
54 help: to link to the enum, prefix with the item type
58 help: to link to the function, add parentheses
65 ## private_intra_doc_links
67 This lint **warns by default**. This lint detects when [intra-doc links] from public to private items.
76 This gives a warning that the link will be broken when it appears in your documentation:
79 warning: public documentation for `public` links to private item `private`
83 | ^^^^^^^ this item is private
85 = note: `#[warn(private_intra_doc_links)]` on by default
86 = note: this link will resolve properly if you pass `--document-private-items`
89 Note that this has different behavior depending on whether you pass `--document-private-items` or not!
90 If you document private items, then it will still generate a link, despite the warning:
93 warning: public documentation for `public` links to private item `private`
97 | ^^^^^^^ this item is private
99 = note: `#[warn(private_intra_doc_links)]` on by default
100 = note: this link resolves only because you passed `--document-private-items`, but will break without
103 [intra-doc links]: linking-to-items-by-name.html
107 This lint is **allowed by default**. It detects items missing documentation.
111 #![warn(missing_docs)]
113 pub fn undocumented() {}
117 The `undocumented` function will then have the following warning:
120 warning: missing documentation for a function
121 --> your-crate/lib.rs:3:1
123 3 | pub fn undocumented() {}
124 | ^^^^^^^^^^^^^^^^^^^^^
127 ## missing_crate_level_docs
129 This lint is **allowed by default**. It detects if there is no documentation
130 at the crate root. For example:
133 #![warn(missing_crate_level_docs)]
136 This will generate the following warning:
139 warning: no documentation found for this crate's top-level module
141 = help: The following guide may be of use:
142 https://doc.rust-lang.org/nightly/rustdoc/how-to-write-documentation.html
145 This is currently "allow" by default, but it is intended to make this a
146 warning in the future. This is intended as a means to introduce new users on
147 *how* to document their crate by pointing them to some instructions on how to
148 get started, without providing overwhelming warnings like `missing_docs`
151 ## missing_doc_code_examples
153 This lint is **allowed by default** and is **nightly-only**. It detects when a documentation block
154 is missing a code example. For example:
157 #![warn(missing_doc_code_examples)]
159 /// There is no code example!
160 pub fn no_code_example() {}
164 The `no_code_example` function will then have the following warning:
167 warning: Missing code example in this documentation
168 --> your-crate/lib.rs:3:1
170 LL | /// There is no code example!
171 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
174 To fix the lint, you need to add a code example into the documentation block:
177 /// There is no code example!
180 /// println!("calling no_code_example...");
181 /// no_code_example();
182 /// println!("we called no_code_example!");
184 pub fn no_code_example() {}
189 This lint is **allowed by default**. It detects documentation tests when they
190 are on a private item. For example:
193 #![warn(private_doc_tests)]
209 warning: Documentation test in private item
210 --> your-crate/lib.rs:4:1
212 4 | / /// private doc test
215 7 | | /// assert!(false);
220 ## invalid_codeblock_attributes
222 This lint **warns by default**. It detects code block attributes in
223 documentation examples that have potentially mis-typed values. For example:
229 /// assert_eq!(1, 2);
237 warning: unknown attribute `should-panic`. Did you mean `should_panic`?
242 3 | | /// ```should-panic
243 4 | | /// assert_eq!(1, 2);
247 = note: `#[warn(invalid_codeblock_attributes)]` on by default
248 = help: the code block will either not be tested if not marked as a rust one or won't fail if it doesn't panic when running
251 In the example above, the correct form is `should_panic`. This helps detect
252 typo mistakes for some common attributes.
256 This lint is **allowed by default** and is **nightly-only**. It detects unclosed
257 or invalid HTML tags. For example:
260 #![warn(invalid_html_tags)]
270 warning: unopened HTML tag `script`
277 = note: `#[warn(invalid_html_tags)]` on by default
279 warning: unclosed HTML tag `h1`
286 warning: 2 warnings emitted