Rustdoc inlining trait when it should not be.

[sgrif]

I originally noticed this when chasing down dead links on Diesel's docs. Currently https://docs.rs/diesel/1.0.0-beta1/diesel/prelude/trait.GroupedBy.html looks for a JavaScript file that doesn't exist. The reason for that is because this trait is being rendered in the wrong module. The module structure that led to this is:

pub mod associations {
    mod belongs_to {
        pub trait GroupedBy {}
    }
    pub use self::belongs_to::GroupedBy;
}

pub mod prelude {
    pub use associations::GroupedBy;
}

I would expect that rustdoc would treat the "public" location of this trait as associations::GroupedBy, and not inline it anywhere else unless there's a #[doc(inline)].

Interestingly, there's also a pub use self::prelude::*; so this appears to not affect glob imports.

[QuietMisdreavus]

If i remember rustdoc's reasoning correctly, it looks at the original declaration of GroupedBy whenever it sees a re-export of it. If the original declaration is publicly reachable, then it will not inline it. If not, then it will. This causes a problem here because GroupedBy is originally declared in a private module, then re-exported in its "proper" place, as well as the prelude. From rustdoc's perspective, though, either one could be the proper place for it! The actual declaration is hidden, so it can't know!

You can hint to rustdoc by applying #[doc(inline)] and #[doc(no_inline)] to the re-exports to tell it which ones should render the full docs and which ones should render just a pub use statement in the module. There's currently no way to tell rustdoc that a given re-export is the "canonical" location, though.