🎓 A1Learner
🔍

Rust Rustdoc Lints

Rustdoc lints are warnings about documentation. One lint flags a link to nowhere.

Turn a lint on

At the crate root, ask for a warning on every undocumented public item:

#![warn(missing_docs)]

A broken link

This link names an item that does not exist, so cargo doc warns about it:

/// Links to [`NoSuchItem`].
pub fn broken() {}

A link readers cannot follow

Public docs that link to a private item warn too — the reader's pages have no such page to land on:

fn helper() {}
/// Uses [`helper`].
pub fn public_fn() {}

A bare web address

A plain address in a comment is not a link. Rustdoc warns, and angle brackets fix it:

/// See https://example.org for more.
/// Better: see <https://example.org>.

Example

//! Tiny calculator functions.
#![warn(missing_docs)]
/// Adds two numbers.
pub fn add(a: i32, b: i32) -> i32 { a + b }
pub fn sub(a: i32, b: i32) -> i32 { a - b }
fn main() { println!("add = {} sub = {}", add(5, 2), sub(5, 2)); }

Key points

  • A rustdoc lint is a warning about the documentation, not about the program code.
  • Most rustdoc lints run only when rustdoc runs (cargo doc, cargo test --doc).
  • They do not run on a normal build.
  • missing_docs is the exception.
  • rustc knows it too.
  • rustdoc::private_intra_doc_links warns by default when public docs link to a private item.
  • Readers would land on a page their docs do not have.
  • rustdoc::missing_crate_level_docs checks only the front page: it warns when the crate root has no //! documentation at all
  • rustdoc::invalid_codeblock_attributes warns by default about mistyped fence words — ```should-panic earns a “Did you mean should_panic?” note, and the block may be skipped as a test
  • rustdoc::invalid_rust_codeblocks and rustdoc::invalid_html_tags warn by default about empty or unparsable code blocks and unclosed HTML tags inside comments

In this example, the crate root turns on missing_docs. The crate itself has a //! line and add has a /// line, so both stay quiet. sub has no comment at all, so the compiler warns: missing documentation for a function, pointing at sub. The warning does not stop the program — main still runs and prints add = 7 sub = 3. Change warn to deny and the same missing comment would fail the build.

Note

A warning nobody sees fixes nothing.

The standard cure is the previous lesson's trick.

Deny warnings for cargo doc in CI.

Doc problems then fail the build like code problems.

Try it Yourself

Edit the code, then press Run.

Running is simulated · Rust Playground

Exercise

Which lint warns when a doc comment links to an item that does not exist?