Rustdoc: #[doc(hidden)] should not apply recursively

[jyn514]

I tried this code:

#[doc(hidden)]
pub mod inner {
  pub struct S;
}
pub use inner::S;

I expected to see this happen: Rustdoc generates docs for S but not inner, since the pub use does not have a doc(hidden) attribute.

Instead, this happened: Rustdoc doesn't generate docs for either (presumably because it applies doc(hidden) recursively).

Additionally, I tried this code:

#[doc(hidden)]
pub use context_api;
mod context_api;

but got a name resolution error:

error[E0255]: the name `context_api` is defined multiple times
   --> src/lib.rs:155:1
    |
153 | pub use context_api;
    |         ----------- previous import of the module `context_api` here
154 | 
155 | mod context_api;
    | ^^^^^^^^^^^^^^^^ `context_api` redefined here
    |
    = note: `context_api` must be defined only once in the type namespace of this module
help: you can use `as` to change the binding name of the import
    |
153 | pub use context_api as other_context_api;
    |         ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

error[E0365]: `context_api` is private, and cannot be re-exported
   --> src/lib.rs:153:9
    |
153 | pub use context_api;
    |         ^^^^^^^^^^^ re-export of private `context_api`
    |
    = note: consider declaring type or module `context_api` with `pub`

Both of those combined means there's no way to display the docs for only the module and not its items.

Meta

rustdoc --version: rustdoc 1.52.0-nightly (9778068 2021-02-07)

[jyn514]

Additionally, publicly re-exporting it under a different name doesn't work:

error[E0365]: `context_api_` is private, and cannot be re-exported
   --> src/lib.rs:152:9
    |
152 | pub use context_api_ as context_api;
    |         ^^^^^^^^^^^^^^^^^^^^^^^^^^^ re-export of private `context_api_`
    |
    = note: consider declaring type or module `context_api_` with `pub`

[jyn514]

Ok, as a workaround I can mark other imports as doc(inline) and that works correctly.

#[doc(hidden)]
mod context_api;
#[doc(inline)]
pub use context_api::*;

I think rustdoc should inline these automatically if the original module has doc(hidden).

[jyn514]

For clarification, my use case for this is that context_api was public in the last release, and making it private would introduce unnecessary churn. Using doc(hidden) is like a 'soft deprecation' without adding a bunch of warnings.

[Nemo157]

Also see #59368 which has mentions of this issue.

[jyn514]

Oh good point, I think this is a duplicate.