Documentation Lints

Documentation lints ensure public API items have rustdoc comments and valid doc links. Enable missing_docs for libraries consumers depend on.

Recipe

[lints.rust]
missing_docs = "warn"
broken_intra_doc_links = "deny"

/// Returns the user id.
///
/// # Errors
///
/// Fails when the id is not found.
pub fn user_id() -> Result<u64, Error> { todo!() }

When to reach for this: Published crates, internal platform libraries, and any pub API surface.

Working Example

[lints.rust]
missing_docs = "warn"
unsafe_code = "forbid"

//! Crate-level documentation for `orders`.
//!
//! # Examples
//!
//! ```
//! use orders::Client;
//! ```
 
/// HTTP client for the orders API.
pub struct Client;

cargo doc --no-deps --document-private-items
RUSTDOCFLAGS="-D warnings" cargo doc --no-deps

What this demonstrates:

//! documents the crate/module
/// documents the following item
# Errors, # Panics, # Safety sections expected by API guidelines
RUSTDOCFLAGS="-D warnings" fails on broken links in CI

Deep Dive

Key Doc Lints

Lint	Catches
`missing_docs`	Undocumented `pub` items
`broken_intra_doc_links`	`[WrongType]` links
`missing_crate_level_docs`	Empty crate root docs
`invalid_html`	Bad tags in docs

rustdoc Sections

Examples - doctest or no_run
Errors - Result variants
Safety - required for pub unsafe fn

Gotchas

Documenting every private fn - noise. Fix: missing_docs targets pub by default policy; allow private modules.
Broken links after rename - doc CI fails. Fix: RUSTDOCFLAGS="-D warnings" on PRs.
Empty doc comments - satisfy lint without value. Fix: review for one-line purpose + errors.
Unsafe without Safety section - rustdoc warning. Fix: mandatory template for unsafe API.
Examples that do not compile - doctests fail. Fix: cargo test --doc in CI.

Alternatives

Alternative	Use When	Don't Use When
`warn` vs `deny` missing_docs	Gradual adoption	Greenfield public crate
External mdbook only	Narrative guides	Replacing API reference
`#[doc(hidden)]`	Internal re-exports	Hiding public API mistakes

FAQs

missing_docs on binaries?

Often relaxed; focus on library crates in workspace.

How document errors?

List each Error variant behavior under # Errors with when it occurs.

Doctest in every pub fn?

Not required; at least one crate example and doctests on complex APIs.

How fix intra-doc links?

Use full path [Client](Client) same module or [super::foo] paths rustdoc resolves.

docs.rs vs local doc lints?

Same rustdoc; CI cargo doc catches issues before publish.

Document enums?

Document enum and each variant if public, especially error enums.

What about re-exports?

#[doc(inline)] on pub use shows docs at re-export site.

missing_docs in tests?

Usually N/A for test modules; public test helpers in integration crates should be documented or kept private.

How enforce in workspace?

Shared [lints.rust] missing_docs = "warn" in each lib Cargo.toml or workspace lint inheritance pattern.

Document unsafe traits?

# Safety on trait and implementations explaining invariants maintainers must uphold.

Doctests - executable examples
Lint Levels & Attributes - lint levels
Rust API Guidelines - doc conventions
Documentation Conventions - team style

Stack versions: This page was written for Rust 1.97.0 (edition 2024), Tokio 1.x, Axum 0.8, serde 1.0, sqlx 0.8, clap 4, and Polars 0.46+.

Documentation Lints

Documentation lints ensure public API items have rustdoc comments and valid doc links. Enable missing_docs for libraries consumers depend on.

Recipe

[lints.rust]
missing_docs = "warn"
broken_intra_doc_links = "deny"

/// Returns the user id.
///
/// # Errors
///
/// Fails when the id is not found.
pub fn user_id() -> Result<u64, Error> { todo!() }

When to reach for this: Published crates, internal platform libraries, and any pub API surface.

Working Example

[lints.rust]
missing_docs = "warn"
unsafe_code = "forbid"

//! Crate-level documentation for `orders`.
//!
//! # Examples
//!
//! ```
//! use orders::Client;
//! ```
 
/// HTTP client for the orders API.
pub struct Client;

cargo doc --no-deps --document-private-items
RUSTDOCFLAGS="-D warnings" cargo doc --no-deps

What this demonstrates:

//! documents the crate/module
/// documents the following item
# Errors, # Panics, # Safety sections expected by API guidelines
RUSTDOCFLAGS="-D warnings" fails on broken links in CI

Deep Dive

Key Doc Lints

Lint	Catches
`missing_docs`	Undocumented `pub` items
`broken_intra_doc_links`	`[WrongType]` links
`missing_crate_level_docs`	Empty crate root docs
`invalid_html`	Bad tags in docs

rustdoc Sections

Examples - doctest or no_run
Errors - Result variants
Safety - required for pub unsafe fn

Gotchas

Documenting every private fn - noise. Fix: missing_docs targets pub by default policy; allow private modules.
Broken links after rename - doc CI fails. Fix: RUSTDOCFLAGS="-D warnings" on PRs.
Empty doc comments - satisfy lint without value. Fix: review for one-line purpose + errors.
Unsafe without Safety section - rustdoc warning. Fix: mandatory template for unsafe API.
Examples that do not compile - doctests fail. Fix: cargo test --doc in CI.

Alternatives

Alternative	Use When	Don't Use When
`warn` vs `deny` missing_docs	Gradual adoption	Greenfield public crate
External mdbook only	Narrative guides	Replacing API reference
`#[doc(hidden)]`	Internal re-exports	Hiding public API mistakes

FAQs

missing_docs on binaries?

Often relaxed; focus on library crates in workspace.

How document errors?

List each Error variant behavior under # Errors with when it occurs.

Doctest in every pub fn?

Not required; at least one crate example and doctests on complex APIs.

How fix intra-doc links?

Use full path [Client](Client) same module or [super::foo] paths rustdoc resolves.

docs.rs vs local doc lints?

Same rustdoc; CI cargo doc catches issues before publish.

Document enums?

Document enum and each variant if public, especially error enums.

What about re-exports?

#[doc(inline)] on pub use shows docs at re-export site.

missing_docs in tests?

Usually N/A for test modules; public test helpers in integration crates should be documented or kept private.

How enforce in workspace?

Shared [lints.rust] missing_docs = "warn" in each lib Cargo.toml or workspace lint inheritance pattern.

Document unsafe traits?

# Safety on trait and implementations explaining invariants maintainers must uphold.

Doctests - executable examples
Lint Levels & Attributes - lint levels
Rust API Guidelines - doc conventions
Documentation Conventions - team style

Stack versions: This page was written for Rust 1.97.0 (edition 2024), Tokio 1.x, Axum 0.8, serde 1.0, sqlx 0.8, clap 4, and Polars 0.46+.

Documentation Lints

Buscar en la documentación

Documentation Lints