same-crate reexports lose documentation added to cross-crate reexports

[shepmaster]

I tried this code (ZIP of project):

├── Cargo.lock
├── Cargo.toml
├── regular-items
│   ├── Cargo.toml
│   └── src
│       └── lib.rs
└── src
    └── lib.rs

src/lib.rs

/// This documentation for `CONSTANT` comes from a cross-crate re-export.
pub use regular_items::CONSTANT;

/// This documentation for `function` comes from a cross-crate re-export.
pub use regular_items::function;

pub mod prelude {
    pub use crate::{CONSTANT, function};
}

regular-items/src/lib.rs

pub const CONSTANT: u8 = 0;
pub fn function() {}

I then viewed the documentation for

• the crate:

  

• the prelude module:

  

• crate::CONSTANT:

  

• crate::prelude::CONSTANT:

  

I expected:

• That the documentation added to crate::CONSTANT would be present on crate::prelude::CONSTANT.
• That crate::prelude::CONSTANT would redirect to crate::CONSTANT.

Instead:

• No documentation is present on crate::prelude::CONSTANT.
• crate::prelude::CONSTANT appears to be a different item than crate::CONSTANT.

Meta

cargo +nightly --version --verbose:

cargo 1.56.0-nightly (e515c3277 2021-09-08)
release: 1.56.0
commit-hash: e515c3277bf0681bfc79a9e763861bfe26bb05db
commit-date: 2021-09-08

Potentially related

• Documentation on re-exports is ignored if the item is defined in the same crate #84619

[jyn514]

crate::prelude::CONSTANT appears to be a different item than crate::CONSTANT.

Rustdoc is probably deciding to inline it for some reason - unless it's a change in behavior from an earlier release I don't think it's a bug. Missing the docs on prelude::CONSTANT is definitely wrong though.

[shepmaster]

I don't think it's a bug

Note that this causes the doc tests to be re-run for each instance:

test src/lib.rs - Snafu (line 279) ... ok
test src/lib.rs - Snafu (line 306) ... ok
test src/lib.rs - Snafu (line 337) ... ok
test src/lib.rs - Snafu (line 376) ... ok
test src/lib.rs - Snafu (line 420) ... ok
test src/lib.rs - Snafu (line 445) ... ok
test src/lib.rs - Snafu (line 473) ... ok
test src/lib.rs - Snafu (line 506) ... ok
test src/lib.rs - Snafu (line 527) ... ok
test src/lib.rs - Snafu (line 552) ... ok
test src/lib.rs - Snafu (line 591) ... ok
test src/lib.rs - Snafu (line 617) ... ok

test src/lib.rs - prelude::Snafu (line 227) ... ok
test src/lib.rs - prelude::Snafu (line 254) ... ok
test src/lib.rs - prelude::Snafu (line 285) ... ok
test src/lib.rs - prelude::Snafu (line 324) ... ok
test src/lib.rs - prelude::Snafu (line 368) ... ok
test src/lib.rs - prelude::Snafu (line 393) ... ok
test src/lib.rs - prelude::Snafu (line 421) ... ok
test src/lib.rs - prelude::Snafu (line 454) ... ok
test src/lib.rs - prelude::Snafu (line 475) ... ok
test src/lib.rs - prelude::Snafu (line 500) ... ok
test src/lib.rs - prelude::Snafu (line 539) ... ok
test src/lib.rs - prelude::Snafu (line 565) ... ok

[jyn514]

Note that this causes the doc tests to be re-run for each instance:

That does seem like a bug - can you open a separate issue for it? Specifically that #[doc(inline)] will run doctests.

[shepmaster]

can you open a separate issue for it

I don't think it's separate; it's a knock-on effect of the fact that I have to provide the documentation twice and the documentation contains doc tests.

Effectively:

/// ```rust
/// assert_eq!(0, 1);
/// ```
pub use inner::alpha as my_alpha;

pub mod prelude {
    /// ```rust
    /// assert_eq!(0, 2);
    /// ```
    pub use super::my_alpha;
}

[jyn514]

I think this is a special case of #84619.

[aliemjay]

Last time I checked (and that was a long ago), for any re-exported item in a module, we concatenate the docs for the use statement with the resolution of the item (Res), and since Res refers only to where the item is originally defined (which may be cross-crate), any docs added anywhere other than these two places is ignored.

This behavior is now consistent for cross-crate and same-crate reexports.

Apparently the only way to fix is to follow the use path recursively and concatenate doc strings. But while this is feasible for paths within the same crate, once we cross crate boundary we no longer have this luxury and the only thing we can get from CStore is the Res of the item, again!.

So, if it is fine to sacrifice consistency with an incomplete solution that follows only the paths within the same crate, I'm happy to claim this issue. Otherwise, it would be diffcult since it requires modifying crate metadata.

[jyn514]

So, if it is fine to sacrifice consistency with an incomplete solution that follows only the paths within the same crate, I'm happy to claim this issue. Otherwise, it would be diffcult since it requires modifying crate metadata.

Yeah, that seems reasonable. We can do the more proper fix later.

cc @petrochenkov who may have suggestions about how to do this with the existing metadata