Group navigation items in the docs by source crate/module

I would like to propose a feature request for the rustdoc. For the documentation generated for a type, it seems great to me if the trait implmentations can be grouped by the name of source crate (even source module) in the left navigation panel. Usually, a type won't have too many methods but it can have numerous trait implmentations (especially for numberic related types such as BigUint and rug::Integer).

People usually don't browse the trait implementations by the alphabetic order, they do directly by searching. But sometimes if I don't know which trait I'm looking for, but just want to know what functionalities the type support, it will be great if I can find the implementations by the crate / module name. For example, the implementation of all the arithmetic traits (Add, Sub, etc) can be grouped by the core::ops module name.

I would like to create an issue for this if there's not an approach that I just haven't known yet.

4 Likes

FYI, I have created an issue for this and have done some preliminary work. Here are two examples: page1, page2.

There are three questions I'm not sure about, which are mentioned in the issue:

  1. Should the module names be embedded in the title like the picture above, or they should be formatted as subtitles under the "Trait Implementation" section?
  2. Is it useful to have some rules to simplify the groups to prevent generating too many groups (such as don't create a group if there is only one trait in that group)
  3. Do we also group the traits in the sections for auto and blanket trait implementations?

Please give some comments on these choices if you are interested in this change :blush:

In source code I usually try to order trait implementations in order of decreasing rarity: boring stuff like Default or Clone comes at the bottom, bespoke local traits near the top. Maybe it would be feasible to do use similar heuristics here? At least could do local traits, then foreign non-std traits, then std traits?

That's a great suggestion! But I'm not sure if it's the same case for all users, because for me, std/core traits are often very useful and important as well. How about we put the local traits at the top (with name crate::xxx, and put other trait groups under them sorted alphabetically?

Second thought: I'm not sure how this heuristic will get along with the std library docs itself, displaying crate::xxx for std traits seems weird.

This topic was automatically closed 90 days after the last reply. New replies are no longer allowed.