rustdoc: `pub use` re-exports of private re-exports of public items show the private path

[lilyball]

I tried this code:

/// bar docs
pub mod bar {
    /// the docs for Bar
    pub trait Bar {}
}

mod qux {
    pub use crate::bar::Bar;
}

pub use qux::Bar;

I expected to see this happen: The Bar item should be documented as a re-export of bar::Bar

Instead, this happened: It shows up as a re-export of qux::Bar (though the link takes me to bar::Bar):

Re-exports

pub use qux::Bar;

Modules

bar    bar docs

This is very odd, it shouldn't be exposing a private module path like that, it should instead show it as pub use bar::Bar.

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]

Also see #94338 wherein I argue that inline/no_inline inference should be done by considering the visibility of the re-exported path, not the underlying item.

In the case of a public re-export of a private use, rustdoc should recurse once into that private use and reevaluate. That would solve the issue described here, where the top-level pub use qux::Bar would recurse once into qux::Bar and find the pub use crate::bar::Bar and document it as a re-export of that instead.

The way this could work with the #94338 model of "consider the visibility of the re-exported path" is to introduce a new #[doc(inline_once)] attribute and infer that instead of inferring #[doc(inline)]. This new variant would mean "inline this specific path" rather than "inline what this path resolves to", and so it would be documented however that path is (or would be). This should produce identical behavior for re-exports of items, and it wouldn't affect public re-exports of public use statements as those would be inferred as #[doc(no_inline)] as per #94338. So this would only affect re-exports of private paths which are themselves re-exports.

With this model, the above code would be inferred as

/// bar docs
pub mod bar {
    /// the docs for Bar
    pub trait Bar {}
}

mod qux {
    #[doc(no_inline)]
    pub use crate::bar::Bar;
}

#[doc(inline_once)]
pub use qux::Bar;

The qux::Bar item, if it were documented, would be documented as a re-export of crate::bar::Bar, and so the #[doc(inline_once)] pub use qux::Bar would also be documented as a re-export of crate::bar::Bar¹. If the inlined use uses a path relative to self or super then it would be adjusted as needed, i.e. if qux::Bar was pub use super::bar::Bar then the top-level re-export would show it as pub use bar::Bar.

By considering just the visibility of the path itself (as per #94338) and inferring #[doc(inline_once)] instead of #[doc(inline)], then re-export chains will just naturally behave correctly, never showing a private path to the user and never inlining an item when a re-export would do.

Footnotes

1. Perhaps this should show as bar::Bar rather than crate::bar::Bar, but the behavior today of writing pub use crate::bar::Bar at the top-level is to show it as the full crate::bar::Bar even though it could be rendered as bar::Bar, so this behavior would be consistent with what we have today. ↩