Rustdoc: unify impl blocks where possible.

[richard-uk1]

From #32631:

We'll have to be sure to update rustdoc, however, to provide one unified view to the API surface area rather than multiple impl blocks.

I have run into a similar problem when using codegen (specifically, in web-sys), where currently each function/value is inside its own impl block, e.g.

impl Event {
    pub const CAPTURING_PHASE: u16 = 1;
}
impl Event {
    pub const AT_TARGET: u16 = 2;
}
impl Event {
    pub const BUBBLING_PHASE: u16 = 3;
}
impl Event {
    pub const ALT_MASK: i32 = 1;
}

Presently all these appear as separate impl blocks in rustdoc. It would be easier to read if they were in a single block.

[richard-uk1]

I'd like to help implement this, but I've not hacked on rustdoc before.

[ExpHP]

Sometimes this might be done deliberately, e.g. breaking impls into sets of 2-4 methods to keep where clauses closer to methods, or to write docstrings on the impl blocks.

[richard-uk1]

Hmm, I'm not sure how to reconcile the two things. I didn't know you could write docs on impl blocks. I'm not proposing unifying impl blocks with different where clauses, they should stay separate. So these would have 2 blocks in the docs

impl<T> Vec<T> {
    // ...
}

impl<T> Vec<T>
where T: Clone
{
    // ...
}

whereas these would be unified

impl<T> Vec<T> {
    // ...
}

impl<T> Vec<T> {
    // ...
}

EDIT I guess I'm arguing that which impl block a function is in (with the same generic constraints) is an implementation detail that shouldn't leak. There is the orthogonal issue that rustdoc doesn't necessarily order the fns/structs/etc. in the most logical order, compared to something like documentation in elm, where the user must specify the layout of the items.

[steveklabnik]

Triage: don't believe there's any change here

[richard-uk1]

It would be great to be able to do this even if behind a flag or similar - the web-sys docs would benefit greatly from this.

[tczajka]

Sometimes this might be done deliberately, e.g. breaking impls into sets of 2-4 methods to keep where clauses closer to methods, or to write docstrings on the impl blocks.

A solution to this is to unify those impl blocks with the same docstrings and where clauses.

[richard-uk1]

I think that unifying on the same doc string is a great idea!

…

On Sun, 19 Sep 2021, 11:45 Tomek Czajka, ***@***.***> wrote: Sometimes this might be done deliberately, e.g. breaking impls into sets of 2-4 methods to keep where clauses closer to methods, or to write docstrings on the impl blocks. A solution to this is to unify those impl blocks with the same docstrings and where clauses. — You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub <#52563 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAKT4XSVWFBF3ZVZ4YP2WQTUCW5MRANCNFSM4FK7H5XA> . Triage notifications on the go with GitHub Mobile for iOS <https://apps.apple.com/app/apple-store/id1477376905?ct=notification-email&mt=8&pt=524675> or Android <https://play.google.com/store/apps/details?id=com.github.android&referrer=utm_campaign%3Dnotification-email%26utm_medium%3Demail%26utm_source%3Dgithub>.

[dylni]

Related: #82408