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]: 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 /// [private]
  74 pub fn public() {}
  75 fn private() {}
  76 ```
  77
  78 This gives a warning that the link will be broken when it appears in your documentation:
  79
  80 ```text
  81 warning: public documentation for `public` links to private item `private`
  82  --> priv.rs:1:6
  83   |
  84 1 | /// [private]
  85   |      ^^^^^^^ this item is private
  86   |
  87   = note: `#[warn(rustdoc::private_intra_doc_links)]` on by default
  88   = note: this link will resolve properly if you pass `--document-private-items`
  89 ```
  90
  91 Note that this has different behavior depending on whether you pass `--document-private-items` or not!
  92 If you document private items, then it will still generate a link, despite the warning:
  93
  94 ```text
  95 warning: public documentation for `public` links to private item `private`
  96  --> priv.rs:1:6
  97   |
  98 1 | /// [private]
  99   |      ^^^^^^^ this item is private
 100   |
 101   = note: `#[warn(rustdoc::private_intra_doc_links)]` on by default
 102   = note: this link resolves only because you passed `--document-private-items`, but will break without
 103 ```
 104
 105 [intra-doc links]: linking-to-items-by-name.html
 106
 107 ## missing_docs
 108
 109 This lint is **allowed by default**. It detects items missing documentation.
 110 For example:
 111
 112 ```rust
 113 #![warn(missing_docs)]
 114
 115 pub fn undocumented() {}
 116 # fn main() {}
 117 ```
 118
 119 The `undocumented` function will then have the following warning:
 120
 121 ```text
 122 warning: missing documentation for a function
 123   --> your-crate/lib.rs:3:1
 124    |
 125  3 | pub fn undocumented() {}
 126    | ^^^^^^^^^^^^^^^^^^^^^
 127 ```
 128
 129 Note that unlike other rustdoc lints, this lint is also available from `rustc` directly.
 130
 131 ## missing_crate_level_docs
 132
 133 This lint is **allowed by default**. It detects if there is no documentation
 134 at the crate root. For example:
 135
 136 ```rust
 137 #![warn(rustdoc::missing_crate_level_docs)]
 138 ```
 139
 140 This will generate the following warning:
 141
 142 ```text
 143 warning: no documentation found for this crate's top-level module
 144   |
 145   = help: The following guide may be of use:
 146           https://doc.rust-lang.org/nightly/rustdoc/how-to-write-documentation.html
 147 ```
 148
 149 This is currently "allow" by default, but it is intended to make this a
 150 warning in the future. This is intended as a means to introduce new users on
 151 *how* to document their crate by pointing them to some instructions on how to
 152 get started, without providing overwhelming warnings like `missing_docs`
 153 might.
 154
 155 ## missing_doc_code_examples
 156
 157 This lint is **allowed by default** and is **nightly-only**. It detects when a documentation block
 158 is missing a code example. For example:
 159
 160 ```rust
 161 #![warn(rustdoc::missing_doc_code_examples)]
 162
 163 /// There is no code example!
 164 pub fn no_code_example() {}
 165 # fn main() {}
 166 ```
 167
 168 The `no_code_example` function will then have the following warning:
 169
 170 ```text
 171 warning: Missing code example in this documentation
 172   --> your-crate/lib.rs:3:1
 173    |
 174 LL | /// There is no code example!
 175    | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 176 ```
 177
 178 To fix the lint, you need to add a code example into the documentation block:
 179
 180 ```rust
 181 /// There is no code example!
 182 ///
 183 /// ```
 184 /// println!("calling no_code_example...");
 185 /// no_code_example();
 186 /// println!("we called no_code_example!");
 187 /// ```
 188 pub fn no_code_example() {}
 189 ```
 190
 191 ## private_doc_tests
 192
 193 This lint is **allowed by default**. It detects documentation tests when they
 194 are on a private item. For example:
 195
 196 ```rust
 197 #![warn(rustdoc::private_doc_tests)]
 198
 199 mod foo {
 200     /// private doc test
 201     ///
 202     /// ```
 203     /// assert!(false);
 204     /// ```
 205     fn bar() {}
 206 }
 207 # fn main() {}
 208 ```
 209
 210 Which will give:
 211
 212 ```text
 213 warning: Documentation test in private item
 214   --> your-crate/lib.rs:4:1
 215    |
 216  4 | /     /// private doc test
 217  5 | |     ///
 218  6 | |     /// ```
 219  7 | |     /// assert!(false);
 220  8 | |     /// ```
 221    | |___________^
 222 ```
 223
 224 ## invalid_codeblock_attributes
 225
 226 This lint **warns by default**. It detects code block attributes in
 227 documentation examples that have potentially mis-typed values. For example:
 228
 229 ```rust
 230 /// Example.
 231 ///
 232 /// ```should-panic
 233 /// assert_eq!(1, 2);
 234 /// ```
 235 pub fn foo() {}
 236 ```
 237
 238 Which will give:
 239
 240 ```text
 241 warning: unknown attribute `should-panic`. Did you mean `should_panic`?
 242  --> src/lib.rs:1:1
 243   |
 244 1 | / /// Example.
 245 2 | | ///
 246 3 | | /// ```should-panic
 247 4 | | /// assert_eq!(1, 2);
 248 5 | | /// ```
 249   | |_______^
 250   |
 251   = note: `#[warn(rustdoc::invalid_codeblock_attributes)]` on by default
 252   = 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
 253 ```
 254
 255 In the example above, the correct form is `should_panic`. This helps detect
 256 typo mistakes for some common attributes.
 257
 258 ## invalid_html_tags
 259
 260 This lint is **allowed by default** and is **nightly-only**. It detects unclosed
 261 or invalid HTML tags. For example:
 262
 263 ```rust
 264 #![warn(rustdoc::invalid_html_tags)]
 265
 266 /// <h1>
 267 /// </script>
 268 pub fn foo() {}
 269 ```
 270
 271 Which will give:
 272
 273 ```text
 274 warning: unopened HTML tag `script`
 275  --> foo.rs:1:1
 276   |
 277 1 | / /// <h1>
 278 2 | | /// </script>
 279   | |_____________^
 280   |
 281   note: the lint level is defined here
 282  --> foo.rs:1:9
 283   |
 284 1 | #![warn(rustdoc::invalid_html_tags)]
 285   |         ^^^^^^^^^^^^^^^^^^^^^^^^^^
 286
 287 warning: unclosed HTML tag `h1`
 288  --> foo.rs:1:1
 289   |
 290 1 | / /// <h1>
 291 2 | | /// </script>
 292   | |_____________^
 293
 294 warning: 2 warnings emitted
 295 ```
 296
 297 ## bare_urls
 298
 299 This lint is **warn-by-default**. It detects URLs which are not links.
 300 For example:
 301
 302 ```rust
 303 /// http://example.org
 304 /// [http://example.net]
 305 pub fn foo() {}
 306 ```
 307
 308 Which will give:
 309
 310 ```text
 311 warning: this URL is not a hyperlink
 312  --> links.rs:1:5
 313   |
 314 1 | /// http://example.org
 315   |     ^^^^^^^^^^^^^^^^^^ help: use an automatic link instead: `<http://example.org>`
 316   |
 317   = note: `#[warn(rustdoc::bare_urls)]` on by default
 318
 319 warning: this URL is not a hyperlink
 320  --> links.rs:3:6
 321   |
 322 3 | /// [http://example.net]
 323   |      ^^^^^^^^^^^^^^^^^^ help: use an automatic link instead: `<http://example.net>`
 324
 325 warning: 2 warnings emitted
 326 ```