rustdoc
provides lints to help you writing and testing your documentation. You can use them like any other lints by doing this:
#![allow(missing_docs)] // allowing the lint, no message #![warn(missing_docs)] // warn if there is missing docs #![deny(missing_docs)] // rustdoc will fail if there is missing docs
Here is the list of the lints provided by rustdoc
:
This lint warns by default. This lint detects when an intra-doc link fails to get resolved. For example:
/// I want to link to [`Nonexistent`] but it doesn't exist! pub fn foo() {}
You'll get a warning saying:
warning: unresolved link to `Nonexistent` --> test.rs:1:24 | 1 | /// I want to link to [`Nonexistent`] but it doesn't exist! | ^^^^^^^^^^^^^ no item named `Nonexistent` in `test`
It will also warn when there is an ambiguity and suggest how to disambiguate:
/// [`Foo`] pub fn function() {} pub enum Foo {} pub fn Foo(){}
warning: `Foo` is both an enum and a function --> test.rs:1:6 | 1 | /// [`Foo`] | ^^^^^ ambiguous link | = note: `#[warn(broken_intra_doc_links)]` on by default help: to link to the enum, prefix with the item type | 1 | /// [`enum@Foo`] | ^^^^^^^^^^ help: to link to the function, add parentheses | 1 | /// [`Foo()`] | ^^^^^^^
This lint warns by default. This lint detects when intra-doc links from public to private items. For example:
/// [private] pub fn public() {} fn private() {}
This gives a warning that the link will be broken when it appears in your documentation:
warning: public documentation for `public` links to private item `private` --> priv.rs:1:6 | 1 | /// [private] | ^^^^^^^ this item is private | = note: `#[warn(private_intra_doc_links)]` on by default = note: this link will resolve properly if you pass `--document-private-items`
Note that this has different behavior depending on whether you pass --document-private-items
or not! If you document private items, then it will still generate a link, despite the warning:
warning: public documentation for `public` links to private item `private` --> priv.rs:1:6 | 1 | /// [private] | ^^^^^^^ this item is private | = note: `#[warn(private_intra_doc_links)]` on by default = note: this link resolves only because you passed `--document-private-items`, but will break without
This lint is allowed by default. It detects items missing documentation. For example:
#![warn(missing_docs)] pub fn undocumented() {} # fn main() {}
The undocumented
function will then have the following warning:
warning: missing documentation for a function --> your-crate/lib.rs:3:1 | 3 | pub fn undocumented() {} | ^^^^^^^^^^^^^^^^^^^^^
This lint is allowed by default. It detects if there is no documentation at the crate root. For example:
#![warn(missing_crate_level_docs)]
This will generate the following warning:
warning: no documentation found for this crate's top-level module | = help: The following guide may be of use: https://doc.rust-lang.org/nightly/rustdoc/how-to-write-documentation.html
This is currently “allow” by default, but it is intended to make this a warning in the future. This is intended as a means to introduce new users on how to document their crate by pointing them to some instructions on how to get started, without providing overwhelming warnings like missing_docs
might.
This lint is allowed by default and is nightly-only. It detects when a documentation block is missing a code example. For example:
#![warn(missing_doc_code_examples)] /// There is no code example! pub fn no_code_example() {} # fn main() {}
The no_code_example
function will then have the following warning:
warning: Missing code example in this documentation --> your-crate/lib.rs:3:1 | LL | /// There is no code example! | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
To fix the lint, you need to add a code example into the documentation block:
/// There is no code example! /// /// ``` /// println!("calling no_code_example..."); /// no_code_example(); /// println!("we called no_code_example!"); /// ``` pub fn no_code_example() {}
This lint is allowed by default. It detects documentation tests when they are on a private item. For example:
#![warn(private_doc_tests)] mod foo { /// private doc test /// /// ``` /// assert!(false); /// ``` fn bar() {} } # fn main() {}
Which will give:
warning: Documentation test in private item --> your-crate/lib.rs:4:1 | 4 | / /// private doc test 5 | | /// 6 | | /// ``` 7 | | /// assert!(false); 8 | | /// ``` | |___________^
This lint warns by default. It detects code block attributes in documentation examples that have potentially mis-typed values. For example:
/// Example. /// /// ```should-panic /// assert_eq!(1, 2); /// ``` pub fn foo() {}
Which will give:
warning: unknown attribute `should-panic`. Did you mean `should_panic`? --> src/lib.rs:1:1 | 1 | / /// Example. 2 | | /// 3 | | /// ```should-panic 4 | | /// assert_eq!(1, 2); 5 | | /// ``` | |_______^ | = note: `#[warn(invalid_codeblock_attributes)]` on by default = 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
In the example above, the correct form is should_panic
. This helps detect typo mistakes for some common attributes.