Skip to content

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

New issue

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

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

Already on GitHub? # to your account

Open
xizheyin opened this issue Mar 4, 2025 · 0 comments
Labels
A-docs Area: Documentation for any part of the project, including the compiler, standard library, and tools A-local-reexports Area: Documentation that has been locally re-exported (i.e., non-cross-crate) C-bug Category: This is a bug. 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
@jieyouxu jieyouxu added A-docs Area: Documentation for any part of the project, including the compiler, standard library, and tools and removed needs-triage This issue may need triage. Remove it if it has been sufficiently triaged. labels Apr 10, 2025
# for free to join this conversation on GitHub. Already have an account? # to comment
Labels
A-docs Area: Documentation for any part of the project, including the compiler, standard library, and tools A-local-reexports Area: Documentation that has been locally re-exported (i.e., non-cross-crate) C-bug Category: This is a bug. 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

4 participants