Rustdoc: List impl interface before describing impl methods

[gsingh93]

Lots of languages have documentations where you can see the entire interface of the class before digging deeper and finding out what the methods do. For example, look at how the Java documentation is structured (C++ docs on multiple mainstream sites are similar): http://docs.oracle.com/javase/7/docs/api/java/util/ArrayList.html

There is a high level overview of the class, a list of methods with one line descriptions, followed by the same function list with more detailed descriptions. The list of methods links to the more detailed descriptions.

This structure allows a user who doesn't know the exact name of the method they're looking for quickly find the method. Contrast this with the current way rustdoc does things. Look at this page: http://doc.rust-lang.org/std/vec/struct.Vec.html

I have to sift through all the functions and their descriptions as I look for the function I want. The functions aren't alphabetized either, so if I am looking for a function, I can't find it alphabetically.

I don't know whether it would be good to show Traits methods in this list or not.

[Gankra]

Is this at all resolved by the fact that their is a "collapse all" and "expand all" button? I appreciate that this doesn't work for noscript users, but I consider it to be vastly more usable than an index.

[gsingh93]

Its mostly resolved. I think the fact the functions aren't alphabetized is a related pain point for searching for methods.

[gsingh93]

Does anyone else agree that the API documentation would be better if it was alphabetized, or is that just me? It's way easier for me to find methods visually, although I guess I could use Ctrl+F, but I don't always know the exact name.

I looked into how one would implement this, and I got it working locally just by implementing Ord on clean::Item and then sorting the items list before looping through it. The only downside I saw was that it's nice having "constructor" methods at the top and sorting methods means they're usually not at the top, but we could probably identify those as all methods that don't take self as an argument and return Self.

[killkrt]

As I wrote in this post in my opinion it would be great to have a quick indication whether a struct implements the Copy trait, since it is a very important information in Rust.
Furthermore I agree with @gsingh93, it would be better if the documentation was alphabetised, also having clear section for builder (function of form fn method(not self) -> Self) methods would be great.

[steveklabnik]

Triage:

Its mostly resolved. I think the fact the functions aren't alphabetized is a related pain point for searching for methods.

Given that we want to totally re-think rustdoc, and this hasn't had any comments in a very long time, and is basically all resolved, I'm going to give this one a close, as I don't think we need to track it down to this level of detail. Thanks!

[gsingh93]

Is there a thread somewhere where the redesign of rustdoc is being discussed?