Open
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
--lib
is usually how we might disambiguate between multiple targets, but the lib target is the only target for that crate. - AFAICT the
--help
text forcargo doc
never mentions the ability to overridedoc = false
by 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