From gtk-rs/gir#1079
Given the following Rust code with in-line annotations of the expected behaviour:
#![feature(doc_cfg)]
#[doc(cfg(feature = "foobar"))]
pub mod imp_pub {
/// Feature on `struct` in public module shows, despite no `doc_cfg` directly on the `struct`
pub struct BarPub {}
}
// This only shows Re-exports, but doesn't place the type in the top-level module
#[doc(cfg(feature = "foobar"))]
pub use crate::imp_pub::*;
#[doc(cfg(feature = "foobar"))]
mod imp_priv {
/// Feature on `struct` in private module is never shown
pub struct BarPriv {}
impl BarPriv {
/// Oddly enough the feature guard _is_ shown here
pub fn test() {}
}
}
#[doc(cfg(feature = "foobar"))]
pub use crate::imp_priv::*;
#[doc(cfg(feature = "foobar"))]
mod imp_priv_2 {
/// In a private module `doc_cfg` has to be placed directly on the `struct`
#[doc(cfg(feature = "foobar"))]
pub struct Bar {}
impl Bar {
/// The explicit feature guard is hidden here because it is _implied_ from the surrounding [`Bar`] type
#[doc(cfg(feature = "foobar"))]
pub fn test() {}
}
}
#[doc(cfg(feature = "foobar"))]
pub use crate::imp_priv_2::*;On:
me:gtk-rs/ $ rustc +nightly -Vv
rustc 1.53.0-nightly (5d04957a4 2021-03-22)
binary: rustc
commit-hash: 5d04957a4b4714f71d38326fc96a0b0ef6dc5800
commit-date: 2021-03-22
host: x86_64-unknown-linux-gnu
release: 1.53.0-nightly
LLVM version: 12.0.0
The issue
rustdoc does not seem to be able to generate feature requirement labels on types in private modules (mod imp_priv) that are publicly reexported (pub use crate::imp_priv::*;). The labels do not show up on the module overview nor struct page, but do propagate into items like functions for the given type.
Observed
This renders the BarPriv type without any feature requirement, neither in the module overview:
Nor on the struct page:
Note that the label is propagated onto pub fn test() {} (does not have an explicit #[doc(cfg())]), rustdoc at least understood that!
Expected output
It is supposed to render the feature requirement for foobar like Bar, both in the module overview above as on the struct page:
Bonus
It seems tricky to combine feature requirements on the mod and pub use reexport. In the case above they are the same, but what if:
#[doc(cfg(feature = "foo"))]
mod priv;
#[doc(cfg(feature = "bar"))]
pub use priv::*;
The type is only publicly available when foo and bar are specified. Specifying foo is fine but makes the contents of priv unreachable through the current module, specifying only bar should result in a "module priv not found" error.
CC @GuillaumeGomez
From gtk-rs/gir#1079
Given the following Rust code with in-line annotations of the expected behaviour:
On:
The issue
rustdocdoes not seem to be able to generate feature requirement labels on types in private modules (mod imp_priv) that are publicly reexported (pub use crate::imp_priv::*;). The labels do not show up on the module overview norstructpage, but do propagate into items like functions for the given type.Observed
This renders the
BarPrivtype without any feature requirement, neither in the module overview:Nor on the
structpage:Note that the label is propagated onto
pub fn test() {}(does not have an explicit#[doc(cfg())]),rustdocat least understood that!Expected output
It is supposed to render the feature requirement for
foobarlikeBar, both in the module overview above as on thestructpage:Bonus
It seems tricky to combine feature requirements on the
modandpub usereexport. In the case above they are the same, but what if:The type is only publicly available when
fooandbarare specified. Specifyingfoois fine but makes the contents ofprivunreachable through the current module, specifying onlybarshould result in a "moduleprivnot found" error.CC @GuillaumeGomez