The rustdocs isn't perfect but the way you portrait the problem is somewhat abstract or at worst, sorry, selfish. Those traits miasma is there for advanced reference, it is useful when troubleshooting errors or determining types (that's what reference do).
Lots of information is not meant to be read at once. You start from what type you have (that impl the traits) then look at the possible associated methods or return type, etc.
If you need to know how to use the crate, don't read the references. Read the examples in the repo or the user of the crate.
We cannot and should not try to optimize for the people who don't even try. If someone isn't willing to actually read the documentation of a crate when learning how to use it, there is nothing we can feasibly do to make their experience good.
No, because that's not what the frontpage is. It's for root-level docs. Imagine you actually did replace the front page: what happens when someone actually wants something else from the crate? Where do they go? Since you've advocated against written documentation, their only option would be to blindly click around until they stumbled on the exact right thing. Exactly what you don't want.
That's not the same thing. I'm a little confused how you conflate the two, actually.
Then the crate author needs to actually write some docs. No amount of beautiful formatting and structuring can tell you how to use a crate. Cargo doc most certainly cannot be expected to automagically detect what parts of a crate are most "important" and highlight them for you.
What you are asking for is impossible and inconsistent. If you're too lazy preoccupied to read the docs, then ask an LLM. Blindly clicking around and looking at signatures is never, ever going to be a viable way to learn how to use any given crate, and we shouldn't be prioritizing that.
I'm sorry, but you're the one who went there. Nobody forced you to click those links or look at that text; it wasn't in front of or blocking or hiding any critical information. You went there and then complained about it online. If you want out, click the back arrow in your browser.
I'm left wondering, what could you possibly expect us to do to prevent people from clicking links that have to be there? Just like no amount of traffic control signs or signals can stop people from driving straight off the road, no amount of handholding in the docs will stop people who make zero attempt to use the docs right.
I'm just saying that there is something like information architecture and there are somewhat objective measures of navigability and findability.
Not sure what the way forward here is:
Some minor improvements here and there to improve the IA of Rustdocs step by step towards this goal (if it can even be agreed upon what those steps would be).
Having somebody who's done this before at scale redesign it into something that's more usable and also more aesthetically pleasing.
My time, energy and focus are too limited to be able to do much more here. I was just wondering whether I'm the only person who's having a hard time navigating this thing every time.
Actually, I expect such a page documenting a trait (or type) by indexing all their available methods and functions organized by inherent and trait origin could indeed be auto-generated and also include blanket traits.
Additionally, traits and types with custom implementation for their constrained versions may be considered distinct and given their own auto-generated page and cross-referenced with the base version for convenience.
To be honest im on phone and didnt check it thoroughly. You may look at it, I only suggest it.
It is also worth considering that not all humans explore in the same way.
So maybe there are modifications that would make it more accessible to a segment of readers that may search slightly differently. Like a setting + cookie, where one switches between two layouts, that group things differently. And this is remembered.
And sometimes the crate docs are a bit empty or noisy imho. Not bad at all, but still to be improved.
PS maybe the guys from Brown University could research this, using metrics and stuff. Could be interesting.
I do hope that the structure of crate reflected in the nav. I'm in good term for a change like that. Is that direction you mean more natural?
Earlier, I'm getting impression that @alper wants to list all associated method as if it is free function in the front page. That's what I'm not agreed with. Trait assoc fn is meant inside a trait.
Hmm. When I view that page, the links aren't underlined unless I'm hovering my cursor over the link. As a result, I didn't realize those were links. I've always clicked on Traits in the navigation panel on the left, then clicked on Itertools (which, by the way doesn't have an underline even when I hover over it). Having the underlines always visible would be a step in making links more obvious and discoverable. (I'd ask for links to be old school blue like in the early Netscape days, but I'm betting that would not be well received.)
That's where usability and âdesignâ clash. Apparently making things stylistically obvious is not acceptable, these days, because it makes things âgarishâ, different elements âclashâ and the end result is not âmodernâ.
So you either need to use tools that make things looking âold-schoolâ or accept the fact that slight difference in color is all you get, in a modern webâŚ
This is indeed more or less what a good user guide should look like. But it's a part of documentation distinct from the auto-generated API reference, which is indeed a reference with a different purpose. Rustdoc cannot write a user guide, though, unless an LLM gets added to it (the deepwiki site is, of course, LLM-written). What Rustdoc could do, though, is to enable the library owner to add more metadata to the code so as to better organize stuff, for example categorizing the dozens of Itertools provided methods under topics like "filtering" or "aggregation".
Yeah, true, and optimally all crates would have such extensive root-level doc comments (and also module-level comments in all child modules). The std docs also make use of dummy modules and magic attributes in order to document keywords and primitive types (std/src/keyword_docs.rs and core/src/primitive_doc.rs [not sure why the former isn't available in core docs ])
