Description
Problem
PR #7593 changed Cargo to document private items for binary targets by default. This is great!
In my case, I've got a crate with two binaries and a library. The library is really only to support the binaries and the test suite. There's no need for public documentation. Instead, I want to configure the repo so that cargo doc documents the private items in the library. I created a .cargo/config that specifies build.rustdocflags = "--document-private-items". If I run cargo doc --lib, this does the right thing (generates library documentation that includes private items). But if I just run cargo doc, this fails because it tries to generate docs for the binaries, hits the behavior added in #7593, and passes --document-private-items twice to rustdoc.
Here's an example with a demo repo that I created to test this:
$ cargo doc -v
Checking cargo-doc-rustdocflags v0.1.0 (/Users/dap/oxide/cargo-rustdoc-flags)
Documenting cargo-doc-rustdocflags v0.1.0 (/Users/dap/oxide/cargo-rustdoc-flags)
Running `rustdoc --edition=2018 --crate-type lib --crate-name cargo_doc_rustdocflags src/lib.rs -o /Users/dap/oxide/cargo-rustdoc-flags/target/doc --error-format=json --json=diagnostic-rendered-ansi -L dependency=/Users/dap/oxide/cargo-rustdoc-flags/target/debug/deps --document-private-items`
Running `rustc --crate-name cargo_doc_rustdocflags --edition=2018 src/lib.rs --error-format=json --json=diagnostic-rendered-ansi --crate-type lib --emit=dep-info,metadata -C debuginfo=2 -C metadata=fd5eda5c10a1d5e5 -C extra-filename=-fd5eda5c10a1d5e5 --out-dir /Users/dap/oxide/cargo-rustdoc-flags/target/debug/deps -C incremental=/Users/dap/oxide/cargo-rustdoc-flags/target/debug/incremental -L dependency=/Users/dap/oxide/cargo-rustdoc-flags/target/debug/deps`
Running `rustdoc --edition=2018 --crate-type bin --crate-name hello src/bin/hello/main.rs -o /Users/dap/oxide/cargo-rustdoc-flags/target/doc --error-format=json --json=diagnostic-rendered-ansi --document-private-items -L dependency=/Users/dap/oxide/cargo-rustdoc-flags/target/debug/deps --extern cargo_doc_rustdocflags=/Users/dap/oxide/cargo-rustdoc-flags/target/debug/deps/libcargo_doc_rustdocflags-fd5eda5c10a1d5e5.rmeta --document-private-items`
error: Option 'document-private-items' given more than once
error: Could not document `cargo-doc-rustdocflags`.
Caused by:
process didn't exit successfully: `rustdoc --edition=2018 --crate-type bin --crate-name hello src/bin/hello/main.rs -o /Users/dap/oxide/cargo-rustdoc-flags/target/doc --error-format=json --json=diagnostic-rendered-ansi --document-private-items -L dependency=/Users/dap/oxide/cargo-rustdoc-flags/target/debug/deps --extern cargo_doc_rustdocflags=/Users/dap/oxide/cargo-rustdoc-flags/target/debug/deps/libcargo_doc_rustdocflags-fd5eda5c10a1d5e5.rmeta --document-private-items` (exit code: 1)
warning: build failed, waiting for other jobs to finish...
error: build failed
Steps
- Clone this repo: https://github.com/davepacheco/bug-cargo-doc-rustdocflags
- Run
cargo doc. Instead of generating docs, it fails.
I expect you'd also run into this without a .cargo/config if you specified RUSTDOCFLAGS=--document-private-items in the environment.
Possible Solution(s): It would be nice if the auto-document-private-items behavior for binary targets checked whether --document-private-items is already part of the rustdoc flags before adding it.
You can work around this problem by disabling docs for the binaries, using a block like this in Cargo.toml:
[[bin]]
name = # your binary's name
doc = false
Notes
Output of cargo version:
$ cargo version
cargo 1.42.0 (86334295e 2020-01-31)
I see the same on cargo 1.45.0-nightly (9fcb8c1d2 2020-05-25). I'm on OS X 10.15.4.