#[doc(cfg(…))] doesn’t work properly with cross-crate re-exports.

[steffahn]

Hard to put in words the kind of mess that the situation currently seems to be…

Let’s just look at an example:

#![feature(doc_cfg)]

/// A module called `local_io`
pub mod local_io {}

#[doc(cfg(feature = "foo"))]
/// A module called `local_cfg_io`
pub mod local_cfg_io {}

pub mod m {
    #[doc(inline)]
    pub use std::io as io1;
    #[doc(no_inline)]
    pub use std::io as io2;
    #[doc(cfg(feature = "foo"), inline)]
    pub use std::io as io3;
    #[doc(cfg(feature = "foo"), no_inline)]
    pub use std::io as io4;

    #[doc(inline)]
    pub use crate::local_io as local_io1;
    #[doc(no_inline)]
    pub use crate::local_io as local_io2;
    #[doc(cfg(feature = "foo"), inline)]
    pub use crate::local_io as local_io3;
    #[doc(cfg(feature = "foo"), no_inline)]
    pub use crate::local_io as local_io4;

    #[doc(inline)]
    pub use crate::local_cfg_io as local_cfg_io1;
    #[doc(no_inline)]
    pub use crate::local_cfg_io as local_cfg_io2;
    #[doc(cfg(feature = "foo"), inline)]
    pub use crate::local_cfg_io as local_cfg_io3;
    #[doc(cfg(feature = "foo"), no_inline)]
    pub use crate::local_cfg_io as local_cfg_io4;
}

Resulting docs of module m:

Bug description

As you can see above, the cfg(feature = "foo") is mostly ignored on the pub use items. Only external items with inline take that attribute into account.

Expected behavior

I would probably expect that the rendered cfg label on a re-export only depends on cfg(doc(…)) attributes on the pub use itself. For a no_inline item, this would mean that the label in the “Re-exports” list might differ from the label you see on the item itself once you click on it; maybe we want a more clear way to distinguish the cfg of the pub use from the cfg of the used item.

---

@rustbot label A-rustdoc-ui, F-doc_cfg, requires-nightly

[jyn514]

Didn't read all the test cases, but this is probably a duplicate of #85043 or vice versa.

[steffahn]

Thanks for the link, I hadn't seen #85043 before.

It's related but I feel like the test cases cover somewhat of a different dimension. I guess, perhaps, the issues could be grouped as a single one. The new area that this issue covers is the behavior around items from other crates.

[jyn514]

I would probably expect that the rendered cfg label on a re-export only depends on cfg(doc(…)) attributes on the pub use itself. For a no_inline item, this would mean that the label in the “Re-exports” list might differ from the label you see on the item itself once you click on it; maybe we want a more clear way to distinguish the cfg of the pub use from the cfg of the used item.

Hmm, this is surprising to me - wouldn't you want to AND the conditions? Since the export will only available if both the original and new cfgs are true? I guess that could lead to trouble for facade re-exports:

#[cfg(unix)]
mod unix {
  #[doc(cfg(unix))]
  pub struct Foo {}
}

#[cfg(windows)]
mod windows {
  #[doc(cfg(windows)]
  pub struct Foo {}
}

#[cfg(unix)]
pub use unix::Foo;
#[cfg(windows)]
pub use windows::Foo;

But I don't see a way for both that and

#[cfg(unix)]
pub use inner::UnixFoo;
#[cfg(windows)]
pub use inner::WindowsFoo;

to behave as expected - the first one you don't want to show the cfg, and the second you do.

Maybe that is an argument to only use the attributes on the re-export, so you have the most flexibility.

[Kixunil]

This also affects pub extern crate statements.