Documentation of a re-export doesn't appear on level-two re-export

[jplatte]

I have a macro crate with a "peer dependency" on another crate, i.e. I can't write doctests for the macro itself without introducing circular dev-dependencies which are kind of annoying. The other crate re-exports the macro and the macro is actually expected to only ever be used through there, so I documented the re-export instead. However, there's another higher-level crate that re-exports a bunch of other crates entirely including the one that re-exports the macro. In the documentation of the higher-level crate, the documentation for the macro does not appear, while it appears on the "level-one" re-export.

Minimal reproduction:

Crate foo re-exports a type from bar, which is itself a re-export of a type from baz. The docs on each of the declarations (original type definition in baz, re-exports in bar and foo) are simply the crate name

// # baz/src/lib.rs
/// baz
pub struct Type;

// # bar/src/lib.rs
/// bar
pub use baz::Type;

// # foo/src/lib.rs
/// foo
pub use bar::Type;

Here is a repo with this: https://github.com/jplatte/rust-issue-81893

I expected to see this happen: the docs of foo::Type should be foo bar baz

Instead, this happened: the docs of foo::Type are foo baz

Meta

Happens with latest nightly from rustup that has rustfmt:

rustc --version --verbose:

rustc 1.51.0-nightly (04caa632d 2021-01-30)
binary: rustc
commit-hash: 04caa632dd10c2bf64b69524c7f9c4c30a436877
commit-date: 2021-01-30
host: x86_64-unknown-linux-gnu
release: 1.51.0-nightly
LLVM version: 11.0.1

[jyn514]

Some related bugs:

mod a {
    /// baz
    pub struct Type;
}

mod b {
    /// bar
    pub use crate::a::Type;
}

/// foo
pub use b::Type;

only shows baz in the docs, as does

mod a {
    /// baz
    pub struct Type;
}

/// bar
pub use a::Type;

[jyn514]

A bit of trivia, not particularly helpful: In 1.33, the cross-crate issue behaved as the single crate issue and only showed baz.

[TaKO8Ki]

@rustbot claim

[TaKO8Ki]

It is about work on this issue!

[jyn514]

@TaKO8Ki hi, have you made any progress on this issue? No problem if not, but please comment @rustbot release-assignment if so, so other people can work on it.

[TaKO8Ki]

@jyn514
I'm sorry. I was busy a while ago, but I have some time on my hands these days, so can I work on this issue some more?

[jyn514]

Sure thing. If it helps, I think this is the place to look:

rust/src/librustdoc/clean/inline.rs

Line 287 in 4fa76a4

fn merge_attrs(

[TaKO8Ki]

@jyn514
Thank you! I'm going to take a look.

[GuillaumeGomez]

The problem evolved a bit. With this code:

mod a {
    /// baz
    pub struct Type;
}

mod b {
    /// bar
    pub use crate::a::Type;
}

/// foo
pub use b::Type;

We now have foo baz documentation for Type.

[jplatte]

Isn't that the same thing I wrote originally? Or is the change that it happens inside one crate as well now (I don't think I tested that scenario before)?

[GuillaumeGomez]

Sorry, you are absolutely right. I worked on something similar recently and checked if the problem still existed and forgot to check your first message. Sorry. I'm working on this issue to fix it definitely.

[jplatte]

I just tested it and unfortunately it doesn't appear fixed for Ruma in rustc 1.67.0-nightly (96ddd32c4 2022-11-14).

Original definition: https://github.com/ruma/ruma/blob/28a665c3d9be8b83f4d722113a7f3159094d6a3b/crates/ruma-macros/src/lib.rs#LL385C5-L385C15
First re-export with docs: https://github.com/ruma/ruma/blob/28a665c3d9be8b83f4d722113a7f3159094d6a3b/crates/ruma-common/src/api.rs#L135
Re-re-export: https://github.com/ruma/ruma/blob/28a665c3d9be8b83f4d722113a7f3159094d6a3b/crates/ruma/src/lib.rs#L101

[GuillaumeGomez]

Can you write a minimum code to reproduce the issue please? I think the proc-macro call might be messing with it.

[jplatte]

Updated https://github.com/jplatte/rust-issue-81893 with a new reproducer.

[GuillaumeGomez]

Found out about this issue: the problem is that reexports don't exist in the Rust ABI at the moment. There is work in progress to add support for it but we're far from done. Until then, I'm afraid that foreign reexports docs won't appear...

[jyn514]

what are you talking about? "rust abi" isn't a thing and it wouldn't involve rustdoc if it did, abi is a codegen thing and rustdoc doesn't do codegen.

[GuillaumeGomez]

By that I meant that this information isn't stored in the rmeta file. That's what I called (wrongly apparently) the ABI.

[jyn514]

ok. .rmeta files contain metadata; here's the section of the dev-guide that talks about them: https://rustc-dev-guide.rust-lang.org/backend/libs-and-metadata.html

it's ok not to know everything about the compiler, but please don't make up random words if you're not sure the right word, i would much rather you say "this information isn't stored in the rmeta file" than confuse everyone involved.

[GuillaumeGomez]

Thanks!

[jyn514]

also there are two parts to this issue, one is within the same crate and one is across crates; only the one across crates can be affected by what's in the metadata file. is the part within the same crate fixed? if not, i think it's unlikely that metadata is related.

[GuillaumeGomez]

In the same crate it was fixed recently. I wrote a blog post recently about the work on how re-exports are handled in rustdoc here. I also describe how "intermediate" re-exports are handled. So now, the only bug remaining is about foreign re-exports.

[workingjubilee]

"rust abi" isnt a thing

Strictly speaking, there is such a thing as "the Rust ABI".

It is unstable, but implicitly, it is defined by "whatever we are currently doing during codegen". However, "ABI" only concerns parts of the program that are reachable at runtime, such as a struct's binary layout, what registers data is passed in, or thread-local storage data. It would be... a strange day where that sort of thing is relevant to rustdoc.