Description
The rustdoc book explains that pub use items are documented under "Re-exports" by default when re-exporting a public item, and are inlined by default when re-exporting a private item.
Unfortunately, this appears to be implemented today by checking whether the item in its original path is public or private. In particular, it does not check whether the use'd path itself is public.
For example, if I adapt the code sample from that documentation by introducing a private module with two re-exports:
pub use bar::Bar;
/// bar docs
pub mod bar {
mod bar_impl {
/// the docs for Bar
pub trait Bar {}
}
pub use self::bar_impl::Bar;
}the generated documentation behaves as though I used #[doc(inline)] on the top-level re-export. I can add #[doc(no_inline)] and it will behave correctly, showing up as a re-export of bar::Bar, which itself is inlined. But the default behavior ends up with two separate inlined copies of the Bar trait, one at crate::Bar and the other at crate::bar::Bar, and there's nothing on the inlined docs that indicates that they're the same item.
You can see this today in documentation like bytes which has bytes::Buf and bytes::buf::Buf.
There's also some broken behavior in the reverse direction, which is documented in #94336.
Expected behavior
Re-exports should consider the visibility of the re-exported path, not the underlying item. Also see #94336 for a discussion of what happens if the re-exported path is a private re-export of a public item.
Meta
rustdoc --version --verbose:
rustdoc 1.58.1 (db9d1b20b 2022-01-20)
binary: rustdoc
commit-hash: db9d1b20bba1968c1ec1fc49616d4742c1725b4b
commit-date: 2022-01-20
host: x86_64-apple-darwin
release: 1.58.1
LLVM version: 13.0.0