rustdoc: Provide a flag to document private items while also stripping hidden items

[euclio]

Some crates would like to document private items, but still respect #[doc(hidden)].

For example, synstructure generates private constant implementation details for hygiene reasons. Since these constants are private, they normally do not appear in documentation, but they do appear if a downstream crate uses --document-private-items.

The constants are annotated with #[doc(hidden)], so they can be hidden from documentation by using --document-private-items in tandem with --passes strip-hidden, but the --passes flag is deprecated.

Ideally, --document-private-items would be modified to still strip hidden items, because I believe that this is the more common use case. #[doc(hidden)] is generally used for implementation details (hygiene, __Nonexhaustive, etc.), and likely shouldn't ever actually be in the documentation, even for crates that want to document private items. Perhaps the current behavior could be renamed to --document-hidden-items. However, --document-private-items is stable, so I don't think this change can be made.

Instead, I propose adding (and eventually stabilizing) a new flag for rustdoc that has the same effect as --document-private-items and --passes strip-hidden. Something like --document-private-items=exclude-hidden?

[hexane360]

It looks like this changed in 2017 with #46380. Prior to this, --document-private-items ran strip-hidden.

I agree that the default behavior should be to strip hidden items, because it is the most common use case. The problem in #46380 seems to be that there's no way to manually specify private semantics (e.g. #[doc(private)]), not that the semantics for hidden items is incorrect. Hidden items should have separate semantics from private items.

[jtmoon79]

FWIW Asked on SO here.

tl;dr I had a need for attribute #[doc(visible)] proposed in #66528 The CLI options mentioned here are too broad (--document-private-items, --passes strip-hidden, --document-private-items=exclude-hidden, etc.).

I have one private function of-interest to users. The many other private functions should not be seen in the documentation. I'd prefer to mark one private function with something like #[doc(visible)], instead of marking all other functions with #[doc(hidden)].