src/doc/rustdoc/src/lints.md

   1 # Lints
   2
   3 `rustdoc` provides lints to help you writing and testing your documentation. You
   4 can 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
  12 Note that, except for `missing_docs`, these lints are only available when running `rustdoc`, not `rustc`.
  13
  14 Here is the list of the lints provided by `rustdoc`:
  15
  16 ## `broken_intra_doc_links`
  17
  18 This lint **warns by default**. This lint detects when an [intra-doc link] fails to be resolved. For example:
  19
  20 [intra-doc link]: write-documentation/linking-to-items-by-name.md
  21
  22 ```rust
  23 /// I want to link to [`Nonexistent`] but it doesn't exist!
  24 pub fn foo() {}
  25 ```
  26
  27 You'll get a warning saying:
  28
  29 ```text
  30 warning: unresolved link to `Nonexistent`
  31  --> test.rs:1:24
  32   |
  33 1 | /// I want to link to [`Nonexistent`] but it doesn't exist!
  34   |                        ^^^^^^^^^^^^^ no item named `Nonexistent` in `test`
  35 ```
  36
  37 It will also warn when there is an ambiguity and suggest how to disambiguate:
  38
  39 ```rust
  40 /// [`Foo`]
  41 pub fn function() {}
  42
  43 pub enum Foo {}
  44
  45 pub fn Foo(){}
  46 ```
  47
  48 ```text
  49 warning: `Foo` is both an enum and a function
  50  --> test.rs:1:6
  51   |
  52 1 | /// [`Foo`]
  53   |      ^^^^^ ambiguous link
  54   |
  55   = note: `#[warn(rustdoc::broken_intra_doc_links)]` on by default
  56 help: to link to the enum, prefix with the item type
  57   |
  58 1 | /// [`enum@Foo`]
  59   |      ^^^^^^^^^^
  60 help: to link to the function, add parentheses
  61   |
  62 1 | /// [`Foo()`]
  63   |      ^^^^^^^
  64
  65 ```
  66
  67 ## `private_intra_doc_links`
  68
  69 This lint **warns by default**. This lint detects when [intra-doc links] from public to private items.
  70 For example:
  71
  72 ```rust
  73 #![warn(rustdoc::private_intra_doc_links)] // note: unnecessary - warns by default.
  74
  75 /// [private]
  76 pub fn public() {}
  77 fn private() {}
  78 ```
  79
  80 This gives a warning that the link will be broken when it appears in your documentation:
  81
  82 ```text
  83 warning: public documentation for `public` links to private item `private`
  84  --> priv.rs:1:6
  85   |
  86 1 | /// [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
  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:
  95
  96 ```text
  97 warning: public documentation for `public` links to private item `private`
  98  --> priv.rs:1:6
  99   |
 100 1 | /// [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]: write-documentation/linking-to-items-by-name.md
 108
 109 ## `missing_docs`
 110
 111 This lint is **allowed by default**. It detects items missing documentation.
 112 For example:
 113
 114 ```rust
 115 #![warn(missing_docs)]
 116
 117 pub fn undocumented() {}
 118 # fn main() {}
 119 ```
 120
 121 The `undocumented` function will then have the following warning:
 122
 123 ```text
 124 warning: missing documentation for a function
 125   --> your-crate/lib.rs:3:1
 126    |
 127  3 | pub fn undocumented() {}
 128    | ^^^^^^^^^^^^^^^^^^^^^
 129 ```
 130
 131 Note that unlike other rustdoc lints, this lint is also available from `rustc` directly.
 132
 133 ## `missing_crate_level_docs`
 134
 135 This lint is **allowed by default**. It detects if there is no documentation
 136 at the crate root. For example:
 137
 138 ```rust
 139 #![warn(rustdoc::missing_crate_level_docs)]
 140 ```
 141
 142 This will generate the following warning:
 143
 144 ```text
 145 warning: 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
 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`
 155 might.
 156
 157 ## `missing_doc_code_examples`
 158
 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:
 161
 162 ```rust
 163 #![warn(rustdoc::missing_doc_code_examples)]
 164
 165 /// There is no code example!
 166 pub fn no_code_example() {}
 167 # fn main() {}
 168 ```
 169
 170 The `no_code_example` function will then have the following warning:
 171
 172 ```text
 173 warning: Missing code example in this documentation
 174   --> your-crate/lib.rs:3:1
 175    |
 176 LL | /// There is no code example!
 177    | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 178 ```
 179
 180 To 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 /// ```
 190 pub fn no_code_example() {}
 191 ```
 192
 193 ## `private_doc_tests`
 194
 195 This lint is **allowed by default**. It detects documentation tests when they
 196 are on a private item. For example:
 197
 198 ```rust
 199 #![warn(rustdoc::private_doc_tests)]
 200
 201 mod foo {
 202     /// private doc test
 203     ///
 204     /// ```
 205     /// assert!(false);
 206     /// ```
 207     fn bar() {}
 208 }
 209 # fn main() {}
 210 ```
 211
 212 Which will give:
 213
 214 ```text
 215 warning: 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
 228 This lint **warns by default**. It detects code block attributes in
 229 documentation 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 /// ```
 239 pub fn foo() {}
 240 ```
 241
 242 Which will give:
 243
 244 ```text
 245 warning: unknown attribute `should-panic`. Did you mean `should_panic`?
 246  --> src/lib.rs:1:1
 247   |
 248 1 | / /// Example.
 249 2 | | ///
 250 3 | | /// ```should-panic
 251 4 | | /// assert_eq!(1, 2);
 252 5 | | /// ```
 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
 259 In the example above, the correct form is `should_panic`. This helps detect
 260 typo mistakes for some common attributes.
 261
 262 ## `invalid_html_tags`
 263
 264 This lint **warns by default**. It detects unclosed
 265 or invalid HTML tags. For example:
 266
 267 ```rust
 268 #![warn(rustdoc::invalid_html_tags)]
 269
 270 /// <h1>
 271 /// </script>
 272 pub fn foo() {}
 273 ```
 274
 275 Which will give:
 276
 277 ```text
 278 warning: unopened HTML tag `script`
 279  --> foo.rs:1:1
 280   |
 281 1 | / /// <h1>
 282 2 | | /// </script>
 283   | |_____________^
 284   |
 285   note: the lint level is defined here
 286  --> foo.rs:1:9
 287   |
 288 1 | #![warn(rustdoc::invalid_html_tags)]
 289   |         ^^^^^^^^^^^^^^^^^^^^^^^^^^
 290
 291 warning: unclosed HTML tag `h1`
 292  --> foo.rs:1:1
 293   |
 294 1 | / /// <h1>
 295 2 | | /// </script>
 296   | |_____________^
 297
 298 warning: 2 warnings emitted
 299 ```
 300
 301 ## `invalid_rust_codeblocks`
 302
 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:
 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 /// ```
 317 pub fn foo() {}
 318 ```
 319
 320 Which will give:
 321
 322 ```text
 323 warning: Rust code block is empty
 324  --> lint.rs:3:5
 325   |
 326 3 |   /// ```rust
 327   |  _____^
 328 4 | | /// ```
 329   | |_______^
 330   |
 331   = note: `#[warn(rustdoc::invalid_rust_codeblocks)]` on by default
 332
 333 warning: could not parse code block as Rust code
 334   --> lint.rs:8:5
 335    |
 336 8  |   /// ```rust
 337    |  _____^
 338 9  | | /// '<
 339 10 | | /// ```
 340    | |_______^
 341    |
 342    = note: error from rustc: unterminated character literal
 343 ```
 344
 345 ## `bare_urls`
 346
 347 This lint is **warn-by-default**. It detects URLs which are not links.
 348 For example:
 349
 350 ```rust
 351 #![warn(rustdoc::bare_urls)] // note: unnecessary - warns by default.
 352
 353 /// http://example.org
 354 /// [http://example.net]
 355 pub fn foo() {}
 356 ```
 357
 358 Which will give:
 359
 360 ```text
 361 warning: this URL is not a hyperlink
 362  --> links.rs:1:5
 363   |
 364 1 | /// http://example.org
 365   |     ^^^^^^^^^^^^^^^^^^ help: use an automatic link instead: `<http://example.org>`
 366   |
 367   = note: `#[warn(rustdoc::bare_urls)]` on by default
 368
 369 warning: this URL is not a hyperlink
 370  --> links.rs:3:6
 371   |
 372 3 | /// [http://example.net]
 373   |      ^^^^^^^^^^^^^^^^^^ help: use an automatic link instead: `<http://example.net>`
 374
 375 warning: 2 warnings emitted
 376 ```