rustdoc: Provide a flag to document private items while also stripping hidden items #60884
Comments
jonas-schievink
added
C-feature-request
…=GuillaumeGomez strip synstructure consts from compiler docs Fixes rust-lang#60150. Unfortunately this PR depends on the use of the deprecated `--passes` flag in bootstrap to keep the `--strip-hidden` pass while still documenting private items. I've opened rust-lang#60884 to track stabilization of a new flag that encapsulates this behavior. r? @QuietMisdreavus
…=GuillaumeGomez strip synstructure consts from compiler docs Fixes rust-lang#60150. Unfortunately this PR depends on the use of the deprecated `--passes` flag in bootstrap to keep the `--strip-hidden` pass while still documenting private items. I've opened rust-lang#60884 to track stabilization of a new flag that encapsulates this behavior. r? @QuietMisdreavus
…=GuillaumeGomez strip synstructure consts from compiler docs Fixes rust-lang#60150. Unfortunately this PR depends on the use of the deprecated `--passes` flag in bootstrap to keep the `--strip-hidden` pass while still documenting private items. I've opened rust-lang#60884 to track stabilization of a new flag that encapsulates this behavior. r? @QuietMisdreavus
|
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. |
Distinguish between private items and hidden items in rustdoc I believe rustdoc should not be conflating private items (visibility lower than `pub`) and hidden items (attribute `doc(hidden)`). This matters now that Cargo is passing --document-private-items by default for bin crates. In bin crates that rely on macros, intentionally hidden implementation details of the macros can overwhelm the actual useful internal API that one would want to document. This PR restores the strip-hidden pass when documenting private items, and introduces a separate unstable --document-hidden-items option to skip the strip-hidden pass. The two options are orthogonal to one another. Fixes rust-lang#67851. Closes rust-lang#60884.
Distinguish between private items and hidden items in rustdoc I believe rustdoc should not be conflating private items (visibility lower than `pub`) and hidden items (attribute `doc(hidden)`). This matters now that Cargo is passing --document-private-items by default for bin crates. In bin crates that rely on macros, intentionally hidden implementation details of the macros can overwhelm the actual useful internal API that one would want to document. This PR restores the strip-hidden pass when documenting private items, and introduces a separate unstable --document-hidden-items option to skip the strip-hidden pass. The two options are orthogonal to one another. Fixes rust-lang#67851. Closes rust-lang#60884.
|
FWIW Asked on SO here. tl;dr I had a need for attribute 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 |
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?The text was updated successfully, but these errors were encountered: