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?
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-itemsin tandem with--passes strip-hidden, but the--passesflag is deprecated.Ideally,
--document-private-itemswould 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-itemsis 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-itemsand--passes strip-hidden. Something like--document-private-items=exclude-hidden?