Repository navigation
rustdoc: Inconsistant decision to include impl with docs but no visible items #111564
Description
Since #90905, rustdoc has impl blocks with docs but no items: But it's logic doesn't make (user facing) sense
pub struct Foo;
/// 1. Empty
impl Foo {}
/// 2. Private
impl Foo {
fn private() {}
}
/// 3. Public
impl Foo {
pub fn public() {}
}
/// 4. Public Hidden
impl Foo {
#[doc(hidden)]
fn public_hidden() {}
}
/// 5. Private Hidden
impl Foo {
#[doc(hidden)]
fn priviate_hidden() {}
}Running this code across various flag's gets us:
| Header | --document-private-items |
--document-hidden-items |
--document-private-items --document-hidden-items |
|
|---|---|---|---|---|
| Empty | ✔️ | ✔️ | ✔️ | ✔️ |
| Private | ❌ | ✔️ | ✔️ | ✔️ |
| Public | ✔️ | ✔️ | ✔️ | ✔️ |
| Public Hidden | ✔️ | ✔️ | ✔️ | ✔️ |
| Private Hidden | ✔️ | ✔️ | ✔️ | ✔️ |
It doesn't make sense that adding #[doc(hidden)] to a private function makes it's block visible, or that running --document-hidden-items makes a block with only private functions visible. I'm not sure what the exact behavior should be here
Activity
GuillaumeGomez commentedon May 17, 2023
In the code, the comment says:
The logic makes sense to me: impl blocks with only private items should very likely not be visible to readers. The question here I think should be more "should we do the same with impls containing only hidden items?". What do you think?
Rollup merge of rust-lang#111565 - aDotInTheVoid:rdj-impl-viz, r=Guil…
lolbinarycat commentedon Jan 19, 2025
@GuillaumeGomez the "private hidden" case definitely seems like a bug.