rust-lang / rust-lang/rust

[rustdoc] Inconsistency re-exporting items without #[doc(hidden)] from private modules

Open
#137,979 0 comments 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

A-docs A-local-reexports C-bug T-rustdoc
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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.