Re-exports v.s. Structs/Enums/Traits in doc

To make items like struct, enum, trait available from library root, we often have pub use sub_mod::SomeStruct in root lib.rs.

When looking at the home page of doc site generated by cargo doc, sometimes the items are shown in Re-exports section, sometimes they live in Structs / Enums / Traits.

For example:

struct Principal,HashTree are in the Re-exports section.

struct Bytes, BytesMut are in the Structs section and has one-line explanation next to them.

How can I control such behavior? The later one is the ideal behavior.

You can control it as described here: The #[doc] attribute - The rustdoc book

inline and no_inline

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.

1 Like

This topic was automatically closed 90 days after the last reply. We invite you to open a new topic if you have further questions or comments.