Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Open
xizheyin opened this issue Mar 4, 2025 · 0 comments
Labels
A-local-reexports Area: Documentation that has been locally re-exported (i.e., non-cross-crate) C-bug Category: This is a bug. needs-triage This issue may need triage. Remove it if it has been sufficiently triaged. T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue.

Comments

@xizheyin
Copy link
Contributor

xizheyin commented Mar 4, 2025

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
@xizheyin xizheyin added the C-bug Category: This is a bug. label Mar 4, 2025
@rustbot rustbot added the needs-triage This issue may need triage. Remove it if it has been sufficiently triaged. label Mar 4, 2025
@lolbinarycat lolbinarycat added T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue. A-local-reexports Area: Documentation that has been locally re-exported (i.e., non-cross-crate) labels Mar 4, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
A-local-reexports Area: Documentation that has been locally re-exported (i.e., non-cross-crate) C-bug Category: This is a bug. needs-triage This issue may need triage. Remove it if it has been sufficiently triaged. T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue.
Projects
None yet
Development

No branches or pull requests

3 participants