Skip to content

cargo doc should suggest --lib override if documenting a crate with only doc = false targets #13437

Open
@obi1kenobi

Description

@obi1kenobi

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 for cargo doc never mentions the ability to override doc = 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

Metadata

Metadata

Assignees

No one assigned

    Labels

    A-cargo-targetsArea: selection and definition of targets (lib, bins, examples, tests, benches)A-diagnosticsArea: Error and warning messages generated by Cargo itself.C-enhancementCategory: enhancementCommand-docS-needs-mentorStatus: Issue or feature is accepted, but needs a team member to commit to helping and reviewing.

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions