rustdoc: provide summary views

[aturon]

When viewing a specific type, rustdoc currently spreads out information about the applicable methods, arranging them by trait and including documentation per method.

While this is an important view to have, it would often be very useful to see a single summary list of method signatures that apply to a given type. Something close to what you see currently when you view a trait.

These methods could be listed as a separate summary section, or through some kind of slide out (see the "synopsis" button at http://hackage.haskell.org/package/vector-0.10.9.2/docs/Data-Vector.html for example). They can be hyperlinks to more detailed documentation.

[aturon]

cc @bjz

[japaric]

a single summary list of method signatures that apply to a given type

Is the new "collapse all" view like what you had in mind?

[liigo]

Has a summary view that list all methods in one line would be nice:
method1,method2,...,methodn (sory by alphabetical order, with links on every method)

[Swatinem]

There should definitely be a TOC that lists all possible methods of a particular type.
Rustdoc is really confusing to use for a newcomer. I expect there to be an alphabetic list. Instead I have to basically scan the whole document searching for the right trait and generics-trait combination that provides that particular method.
While at it, that TOC should also distinguish contructors (static methods) and normal methods (#15070)

Also, it would be nice if the detailed description could be inlined. Right now I have to click through to the trait that provides that method to see what it does.

[Gankra]

cc me

[thehydroimpulse]

/cc me

[brendanzab]

Hey guys, you can set the notifications in the sidebar -> (no need to cc)

[thehydroimpulse]

@bjz Because I'm already watching this project, I'm already "subscribed" (but no email and stuff), so I need to comment to get real notifications (email, etc...)

[steveklabnik]

Triage: no change. @japaric brought up 'collapse all', but nobody has replied if that's not enough, or what would make this different, though.

[steveklabnik]

Triage: no change since last year.

[mathw]

I came by looking if there was an existing issue about this. I've been writing a fair bit of Rust lately and really missing a table of contents of methods for structs.

The collapse all button does work really nicely - but I didn't even know what it was until I read this issue. I therefore don't think the [-] is very discoverable.

It is still confusing though that some pages get a table of contents of methods and others don't. Perhaps if no pages had a table of contents I would have gone looking for something else and hovered over the collapse button long enough to see the tooltip.

It actually solves both problems I had, the other one of which doesn't actually have an issue currently but maybe I don't need to file a new one - in the default expanded state, the docs are really hard to skim-read for a method name. This is a combination of things, but the biggest issue is that there's not much space between items (I have been experimenting with adding more whitespace above the method names to separate them visually from the preceding method's documentation; and then the next biggest issue is that if there are any headings in a method's docs they look visually more important than the method name and grab the eye.

Now, collapsing all eliminates these issues when scanning the file for a likely-looking method because you don't know if the type you're looking at even has a suitable method for what you want to do, but you do have to know that the function actually exists.

In fact, with the way I use the docs most of the time now, I would very much like them to load in a fully collapsed state - although collapsing the method docs while keeping the initial descriptive section open would be a better default state. Whether this works for people in general though I don't know - they do then have to know that they can expand the method definitions rather than assuming all the methods don't actually have any docs!

[JanZerebecki]

Similar issues: #15642 #28056 Related: #37061 #24483 #39919