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