You can control it as described here: The #[doc] attribute - The rustdoc book
These attributes are used on use
statements, and control where the documentation shows up. For example, consider this Rust code:
pub use bar::Bar;
/// bar docs
pub mod bar {
/// the docs for Bar
pub struct Bar;
}
The documentation will generate a "Re-exports" section, and say pub use bar::Bar;
, where Bar
is a link to its page.
If we change the use
line like this:
#[doc(inline)]
pub use bar::Bar;
Instead, Bar
will appear in a Structs
section, just like Bar
was defined at the top level, rather than pub use
'd.
Let's change our original example, by making bar
private:
pub use bar::Bar;
/// bar docs
mod bar {
/// the docs for Bar
pub struct Bar;
}
Here, because bar
is not public, Bar
wouldn't have its own page, so there's nowhere to link to. rustdoc
will inline these definitions, and so we end up in the same case as the #[doc(inline)]
above; Bar
is in a Structs
section, as if it were defined at the top level. If we add the no_inline
form of the attribute:
#[doc(no_inline)]
pub use bar::Bar;
/// bar docs
mod bar {
/// the docs for Bar
pub struct Bar;
}
Now we'll have a Re-exports
line, and Bar
will not link to anywhere.
One special case: In Rust 2018 and later, if you pub use
one of your dependencies, rustdoc
will not eagerly inline it as a module unless you add #[doc(inline)]
.
The default will depend on whether or not the item's original definition is visible, and it explains the difference between the examples you link:
The types of the bytes
crate being defined in a module is an implementation detail; that module is private, and thus undocumented, hence the documentation for those types must instead be generated at the place where the items are publicly re-exported. On the other hand, ic_types
has types that live in public modules principal
and hash_tree
, so that in those modules the types have documentation pages, and inlining the pub use
would duplicate this documentation.
TL;DR, those defaults often make a lot of sense, you’d have to argue why in your opinion “the later one is the ideal behavior”, and whether e.g. that applies to the concrete example of the ic_types
crate as-well.