Feature: Passing additional args to rustdoc from cargo doc

Summary

rustdoc exposes additional configuration through CLI options, but they are not available through cargo doc. Passing extra args from cargo doc to rustdoc would expose them.

Motivation

  • Fail on rustdoc lint warnings with cargo doc -- -D warnings

Guide-level explanation

Not sure what to write here

Reference-level explanation

In cargo doc subcommand (cargo/doc.rs at master · rust-lang/cargo · GitHub):

  • add an arg that accept multiple values: Arg::with_name("args").multiple(true)
  • pass the values to compile_opts.target_rustdoc_args

See pass extra args to rustdoc from `cargo doc` by mockersf · Pull Request #9415 · rust-lang/cargo · GitHub

Drawbacks

This exposes all rustdoc configuration, which adds complexity.

Rationale and alternatives

This is already possible with an environment variable: RUSTDOCFLAGS. This feature only brings parity to cargo doc as other cargo commands that accepts args: bench, run, rust, rustdoc, test.

It's nicer when running:

cargo clippy -- -D warnings
cargo doc -- -D warnings
// instead of 
RUSTDOCFLAGS='-D warnings' cargo doc

Prior art

Not sure what to write here

Unresolved questions

Not sure what to write here

Future possibilities

Not sure what to write here

bench, run and test pass it when running the final executable. rustc and rustdoc pass it when compiling the final crate. What you are suggesting passes it to all crates, not just the final. cargo build doesn't accept this either. IMHO using RUSTDOCFLAGS (and RUSTFLAGS for rustc) isn't much worse than your proposal.

1 Like