Skip to content

Common well-known traits make "Trait Implementations" too verbose #40363

Open

Description

@kornelski

I find the "Trait Implementations" section of Rustdoc very hard to follow. It has low signal to noise ratio:

  • Very common traits are displayed in full detail. For traits like Copy, Clone, Default, Display, Debug, Hash, etc. I don't need to see all the methods inline with their description. Just links to these traits would be enough. Generally I only need to know whether the type implements them or not.

  • Similarly, traits used via operators are also displayed in full detail. Eq, PartialEq, Add, Sub, Ord, PartialOrd, etc. flood the documentation page with documentation of the traits, and the specific methods are even less relevant. The long verbose list makes it hard to see which traits are supported.

  • If the type implements the same trait multiple times for slightly different types, the whole trait documentation is repeated multiple times. It is useful to know which type combinations are supported, but repeated function descriptions only lower signal to noise ratio. It's worst for primitive types where the list appears to be dominated by countless the variants of Shr and Shl, drowning out all other information.

The current layout does work well for less common/more specific traits, e.g. having entire trait documentation inlined is perfect for *Ext traits and makes sense in some cases like impl Read for File.

So I'm suggesting:

  • Implement collapsing widget for trait implementations, which collapses documentation of methods, leaving only [+] impl Trait for Foo line.

  • Collapse basic traits by default (Copy, Clone, Debug, std::ops::*, etc.). Not all traits in std are obvious, so the list of traits to display in a terse form would probably be manually curated.

  • Group implementations of the same trait together, and collapse all implementations except one. For example File displays all of Read docs twice, in two separate places. It makes the list longer and makes it harder to notice that there are two implementations. It would be clearer to display it as:

    [+] impl Read for File
    [-] impl<'a> Read for &'a File
    fn read(&mut self) …

Activity

  1. GuillaumeGomez commented on Mar 15, 2017

    @GuillaumeGomez
  2. added
    T-rustdocRelevant to the rustdoc team, which will review and decide on the PR/issue.
    on Mar 15, 2017
  3. added
    A-docsArea: Documentation for any part of the project, including the compiler, standard library, and tools
    on Mar 23, 2017
  4. changed the title [-][rustdoc] Common well-known traits make "Trait Implementations" too verbose[/-] [+]Common well-known traits make "Trait Implementations" too verbose[/+] on Mar 23, 2017
  5. added
    T-dev-toolsRelevant to the dev-tools subteam, which will review and decide on the PR/issue.
    on May 18, 2017
  6. vi commented on Jan 29, 2018

    @vi
    Contributor

    Implement collapsing widget for trait implementations, which collapses documentation of methods, leaving only [+] impl Trait for Foo line.

    Thinking about implementing this.

  7. added a commit that references this issue on Jan 31, 2018
  8. vi commented on Jan 31, 2018

    @vi
    Contributor

    Is there some exhausive list or traits (in std or maybe across the entire ecosystem) that should be collapsed by default?

  9. kornelski commented on Jan 31, 2018

    @kornelski
    ContributorAuthor

    I'd look through std::ops, as these are the noisiest.

  10. vi commented on Jan 31, 2018

    @vi
    Contributor

    It is also suggested just to collapse all impls items by default. It is simpler.

  11. removed
    A-docsArea: Documentation for any part of the project, including the compiler, standard library, and tools
    on May 29, 2018
  12. added a commit that references this issue on Jun 16, 2021
  13. removed
    T-dev-toolsRelevant to the dev-tools subteam, which will review and decide on the PR/issue.
    on Jan 18, 2022
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    C-feature-requestCategory: A feature request, i.e: not implemented / a PR.P-lowLow priorityT-rustdocRelevant to the rustdoc team, which will review and decide on the PR/issue.

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions