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

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

    Issue actions