Skip to content

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

Open
@xizheyin

Description

@xizheyin

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

Activity

added
needs-triageThis issue may need triage. Remove it if it has been sufficiently triaged.
on Mar 4, 2025
added
T-rustdocRelevant to the rustdoc team, which will review and decide on the PR/issue.
A-local-reexportsArea: Documentation that has been locally re-exported (i.e., non-cross-crate)
on Mar 4, 2025
added
A-docsArea: Documentation for any part of the project, including the compiler, standard library, and tools
and removed
needs-triageThis issue may need triage. Remove it if it has been sufficiently triaged.
on Apr 10, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    A-docsArea: Documentation for any part of the project, including the compiler, standard library, and toolsA-local-reexportsArea: Documentation that has been locally re-exported (i.e., non-cross-crate)C-bugCategory: This is a bug.T-rustdocRelevant to the rustdoc team, which will review and decide on the PR/issue.

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

      Development

      No branches or pull requests

        Participants

        @lolbinarycat@jieyouxu@rustbot@xizheyin

        Issue actions

          [rustdoc] Inconsistency re-exporting items without #[doc(hidden)] from private modules · Issue #137979 · rust-lang/rust