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,ignore
   7 #![allow(missing_docs)] // allowing the lint, no message
   8 #![warn(missing_docs)] // warn if there is missing docs
   9 #![deny(missing_docs)] // rustdoc will fail if there is missing docs
  10 ```
  11
  12 Here is the list of the lints provided by `rustdoc`:
  13
  14 ## broken_intra_doc_links
  15
  16 This lint **warns by default**. This lint detects when an [intra-doc link] fails to get resolved. For example:
  17
  18  [intra-doc link]: linking-to-items-by-name.html
  19
  20 ```rust
  21 /// I want to link to [`Nonexistent`] but it doesn't exist!
  22 pub fn foo() {}
  23 ```
  24
  25 You'll get a warning saying:
  26
  27 ```text
  28 warning: unresolved link to `Nonexistent`
  29  --> test.rs:1:24
  30   |
  31 1 | /// I want to link to [`Nonexistent`] but it doesn't exist!
  32   |                        ^^^^^^^^^^^^^ no item named `Nonexistent` in `test`
  33 ```
  34
  35 It will also warn when there is an ambiguity and suggest how to disambiguate:
  36
  37 ```rust
  38 /// [`Foo`]
  39 pub fn function() {}
  40
  41 pub enum Foo {}
  42
  43 pub fn Foo(){}
  44 ```
  45
  46 ```text
  47 warning: `Foo` is both an enum and a function
  48  --> test.rs:1:6
  49   |
  50 1 | /// [`Foo`]
  51   |      ^^^^^ ambiguous link
  52   |
  53   = note: `#[warn(broken_intra_doc_links)]` on by default
  54 help: to link to the enum, prefix with the item type
  55   |
  56 1 | /// [`enum@Foo`]
  57   |      ^^^^^^^^^^
  58 help: to link to the function, add parentheses
  59   |
  60 1 | /// [`Foo()`]
  61   |      ^^^^^^^
  62
  63 ```
  64
  65 ## private_intra_doc_links
  66
  67 This lint **warns by default**. This lint detects when [intra-doc links] from public to private items.
  68 For example:
  69
  70 ```rust
  71 /// [private]
  72 pub fn public() {}
  73 fn private() {}
  74 ```
  75
  76 This gives a warning that the link will be broken when it appears in your documentation:
  77
  78 ```text
  79 warning: public documentation for `public` links to private item `private`
  80  --> priv.rs:1:6
  81   |
  82 1 | /// [private]
  83   |      ^^^^^^^ this item is private
  84   |
  85   = note: `#[warn(private_intra_doc_links)]` on by default
  86   = note: this link will resolve properly if you pass `--document-private-items`
  87 ```
  88
  89 Note that this has different behavior depending on whether you pass `--document-private-items` or not!
  90 If you document private items, then it will still generate a link, despite the warning:
  91
  92 ```text
  93 warning: public documentation for `public` links to private item `private`
  94  --> priv.rs:1:6
  95   |
  96 1 | /// [private]
  97   |      ^^^^^^^ this item is private
  98   |
  99   = note: `#[warn(private_intra_doc_links)]` on by default
 100   = note: this link resolves only because you passed `--document-private-items`, but will break without
 101 ```
 102
 103 [intra-doc links]: linking-to-items-by-name.html
 104
 105 ## missing_docs
 106
 107 This lint is **allowed by default**. It detects items missing documentation.
 108 For example:
 109
 110 ```rust
 111 #![warn(missing_docs)]
 112
 113 pub fn undocumented() {}
 114 # fn main() {}
 115 ```
 116
 117 The `undocumented` function will then have the following warning:
 118
 119 ```text
 120 warning: missing documentation for a function
 121   --> your-crate/lib.rs:3:1
 122    |
 123  3 | pub fn undocumented() {}
 124    | ^^^^^^^^^^^^^^^^^^^^^
 125 ```
 126
 127 ## missing_crate_level_docs
 128
 129 This lint is **allowed by default**. It detects if there is no documentation
 130 at the crate root. For example:
 131
 132 ```rust
 133 #![warn(missing_crate_level_docs)]
 134 ```
 135
 136 This will generate the following warning:
 137
 138 ```text
 139 warning: no documentation found for this crate's top-level module
 140   |
 141   = help: The following guide may be of use:
 142           https://doc.rust-lang.org/nightly/rustdoc/how-to-write-documentation.html
 143 ```
 144
 145 This is currently "allow" by default, but it is intended to make this a
 146 warning in the future. This is intended as a means to introduce new users on
 147 *how* to document their crate by pointing them to some instructions on how to
 148 get started, without providing overwhelming warnings like `missing_docs`
 149 might.
 150
 151 ## missing_doc_code_examples
 152
 153 This lint is **allowed by default** and is **nightly-only**. It detects when a documentation block
 154 is missing a code example. For example:
 155
 156 ```rust
 157 #![warn(missing_doc_code_examples)]
 158
 159 /// There is no code example!
 160 pub fn no_code_example() {}
 161 # fn main() {}
 162 ```
 163
 164 The `no_code_example` function will then have the following warning:
 165
 166 ```text
 167 warning: Missing code example in this documentation
 168   --> your-crate/lib.rs:3:1
 169    |
 170 LL | /// There is no code example!
 171    | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 172 ```
 173
 174 To fix the lint, you need to add a code example into the documentation block:
 175
 176 ```rust
 177 /// There is no code example!
 178 ///
 179 /// ```
 180 /// println!("calling no_code_example...");
 181 /// no_code_example();
 182 /// println!("we called no_code_example!");
 183 /// ```
 184 pub fn no_code_example() {}
 185 ```
 186
 187 ## private_doc_tests
 188
 189 This lint is **allowed by default**. It detects documentation tests when they
 190 are on a private item. For example:
 191
 192 ```rust
 193 #![warn(private_doc_tests)]
 194
 195 mod foo {
 196     /// private doc test
 197     ///
 198     /// ```
 199     /// assert!(false);
 200     /// ```
 201     fn bar() {}
 202 }
 203 # fn main() {}
 204 ```
 205
 206 Which will give:
 207
 208 ```text
 209 warning: Documentation test in private item
 210   --> your-crate/lib.rs:4:1
 211    |
 212  4 | /     /// private doc test
 213  5 | |     ///
 214  6 | |     /// ```
 215  7 | |     /// assert!(false);
 216  8 | |     /// ```
 217    | |___________^
 218 ```
 219
 220 ## invalid_codeblock_attributes
 221
 222 This lint **warns by default**. It detects code block attributes in
 223 documentation examples that have potentially mis-typed values. For example:
 224
 225 ```rust
 226 /// Example.
 227 ///
 228 /// ```should-panic
 229 /// assert_eq!(1, 2);
 230 /// ```
 231 pub fn foo() {}
 232 ```
 233
 234 Which will give:
 235
 236 ```text
 237 warning: unknown attribute `should-panic`. Did you mean `should_panic`?
 238  --> src/lib.rs:1:1
 239   |
 240 1 | / /// Example.
 241 2 | | ///
 242 3 | | /// ```should-panic
 243 4 | | /// assert_eq!(1, 2);
 244 5 | | /// ```
 245   | |_______^
 246   |
 247   = note: `#[warn(invalid_codeblock_attributes)]` on by default
 248   = 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
 249 ```
 250
 251 In the example above, the correct form is `should_panic`. This helps detect
 252 typo mistakes for some common attributes.