Skip to content

M0006 crate-docs

Rule: Every crate root opens with crate-level documentation.

Code M0006 (stable, never reused)
Id crate-docs
Category manifest
Source spirit_level
Fix by hand

Level per tier

Tier Level Reason
small warn rustdoc's front page of the crate is its crate-level docs
small-workspace warn rustdoc's front page of the crate is its crate-level docs
medium warn rustdoc's front page of the crate is its crate-level docs
big deny rustdoc's front page of the crate is its crate-level docs
ai off
embedded off
ui off
egui off
units-strict off
units-paranoid off

Why

The crate-level documentation (//! at the top of lib.rs or main.rs) is the front page rustdoc shows. Without it the crate's docs open on a bare item list. (rustdoc's own missing_crate_level_docs lint is off by default and only runs with cargo doc.)

How to fix

Start the crate root with //! lines: what the crate is for, the main types or functions, and a short example.

Configure

[lints.crate-docs]
level = "deny"
reason = "why this project wants it at this level"

Allow one finding in the code with // spirit-level: allow(crate-docs) <reason> (waivers); the code works there too, as in [lints.M0006].