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