[rustdoc] Inconsistency re-exporting items without #[doc(hidden)] from private modules
Nobody has claimed this yet.
- Dominant language
- Rust
- Stars
- 119k
- Forks
- 16.2k
- PR merge metrics
- PR metrics pending
Description
Description
As discussion in #137342 , After hide the item whose source is hidden,
I experimented with different cases and I found another inconsistency, No.7. I think we should hide the case in No.7 for consistency? If someone wants to inline it, just use #[doc(inline)].
In the meantime, the documentation needs to be updated to be more clear.
cc @GuillaumeGomez @lolbinarycat
| No | source in private module? | source is hidden? | reexport chain has hidden?(exclude source) | visible? | inline? | Note |
|---|---|---|---|---|---|---|
| 1 | 0 | 0 | 0 | 1 | no | |
| 2 | 0 | 0 | 1 | 0 | fix in #137534 | |
| 3 | 0 | 1 | 1 | 0 | fix in #137534 | |
| 4 | 0 | 1 | 0 | 0 | fix in #137534 | |
| 5 | 1 | 1 | 0 | 0 | ||
| 6 | 1 | 1 | 1 | 0 | ||
| 7 | 1 | 0 | 1 | 1 | 1 | Bug? |
| 8 | 1 | 0 | 0 | 1 | 1 |
Source code
No1
// Source in a public module
pub mod public_mod {
pub struct PublicItem;
}
// Simple reexport
pub use public_mod::PublicItem;
// Result: PublicItem is NOT inlined, just shown as reexport
No2
// Source in a public module
pub mod public_mod {
pub struct PublicItem;
}
// Hidden reexport
#[doc(hidden)]
pub use public_mod::PublicItem as HiddenItem;
// Reexport of the hidden item
pub use self::HiddenItem as ReexportedItem;
// Result: ReexportedItem is inlined from PublicItem
No3
// Source in a public module but hidden
pub mod public_mod {
#[doc(hidden)]
pub struct HiddenSource;
}
// Reexport with hidden attribute
#[doc(hidden)]
pub use public_mod::HiddenSource as MiddleItem;
// Reexport of the hidden item
pub use self::MiddleItem as FinalItem;
// Result: FinalItem is inlined from HiddenSource, but without HiddenSource docs
No4
// Source in a public module but hidden
pub mod public_mod {
#[doc(hidden)]
pub struct HiddenSource;
}
// Direct reexport of hidden item
pub use public_mod::HiddenSource as ReexportedItem;
// Result: ReexportedItem is inlined from HiddenSource
No5
// Source in a private module and hidden
mod private_mod {
#[doc(hidden)]
pub struct HiddenPrivateItem;
}
// Reexport without hidden
pub use private_mod::HiddenPrivateItem as ReexportedItem;
// Result: ReexportedItem is inlined from HiddenPrivateItem
No6
// Source in a private module and hidden
mod private_mod {
#[doc(hidden)]
pub struct HiddenPrivateItem;
}
// Hidden reexport
#[doc(hidden)]
pub use private_mod::HiddenPrivateItem as MiddleItem;
// Final reexport
pub use self::MiddleItem as FinalItem;
// Result: FinalItem is inlined from HiddenPrivateItem
No7
// Source in a private module
mod private_mod {
pub struct PrivateModItem;
}
// Hidden intermediate reexport
#[doc(hidden)]
pub use private_mod::PrivateModItem as HiddenReexport;
// Final reexport
pub use self::HiddenReexport as FinalItem;
// Result: FinalItem is inlined from PrivateModItem
No8
// Source in a private module
mod private_mod {
pub struct PrivateModItem;
}
// Direct reexport
pub use private_mod::PrivateModItem;
// Result: PrivateModItem is inlined in documentation
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with the No.7 and No.8 minimal examples in the issue and inspect rustdoc's re-export handling. Compare the documented visibility and inlining outcomes across all eight cases, then clarify the documentation and verify that the behavior for the private-module cases is consistent.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- rust
- Domain
- documentation
- Issue type
- Bug
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 38/100