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(rustdoc::broken_intra_doc_links)] // allows the lint, no diagnostics will be reported
8 #![warn(rustdoc::broken_intra_doc_links)] // warn if there are broken intra-doc links
9 #![deny(rustdoc::broken_intra_doc_links)] // error if there are broken intra-doc links
12 Note that, except for `missing_docs`, these lints are only available when running `rustdoc`, not `rustc`.
14 Here is the list of the lints provided by `rustdoc`:
16 ## `broken_intra_doc_links`
18 This lint **warns by default**. This lint detects when an [intra-doc link] fails to be resolved. For example:
20 [intra-doc link]: write-documentation/linking-to-items-by-name.md
23 /// I want to link to [`Nonexistent`] but it doesn't exist!
27 You'll get a warning saying:
30 warning: unresolved link to `Nonexistent`
33 1 | /// I want to link to [`Nonexistent`] but it doesn't exist!
34 | ^^^^^^^^^^^^^ no item named `Nonexistent` in `test`
37 It will also warn when there is an ambiguity and suggest how to disambiguate:
49 warning: `Foo` is both an enum and a function
53 | ^^^^^ ambiguous link
55 = note: `#[warn(rustdoc::broken_intra_doc_links)]` on by default
56 help: to link to the enum, prefix with the item type
60 help: to link to the function, add parentheses
67 ## `private_intra_doc_links`
69 This lint **warns by default**. This lint detects when [intra-doc links] from public to private items.
73 #![warn(rustdoc::private_intra_doc_links)] // note: unnecessary - warns by default.
80 This gives a warning that the link will be broken when it appears in your documentation:
83 warning: public documentation for `public` links to private item `private`
87 | ^^^^^^^ this item is private
89 = note: `#[warn(rustdoc::private_intra_doc_links)]` on by default
90 = note: this link will resolve properly if you pass `--document-private-items`
93 Note that this has different behavior depending on whether you pass `--document-private-items` or not!
94 If you document private items, then it will still generate a link, despite the warning:
97 warning: public documentation for `public` links to private item `private`
101 | ^^^^^^^ this item is private
103 = note: `#[warn(rustdoc::private_intra_doc_links)]` on by default
104 = note: this link resolves only because you passed `--document-private-items`, but will break without
107 [intra-doc links]: write-documentation/linking-to-items-by-name.md
111 This lint is **allowed by default**. It detects items missing documentation.
115 #![warn(missing_docs)]
117 pub fn undocumented() {}
121 The `undocumented` function will then have the following warning:
124 warning: missing documentation for a function
125 --> your-crate/lib.rs:3:1
127 3 | pub fn undocumented() {}
128 | ^^^^^^^^^^^^^^^^^^^^^
131 Note that unlike other rustdoc lints, this lint is also available from `rustc` directly.
133 ## `missing_crate_level_docs`
135 This lint is **allowed by default**. It detects if there is no documentation
136 at the crate root. For example:
139 #![warn(rustdoc::missing_crate_level_docs)]
142 This will generate the following warning:
145 warning: no documentation found for this crate's top-level module
147 = help: The following guide may be of use:
148 https://doc.rust-lang.org/nightly/rustdoc/how-to-write-documentation.html
151 This is currently "allow" by default, but it is intended to make this a
152 warning in the future. This is intended as a means to introduce new users on
153 *how* to document their crate by pointing them to some instructions on how to
154 get started, without providing overwhelming warnings like `missing_docs`
157 ## `missing_doc_code_examples`
159 This lint is **allowed by default** and is **nightly-only**. It detects when a documentation block
160 is missing a code example. For example:
163 #![warn(rustdoc::missing_doc_code_examples)]
165 /// There is no code example!
166 pub fn no_code_example() {}
170 The `no_code_example` function will then have the following warning:
173 warning: Missing code example in this documentation
174 --> your-crate/lib.rs:3:1
176 LL | /// There is no code example!
177 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
180 To fix the lint, you need to add a code example into the documentation block:
183 /// There is no code example!
186 /// println!("calling no_code_example...");
187 /// no_code_example();
188 /// println!("we called no_code_example!");
190 pub fn no_code_example() {}
193 ## `private_doc_tests`
195 This lint is **allowed by default**. It detects documentation tests when they
196 are on a private item. For example:
199 #![warn(rustdoc::private_doc_tests)]
215 warning: Documentation test in private item
216 --> your-crate/lib.rs:4:1
218 4 | / /// private doc test
221 7 | | /// assert!(false);
226 ## `invalid_codeblock_attributes`
228 This lint **warns by default**. It detects code block attributes in
229 documentation examples that have potentially mis-typed values. For example:
232 #![warn(rustdoc::invalid_codeblock_attributes)] // note: unnecessary - warns by default.
237 /// assert_eq!(1, 2);
245 warning: unknown attribute `should-panic`. Did you mean `should_panic`?
250 3 | | /// ```should-panic
251 4 | | /// assert_eq!(1, 2);
255 = note: `#[warn(rustdoc::invalid_codeblock_attributes)]` on by default
256 = 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
259 In the example above, the correct form is `should_panic`. This helps detect
260 typo mistakes for some common attributes.
262 ## `invalid_html_tags`
264 This lint **warns by default**. It detects unclosed
265 or invalid HTML tags. For example:
268 #![warn(rustdoc::invalid_html_tags)]
278 warning: unopened HTML tag `script`
285 note: the lint level is defined here
288 1 | #![warn(rustdoc::invalid_html_tags)]
289 | ^^^^^^^^^^^^^^^^^^^^^^^^^^
291 warning: unclosed HTML tag `h1`
298 warning: 2 warnings emitted
301 ## `invalid_rust_codeblocks`
303 This lint **warns by default**. It detects Rust code blocks in documentation
304 examples that are invalid (e.g. empty, not parsable as Rust). For example:
307 /// Empty code blocks (with and without the `rust` marker):
312 /// Invalid syntax in code blocks:
323 warning: Rust code block is empty
331 = note: `#[warn(rustdoc::invalid_rust_codeblocks)]` on by default
333 warning: could not parse code block as Rust code
342 = note: error from rustc: unterminated character literal
347 This lint is **warn-by-default**. It detects URLs which are not links.
351 #![warn(rustdoc::bare_urls)] // note: unnecessary - warns by default.
353 /// http://example.org
354 /// [http://example.net]
361 warning: this URL is not a hyperlink
364 1 | /// http://example.org
365 | ^^^^^^^^^^^^^^^^^^ help: use an automatic link instead: `<http://example.org>`
367 = note: `#[warn(rustdoc::bare_urls)]` on by default
369 warning: this URL is not a hyperlink
372 3 | /// [http://example.net]
373 | ^^^^^^^^^^^^^^^^^^ help: use an automatic link instead: `<http://example.net>`
375 warning: 2 warnings emitted