Not all doc-comments on re-exports are displayed

[Susurrus]

In nix we're aliasing the libc::termios type using pub use libc::termios as Termios. That type has no documentation in libc, but we'd like to offer documentation for the type in our own crate. Specifying a doc comment above it doesn't support anything in the output. It'd be very useful if you could override documentation when aliasing types.

Originally posted at rust-lang/cargo#4250.

[gyscos]

Would a type alias work in this case?

/// I cannot comment it here!
pub use libc::termios as Termios

/// But this works fine!
pub type Termios = libc::termios;

I think a type alias works almost identically as a re-export (only it shows up in a different rustdoc category).

[Aaron1011]

I believe this is fixed on the latest nightly.

[gyscos]

Indeed! Thanks.

A related question: when pub-using an undocumented enum from another crate, I can re-document the enum itself but not the variant (similarly for a struct, I couldn't document the fields).

Is there a way to add some attribute to #[doc()] so that I can document these inner elements from outside?

[tavianator]

This doesn't seem fixed (anymore?). Using a type = alias is almost as good but doesn't get you the constructor of a tuple-like struct: #73191

[tavianator]

Oh I see, it works for public re-exports of a private type. In my case I wanted to do something like this:

pub mod a {
    /// A foo.
    pub struct Foo;
}

pub mod b {
    /// This doesn't show up anywhere
    pub use a::Foo as Bar;
}

[GuillaumeGomez]

If you want the second comment to appear, you can add #[doc(inline)] on the second reexport. It'll generate another page for the Bar type. I think having a lint for this would be quite useful.