Group navigation items in the docs by source crate/module

[cmpute]

I posted a thread in IRLO for this feature request, and it seems nobody is against it. Therefore, I come to post an issue here.

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.

Current behavior

(This documentation comes from dashu-int::UBig)

Proposed behavior

The style for the module names is to be defined.

[fmease]

@rustbot label C-enhancement T-rustdoc A-rustdoc-ui

[cmpute]

I just tried to implement this feature and got it basically working, right now the rendered page looks like:

There are two questions I'm not sure about:

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?

[cmpute]

Here is a new trial: page1, page2. In these examples, I combine all groups (modules) that only contains one trait into a single group called (ungrouped), and I also grouped the traits in sections of auto and blanket trait implementations.

[scottmcm]

Pondering: does this need the module information? Would crate headers be sufficient?

[cmpute]

Pondering: does this need the module information? Would crate headers be sufficient?

What's the drawback of having module information? Group with modules can provide fine-grained categorization, but it does take more space in the side bar.

The benefit is especially noticable for traits in std / core, because there are various traits for different purposes in them.

[jsha]

Thanks for thinking about this problem @cmpute, and prototyping a solution!

I think this is not the right solution, though. You mention that most types have few methods and many traits, but I think that's not universally true. Plenty of types (particularly in std) have many methods and few traits.

And there are some traits that are extremely common, like Clone, Debug, and Eq. Your approach adds a lot of visual noise in the sidebar to give each of those traits its own heading, because they happen to be in separate modules. But the current status quo, where the traits are children of a single heading, allows convenient quick skimming so long as the type doesn't have too many trait implementations. For example:

You're right that for numeric types, the sidebar is incredibly noisy. This is particularly due to the nature of the mathematical traits, where each trait (e.g. Add) needs N implementations for the N numeric types it can interact with. Then multiply by another 2x since you need separate implementations for winding up on the left or right side of the +, and then another 2x if you want to implement for both T and &T, as dashu-int does. And that's just for a single trait! It explodes combinatorically.

Probably the core::ops traits are special enough that we should give them their own treatment in rustdoc. For instance: normally, the sidebar includes the trait parameters because that's an important part of the impl. However, for numeric types this is not so useful, since the type probably implements each trait for a predictable set of type parameters. Also, normally, the sidebar is presented in alphabetic order while the main documentation is presented in order of implementation.

What if we introduced a "Numeric Trait Implementations" section, in both the sidebar and the main document. It would handle all the traits from core::ops. For the sidebar, instead of listing Add<u8>, Add<u16>, etc., it would just list Add. In the main document, rather than a repetitive listing of all the impls, it would present a summary:

Add

UBig can be added to: u8, u16, u32, u64, u128, usize, and UBig, resulting in a UBig.
UBig can be added to IBig, resulting in an IBig.
&UBig can be added to: &u8, &u16, &u32, &u64, &u128, &usize, and &UBig, resulting in a &UBig.

Rustdoc could also detect when the operations are not symmetrically defined, and say e.g. "IBig can be on the left hand side of an add operation with UBig".

This would happen to solve another problem: In the std docs, the numeric primitive types are some of our largest pages, and the slowest to load. The massive number of implementations is not very informative to the reader. A summary would be much more informative. And while rustdoc tends to mimic the presentation of the source code, this is a place where it diverges: the numeric traits are almost never implemented by hand because it would be so tedious and error prone. Instead they are usually implemented by a macro. So there's no reason for the documentation to be so much more verbose than the source code.

[jsha]

Or perhaps a more useful format to present the summary would be a table:

UBig	+	u8	-> UBig	commutative
UBig	+	u16	-> UBig	✅
UBig	+	IBig	-> IBig	✅
IBig	+	UBig	-> IBig	✅

[cmpute]

Thanks for your reply! I think it's a good idea to only document operator traits! But one concern come to mind is what about user defined "operator" traits? Such as num_traits::Pow, dashu_base::DivEuclid. Maybe it's better to create an attribute like #[doc(trait_collapse)] (naming is so hard lol), that can be applied to a trait, and then we group all the trait implementations with this mark into a compact form.

For combining the docs in the main document, I'm guessing it's not a perfect solution to combine the trait docs. Maybe it's okay for core/std docs, but I'm hoping for a more generalizable solution for other traits (including user defined ones). And what if the user indeed has specialized documentation for the implementation (though in this situation maybe it's okay to just not combine them)

I also want to mention another point I have when I proposed this change. One benefit of grouping the traits by module is that, the relevant traits are closer in the sidebar. For example, serde::Serialize and serde::Deserialize will be next to each other rather than pretty far away in an alphabetical order.

[cmpute]

Or perhaps a more useful format to present the summary would be a table:

UBig + u8 -> UBig commutative
UBig + u16 -> UBig ✅
UBig + IBig -> IBig ✅
IBig + UBig -> IBig ✅

This is awesome! But how to support user defined traits is still a question

[jsha]

one concern come to mind is what about user defined "operator" traits?

The way I think of this is: rustdoc is a tool to help the doc author write docs. Sometimes it's much harder to make the tool write the docs than for the crate author to write them.

So in this case, the crate author could write a section with a summary like the one I provided, listing all the types for which Pow and DivEuclid are defined. And then to prevent impls for those traits from cluttering up the sidebar, they could use #[doc(hidden)] on the impl.

This has the downside that the doc author could make a mistake when hand-writing their summary. However, the author could improve on this by automating creation of the summary inside the macro they use to generate all the various trait implementations.

[cmpute]

I'm not aware of a way to automate generation of this kind of table in rust macro, do you mean using a proc-macro or something? How about using an attribute item as I proposed? By this way we can help the automate this process for everyone.