Include a list of struct methods in reference sidebar on struct pages

[mqudsi]

This is a suggestion for the formatting of reference pages for structs in rustdoc, in particular, to discuss the addition of a linked table of impl to the sidebar which would serve as

a) a quick way to identify methods a struct exposes which can be a great way to quickly find a function you know should exist but don't know the name of in rust, and
b) an easy way to navigate overly-long reference pages (currently, several parts of the rust book and documentation recommend "using ctrl+f to find the impl for xxxx"

As a concrete example, my suggestion would be for the string reference page to change like this:

There are of course several questions about the layout and formatting of such a table. Should arguments be included? If yes, they add not-inconsiderable visual clutter, if no, what about overloads? Are they presented in alphabetical order or in the order they appear in the document? Do we include functions from trait implementations? Do we put them in a separate list?

Thanks for considering.

[est31]

I think the info is too complex to display in the sidebar, and already now you can click the - icon to get an overview.

[QuietMisdreavus]

cc @rust-lang/docs

So, back in the halcyon days of December, I tried writing a table of contents like this. I didn't go to the point of writing out every single item, though; I just stopped at the headers. If this were accepted, I could just resurrect that branch.

[mqudsi]

Just for reference, (and perhaps as a counter to the "too much to list" argument) other projects include functions in the sidebar as an expandable list. Here's Microsoft's documentation for the string class for comparison:

And here's a screenshot with the functions list expanded, showing how they deal with overloads:

[est31]

@mqudsi just because they are bad you shouldn't imitate them. Also, C# has a much simpler type system and not all this bounds/trait stuff that we have.

[mqudsi]

@est31 that's a little harsh, isn't it? C# developers seem happy with their ecosystem, and MSFT's documentation structure and layout has changed many times over the years... a more natural conclusion would be that they found this to work (for them, at least).

[est31]

@mqudsi I'm happy with what's present with rustdoc today, and I don't want us to regress.

[QuietMisdreavus]

On the other hand, for several types in std, there's so many methods that having to navigate them all is fairly imposing. And the [-] trick is fairly unknown, too. I think having some kind of table-of-contents would be helpful, even if it's just the high-level links I started adding.

And for reference, several of .NET's core types have just as many items - methods, fields, etc - on them as several of Rust's, if not more. The expanding sidebar table of contents is how they chose to introduce discoverability into their documentation. One could say the in-doc search is how rustdoc introduces that, but that's more of a means to find something you already know. It's hard to browse through the search bar.

[QuietMisdreavus]

I've finished up that code work and made a PR in #41280.

[steveklabnik]

This has been fixed!