1# Lints
2
3`rustdoc` provides lints to help you writing and testing your documentation. You
4can use them like any other lints by doing this:
5
6```rust
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
10```
11
12Note that, except for `missing_docs`, these lints are only available when running `rustdoc`, not `rustc`.
13
14Here is the list of the lints provided by `rustdoc`:
15
16## broken_intra_doc_links
17
18This lint **warns by default**. This lint detects when an [intra-doc link] fails to be resolved. For example:
19
20[intra-doc link]: linking-to-items-by-name.md
21
22```rust
23/// I want to link to [`Nonexistent`] but it doesn't exist!
24pub fn foo() {}
25```
26
27You'll get a warning saying:
28
29```text
30warning: unresolved link to `Nonexistent`
31 --> test.rs:1:24
32  |
331 | /// I want to link to [`Nonexistent`] but it doesn't exist!
34  |                        ^^^^^^^^^^^^^ no item named `Nonexistent` in `test`
35```
36
37It will also warn when there is an ambiguity and suggest how to disambiguate:
38
39```rust
40/// [`Foo`]
41pub fn function() {}
42
43pub enum Foo {}
44
45pub fn Foo(){}
46```
47
48```text
49warning: `Foo` is both an enum and a function
50 --> test.rs:1:6
51  |
521 | /// [`Foo`]
53  |      ^^^^^ ambiguous link
54  |
55  = note: `#[warn(rustdoc::broken_intra_doc_links)]` on by default
56help: to link to the enum, prefix with the item type
57  |
581 | /// [`enum@Foo`]
59  |      ^^^^^^^^^^
60help: to link to the function, add parentheses
61  |
621 | /// [`Foo()`]
63  |      ^^^^^^^
64
65```
66
67## private_intra_doc_links
68
69This lint **warns by default**. This lint detects when [intra-doc links] from public to private items.
70For example:
71
72```rust
73#![warn(rustdoc::private_intra_doc_links)] // note: unnecessary - warns by default.
74
75/// [private]
76pub fn public() {}
77fn private() {}
78```
79
80This gives a warning that the link will be broken when it appears in your documentation:
81
82```text
83warning: public documentation for `public` links to private item `private`
84 --> priv.rs:1:6
85  |
861 | /// [private]
87  |      ^^^^^^^ this item is private
88  |
89  = note: `#[warn(rustdoc::private_intra_doc_links)]` on by default
90  = note: this link will resolve properly if you pass `--document-private-items`
91```
92
93Note that this has different behavior depending on whether you pass `--document-private-items` or not!
94If you document private items, then it will still generate a link, despite the warning:
95
96```text
97warning: public documentation for `public` links to private item `private`
98 --> priv.rs:1:6
99  |
1001 | /// [private]
101  |      ^^^^^^^ this item is private
102  |
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
105```
106
107[intra-doc links]: linking-to-items-by-name.html
108
109## missing_docs
110
111This lint is **allowed by default**. It detects items missing documentation.
112For example:
113
114```rust
115#![warn(missing_docs)]
116
117pub fn undocumented() {}
118# fn main() {}
119```
120
121The `undocumented` function will then have the following warning:
122
123```text
124warning: missing documentation for a function
125  --> your-crate/lib.rs:3:1
126   |
127 3 | pub fn undocumented() {}
128   | ^^^^^^^^^^^^^^^^^^^^^
129```
130
131Note that unlike other rustdoc lints, this lint is also available from `rustc` directly.
132
133## missing_crate_level_docs
134
135This lint is **allowed by default**. It detects if there is no documentation
136at the crate root. For example:
137
138```rust
139#![warn(rustdoc::missing_crate_level_docs)]
140```
141
142This will generate the following warning:
143
144```text
145warning: no documentation found for this crate's top-level module
146  |
147  = help: The following guide may be of use:
148          https://doc.rust-lang.org/nightly/rustdoc/how-to-write-documentation.html
149```
150
151This is currently "allow" by default, but it is intended to make this a
152warning 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
154get started, without providing overwhelming warnings like `missing_docs`
155might.
156
157## missing_doc_code_examples
158
159This lint is **allowed by default** and is **nightly-only**. It detects when a documentation block
160is missing a code example. For example:
161
162```rust
163#![warn(rustdoc::missing_doc_code_examples)]
164
165/// There is no code example!
166pub fn no_code_example() {}
167# fn main() {}
168```
169
170The `no_code_example` function will then have the following warning:
171
172```text
173warning: Missing code example in this documentation
174  --> your-crate/lib.rs:3:1
175   |
176LL | /// There is no code example!
177   | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
178```
179
180To fix the lint, you need to add a code example into the documentation block:
181
182```rust
183/// There is no code example!
184///
185/// ```
186/// println!("calling no_code_example...");
187/// no_code_example();
188/// println!("we called no_code_example!");
189/// ```
190pub fn no_code_example() {}
191```
192
193## private_doc_tests
194
195This lint is **allowed by default**. It detects documentation tests when they
196are on a private item. For example:
197
198```rust
199#![warn(rustdoc::private_doc_tests)]
200
201mod foo {
202    /// private doc test
203    ///
204    /// ```
205    /// assert!(false);
206    /// ```
207    fn bar() {}
208}
209# fn main() {}
210```
211
212Which will give:
213
214```text
215warning: Documentation test in private item
216  --> your-crate/lib.rs:4:1
217   |
218 4 | /     /// private doc test
219 5 | |     ///
220 6 | |     /// ```
221 7 | |     /// assert!(false);
222 8 | |     /// ```
223   | |___________^
224```
225
226## invalid_codeblock_attributes
227
228This lint **warns by default**. It detects code block attributes in
229documentation examples that have potentially mis-typed values. For example:
230
231```rust
232#![warn(rustdoc::invalid_codeblock_attributes)]  // note: unnecessary - warns by default.
233
234/// Example.
235///
236/// ```should-panic
237/// assert_eq!(1, 2);
238/// ```
239pub fn foo() {}
240```
241
242Which will give:
243
244```text
245warning: unknown attribute `should-panic`. Did you mean `should_panic`?
246 --> src/lib.rs:1:1
247  |
2481 | / /// Example.
2492 | | ///
2503 | | /// ```should-panic
2514 | | /// assert_eq!(1, 2);
2525 | | /// ```
253  | |_______^
254  |
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
257```
258
259In the example above, the correct form is `should_panic`. This helps detect
260typo mistakes for some common attributes.
261
262## invalid_html_tags
263
264This lint is **allowed by default** and is **nightly-only**. It detects unclosed
265or invalid HTML tags. For example:
266
267```rust
268#![warn(rustdoc::invalid_html_tags)]
269
270/// <h1>
271/// </script>
272pub fn foo() {}
273```
274
275Which will give:
276
277```text
278warning: unopened HTML tag `script`
279 --> foo.rs:1:1
280  |
2811 | / /// <h1>
2822 | | /// </script>
283  | |_____________^
284  |
285  note: the lint level is defined here
286 --> foo.rs:1:9
287  |
2881 | #![warn(rustdoc::invalid_html_tags)]
289  |         ^^^^^^^^^^^^^^^^^^^^^^^^^^
290
291warning: unclosed HTML tag `h1`
292 --> foo.rs:1:1
293  |
2941 | / /// <h1>
2952 | | /// </script>
296  | |_____________^
297
298warning: 2 warnings emitted
299```
300
301## invalid_rust_codeblocks
302
303This lint **warns by default**. It detects Rust code blocks in documentation
304examples that are invalid (e.g. empty, not parsable as Rust). For example:
305
306```rust
307/// Empty code blocks (with and without the `rust` marker):
308///
309/// ```rust
310/// ```
311///
312/// Invalid syntax in code blocks:
313///
314/// ```rust
315/// '<
316/// ```
317pub fn foo() {}
318```
319
320Which will give:
321
322```text
323warning: Rust code block is empty
324 --> lint.rs:3:5
325  |
3263 |   /// ```rust
327  |  _____^
3284 | | /// ```
329  | |_______^
330  |
331  = note: `#[warn(rustdoc::invalid_rust_codeblocks)]` on by default
332
333warning: could not parse code block as Rust code
334  --> lint.rs:8:5
335   |
3368  |   /// ```rust
337   |  _____^
3389  | | /// '<
33910 | | /// ```
340   | |_______^
341   |
342   = note: error from rustc: unterminated character literal
343```
344
345## bare_urls
346
347This lint is **warn-by-default**. It detects URLs which are not links.
348For example:
349
350```rust
351#![warn(rustdoc::bare_urls)] // note: unnecessary - warns by default.
352
353/// http://example.org
354/// [http://example.net]
355pub fn foo() {}
356```
357
358Which will give:
359
360```text
361warning: this URL is not a hyperlink
362 --> links.rs:1:5
363  |
3641 | /// http://example.org
365  |     ^^^^^^^^^^^^^^^^^^ help: use an automatic link instead: `<http://example.org>`
366  |
367  = note: `#[warn(rustdoc::bare_urls)]` on by default
368
369warning: this URL is not a hyperlink
370 --> links.rs:3:6
371  |
3723 | /// [http://example.net]
373  |      ^^^^^^^^^^^^^^^^^^ help: use an automatic link instead: `<http://example.net>`
374
375warning: 2 warnings emitted
376```
377