Rust Tooling and Code Quality

cargo doc

The cargo doc command orchestrates rustdoc across a package or workspace to generate offline HTML documentation and validate documentation lints (rustdoc::*). Integrating cargo doc into local development and continuous integration ensures that public API docs stay warning-free and every intra-doc link resolves cleanly.

`cargo doc` Quality Gate in CI:
  RUSTDOCFLAGS="-D warnings" cargo doc --workspace --no-deps --all-features
        |
        +-- Checks `rustdoc::broken_intra_doc_links`
        +-- Checks `rustdoc::private_intra_doc_links`
        +-- Checks `rustdoc::bare_urls`
        +-- Checks `rustdoc::invalid_html_tags`
        +-- Checks `rustdoc::invalid_rust_codeblocks`

Built-In rustdoc::* Lints

rustdoc includes its own specialized lint group (rustdoc::all) distinct from rustc and clippy:

rustdoc Lint Default Level What It Catches
rustdoc::broken_intra_doc_links warn Unresolved [Item] links due to typos, missing imports, or renamed functions.
rustdoc::private_intra_doc_links warn A public item's doc comment linking to a private item that isn't rendered in public docs.
rustdoc::bare_urls warn Raw URLs (https://example.com) not enclosed in <https://...> or [link](https://...).
rustdoc::invalid_html_tags warn Unescaped <T> generic parameters in prose that were not wrapped in backticks `<T>` (causing browsers to parse <T> as an unknown HTML tag!).
rustdoc::invalid_rust_codeblocks warn Empty or syntactically malformed Rust code blocks in doc comments.
rustdoc::unescaped_backticks allow (opt-in) Detects mismatched backticks (`) in doc comments that corrupt code spans.

Catching Unescaped <T> HTML Tag Bugs in Doc Comments

One of the most common documentation mistakes in Rust is writing generic type syntax like Result<T, E> or Vec<u8> in prose without surrounding backticks. Without backticks, Markdown treats <T, E> and <u8> as raw inline HTML tags, making them invisible in the rendered webpage!

rustdoc::invalid_html_tags catches this automatically:

#![deny(rustdoc::all)]

/// Wraps a value of type `T` with a monotonic sequence number.
///
/// Always wrap generic types like `Sequenced<T>` or `Option<T>` in backticks
/// so `rustdoc` renders them as inline code rather than raw HTML tags.
#[derive(Debug, PartialEq, Eq)]
pub struct Sequenced<T> {
    /// Zero-based sequence index.
    pub seq: u64,
    /// Wrapped payload value.
    pub value: T,
}

fn main() {
    let item = Sequenced {
        seq: 1,
        value: "payload",
    };
    println!("Sequenced #{}: {}", item.seq, item.value);
}

Sequenced #1: payload

Configuring [lints.rustdoc] in Cargo.toml

Just like [lints.rust] and [lints.clippy], you can configure rustdoc lints declaratively in Cargo.toml so cargo doc enforces them without needing RUSTDOCFLAGS:

[lints.rustdoc]
broken_intra_doc_links = "deny"
private_intra_doc_links = "deny"
invalid_html_tags = "deny"
bare_urls = "warn"
unescaped_backticks = "warn"