Prevent duplicate documentation for `pub use`

I have a somewhat corner case for cargo documentation.

Given following definition (lib.rs)

mod parent {
  pub mod submodule {
    /// Contains certain data
    pub struct SomeData { }
  }
  pub use submodule::SomeData;
}
pub use parent::SomeData;

The documentation generated by cargo doc will document the crate::parent::submodule::SomeData struct, and both crate::parent::SomeData and crate::SomeData will be documented as re-exported structs.

But if we change the inner module to be private as follows

mod parent {
  mod submodule {
    /// Contains certain data
    pub struct SomeData { }
  }
  pub use submodule::SomeData;
}
pub use parent::SomeData;

then crate::parent::SomeData and crate::SomeData will be documented separately (like there are two structs). Is this desired or a bug of cargo doc?


I do have a workaround for this, but only works for simple structs or generic structs without bounds:

mod parent {
  mod submodule {
    /// Contains certain data
    pub struct SomeData { }
  }
  pub type SomeData = submodule::SomeData;
}
pub use parent::SomeData;

Then cargo will regard crate::parent::SomeData as a concrete struct and crate::SomeData as re-exported.

You can use the #[doc(inline)] and #[doc(no_inline)] attributes to control when documentation shows up.

2 Likes

Thanks! DIdn't know this option, it's exactly what I was looking for!

1 Like