Add --document-hidden-items flag to cargo doc

[dtolnay]

Rustdoc's existing stable --document-private-items flag was split into stable --document-private-items and unstable --document-hidden-items in rust-lang/rust#67875, as these are orthogonal concepts (visibility lower than pub, vs attribute doc(hidden)). Cargo doc has a way to call the first but not the second.

[jyn514]

As a workaround, you could use RUSTDOCFLAGS: RUSTDOCFLAGS='--document-hidden-items' cargo +nightly doc.

[xiongmao86]

If no one is working on this, I would like to take a stab.

[oconnor663]

Currently it looks like I have to spell this:

RUSTDOCFLAGS='-Z unstable-options --document-hidden-items' cargo +nightly doc

[jyn514]

I have a question for the cargo team - how much of rustdoc's flags do you want to expose? Rustdoc has quite a lot of options:

$ rustdoc --help | grep -- -- | wc -l
67

and it seems silly to expose them all. --document-hidden-items doesn't come to mind as a "primary" option I'd expect lots of people to use.

[ehuss]

There isn't a formal policy, but generally we only add flags if it seems like they would be commonly used.

[obi1kenobi]

As a possibly unintended side-effect, this issue also appears to be blocking CI linting of hidden items on stable Rust.

Consider the following example:

/// Hidden fn with broken [rustdoc].
#[doc(hidden)]
pub fn hidden_fn() {}

This function's [rustdoc] link is broken.

However, running RUSTDOCFLAGS='-D warnings' cargo doc --all-features --no-deps --document-private-items reports no issues whatsoever.

Adding --document-hidden-items catches the problem successfully, however as I'm sure we all know, it requires nightly Rust and a much more complex invocation:

$ RUSTDOCFLAGS='-D warnings -Z unstable-options --document-hidden-items' cargo +nightly doc --all-features --no-deps --document-private-items
error: unresolved link to `rustdoc`
  --> example/src/lib.rs:10:28
   |
10 | /// Hidden fn with broken [rustdoc].
   |                            ^^^^^^^ no item named `rustdoc` in scope
   |
   = help: to escape `[` and `]` characters, add '\' before them like `\[` or `\]`
   = note: `-D rustdoc::broken-intra-doc-links` implied by `-D warnings`

error: could not document `example`

[weihanglo]

From #8001 (comment)

For Cargo team I'd also like to have a conversation about how we want to handle rustdoc flags. Rustdoc has a lot of flags, should we replicate most of them as-is in cargo doc? Some (like --crate-version or --extern-html-root-url) make sense for Cargo to handle internally. Where do we draw the line of "this must be passed with RUSTDOCFLAGS" and "Cargo will forward this flag for you"?

In addition, there is a convention that we normally wait for a flag stabilized and add it to Cargo. Given --document-hidden-items is still unstable, this is labeled as S-blocked-external.