Repository navigation
cargo doc should suggest --lib override if documenting a crate with only doc = false targets #13437
Description
Consider the sev crate — it's a lib-only crate whose lib target has doc = false. Running cargo doc on it succeeds immediately as a no-op, without building anything.
Both I and a few other folks on Zulip were surprised to learn that adding --lib to the cargo doc invocation will override the doc = false setting. It was particularly surprising because:
- Adding
--libis usually how we might disambiguate between multiple targets, but the lib target is the only target for that crate. - AFAICT the
--helptext forcargo docnever mentions the ability to overridedoc = falseby explicitly selecting a target.
It would be great if running cargo doc in a no-op manner would print out a note suggesting the user explicitly select a target to override doc = false. For example:
$ cargo doc --no-deps
note: all targets are `doc = false` so nothing will be documented
run `cargo doc -p sev --lib` to override and document the lib target
Finished dev [unoptimized + debuginfo] target(s) in 0.02s
Also, perhaps the cargo doc --help could mention explicitly selecting a target overrides doc = false in the Target Selection section:
Target Selection:
--lib Document only this package's library
--bins Document all binaries
--bin [<NAME>] Document only the specified binary
--examples Document all examples
--example [<NAME>] Document only the specified example
Explicitly selecting a target will override `doc = false` set on that target in Cargo.toml
Raised via: obi1kenobi/cargo-semver-checks#660
@rustbot label +T-rustdoc
Activity
rustbot commentedon Feb 13, 2024
Error: Label T-rustdoc can only be set by Rust team members
Please file an issue on GitHub at triagebot if there's a problem with this bot, or reach out on #t-infra on Zulip.
weihanglo commentedon Feb 19, 2024
I believe a target with
test = falsecan be tested when specified bycargo test --test my-test. It is documented here viacargo help doc(thecargo helplong manual is always hard to find).For sure, if there is nothing being tested/documented/benchmarked, Cargo could message for that.
theinfosecguy commentedon Oct 25, 2026
@epage Is this still available? I can pick this up.