Rust: Documentation needs indexes (function summaries)

[freinn]

I think that the current Rust documentation for the standard API is "too verbose". Don't get me wrong, is perfectly fine and useful like it is now. But:

• It would be better to have an "index of methods". Just compare the java ArrayList doc to the Rust Vec doc. In the case of the Java doc, an user looking for the method he wants is very fast because all is condensed in a little space. Nevertheless, the Rust Vec webpage is nice, but you have to scroll a lot to find the exact function you are looking for.

I think there are 2 possible solutions to this:

1) Condense the docs in a HTML "list" and show each method example and comments when you click on it.

2) Create an index on the top of the page (or another page) with one-line description of what the function does and a link to the details in the same page (down).

I'm here not just to ask for work. I can help on it if you guide me a little, even being a rust noob.

[freinn]

Ok, I realized just now that if you push the '-' in the top of the webpage, all function definitions collapse so you can see a list of function prototypes. But I think an index page with prototypes + one line explanation, like the java docs, is better.

[steveklabnik]

There are a _lot_ of open issues about rustdoc's output. I thought this was an exact duplicate, but I cannot find it.

[dhardy]

Ok, I realized just now that if you push the '-' in the top of the webpage, all function definitions collapse so you can see a list of function prototypes.

All this time I've been using the API docs and didn't realise that. This aids usability enormously! Can this feature somehow be made more obvious?

Descriptions could maybe even be collapsed by default; usage is quite often clear from the prototype alone.

[joshtriplett]

I just spoke to several developers who had the same issue with rustdoc.

Pressing '-' helps, but ideally, there'd be an index at the top with all the functions, and anchor links to full descriptions below. Much like the trait functions have small summaries rather than complete descriptions.

[steveklabnik]

there'd be an index at the top with all the functions

How is this significantly different than [-]; is it just that it's at the top?

[the8472]

It's on top and needs a click to be activated. Its state is not remembered. You can't use forward/back navigation to jump between index and method description.

And often one might not really care whether the method comes from a trait implementation or a plain impl block, especially if it's a deref. So the trait signatures, being fat <h3>s can lead to visual clutter. And they're often highly duplicated (e.g. for different array sizes, for borrowed vs. owned etc.). The trait information still has to be displayed in some way but I hope an index could provide a more compact way to do it.

[the8472]

Some modules and structs have a lot of prose on top before you can even get to what you're looking for.

• https://doc.rust-lang.org/std/collections/
• https://docs.rs/itertools/0.6.1/itertools/trait.Itertools.html

I realize that there is a navigation on the left that lets me skip down to the modules and structs, but that is still suboptimal compared to javadocs.

• javadocs have the index on top in package documentation
• the top-left rustdoc navigation disappears on <700px browser windows. and so does the [-]
• the navigation appears visually identical to the list of sibling modules

[hobofan]

This seems to be related: https://github.com/rust-lang/rust/issues/14475