Skip to content

X0005 cargo-doc

Rule: Cargo doc builds the workspace's documentation without a warning.

Code X0005 (stable, never reused)
Id cargo-doc
Category build
Source cargo (run as an executable)
Fix by hand
Needs cargo installed

Level per tier

Tier Level Reason
small warn broken intra-doc links and tags render wrong on docs.rs and in the IDE
small-workspace warn broken intra-doc links and tags render wrong on docs.rs and in the IDE
medium deny the docs of internal crates are the map of the code; they build without a warning
big deny the docs of internal crates are the map of the code; they build without a warning
ai off
embedded off
ui off
egui off
units-strict off
units-paranoid off

Parameters

Name Type Default Meaning
args list of strings ["--workspace", "--no-deps"] arguments to cargo doc

Why

A broken intra-doc link, an unclosed HTML tag or a bare URL in a doc comment renders wrong on docs.rs and in the IDE. cargo doc warns about them; this lint reports every warning, as RUSTDOCFLAGS="-D warnings" in CI would.

How to fix

Fix the doc comment the warning points at: link with the path rustdoc can resolve ([`crate::Foo`]), escape brackets that are not links.

Configure

[lints.cargo-doc]
level = "deny"
args = ["--workspace", "--no-deps"]
reason = "why this project wants it at this level"

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