Skip to content
New issue

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

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

Already on GitHub? Sign in to your account

rustdoc: pub use items have docs inlined if impl is private even if use'd path is a public reexport #94338

Closed
lilyball opened this issue Feb 24, 2022 · 2 comments
Labels
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

@lilyball
Copy link
Contributor

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
@lilyball lilyball added the C-bug Category: This is a bug. label Feb 24, 2022
@fmease fmease 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) and removed needs-triage-legacy labels Jan 24, 2024
@fmease
Copy link
Member

fmease commented Jan 24, 2024

I can no longer reproduce this. I might've misunderstood the situation though.
Latest output:

--- Re-exports
pub use bar::Bar;  // links to `bar/trait.Bar.html`
--- Modules
bar                // links to `bar/index.html`

Closing as fixed. Please ping me if I the issue actually persists and if I should reopen it.

@fmease fmease closed this as completed Jan 24, 2024
@lilyball
Copy link
Contributor Author

You're right, this appears to have been fixed at some point between 1.68.2 and 1.71.0

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
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

3 participants