rustdoc "expand all docs" button does not expand "hidden undocumented items"

[mbrubeck]

In nightly rustdoc, trait items that aren't overridden are collapsed as "hidden undocumented items." (This is slightly inaccurate, since they may have documentation from the trait declaration.) Clicking the [+] ("expand all docs") link at the top of the page expands all docs except for these. This means there is no longer any way to actually expand all documentation.

My use case for this is using the browser's "find in page" feature to search for method names, or to answer questions like "does this type have any methods that take &mut self?"

[dekellum]

"undocumented items" is definitely misleading here, as its very common in the implementation to defer to the documentation of the Trait. If its desirable to keep the distinction, perhaps it could be called "Trait items" (e.g. documented by the trait or not).

In addition, "hidden undocumented items" can be redundant, or simply in the way of the Trait docs, in the expand/collapse hierarchy. Example:

Fully Collapsed

First Expansion

Note expanding here offers no new documentation. Perhaps rustdoc should only add this collapsible sub-section if there is also at least one item that is documented, specific to this impl, that can be given prominence over the Trait docs?

Fully Expanded

Observed from: rustc 1.32.0-nightly (6bfb46e 2018-11-26)

[pickfire]

I just realize having to click to expand one by one feels troublesome today. Should ping @rust-lang/docs for their opinion since this issue is left here for so long.

I recall that the previous behavior to press + to expand all of these again feels better, at least don't need to click one by one if I want to search through it, I was searching for len function in Bytes. https://doc.rust-lang.org/stable/std/str/struct.Bytes.html

[pickfire]

Wrong ping, test ping @rust-lang/docs to see if it is working (just wondering if anyone other than @jyn514 get this)

[mbrubeck]

cc @rust-lang/docs

[GuillaumeGomez]

Strange I never saw this issue. So about this: it's the expected behavior. After we can debate if we want to change this or not, but it's currently not considered as a bug.

[pickfire]

@GuillaumeGomez If there is a page and you want to see all the subsequent methods, how do you do it? Do you click on all the "expand undocumented items" one by one and then ctrl-f to search for the relevant function or maybe click on each trait implementations (link) to find the relevant function?

In diesel, I missed the establish function (for SqliteConnection) just because I didn't click on the trait implementation and took me some time to notice that it has always been there, just hidden under the trait implementations. I wonder if there is a way to do it with less effort? I could use search but the searched trait cannot guarantee to relate to the original struct/enum.

[GuillaumeGomez]

To put it simply: I don't know. The rust doc pages are already super heavy but it remains hard to find some information (on traits mostly). So maybe just changing the behavior of the "expand all docs" button might be enough?

[dekellum]

IMO, it would be an improvement to simply remove the "undocumented items" level of the hierarchy. Or at least I haven't seen the case where imposing this level is beneficial. An associated benefit would be that "expand all docs" would then actually expand all "docs" (sections).

Going a bit further toward the user intent of finding these methods, it would help if all trait methods were listed, nested under the traits in the "Trait implementations" section on the left-bar. In other words, just because such methods happen to satisfy a trait doesn't necessarily give them second class status on the page.

[GuillaumeGomez]

That could be an idea too.

[pickfire]

https://users.rust-lang.org/t/documentation-of-types-discoverability-problem/53274/2

Also, if you go to the "Trait Implementations" section of the BufReader page, you can click [+] just to the left of each impl, and then again next to "Show hidden undocumented items", to see the list of associated items available from that trait. (Although this isn't much fun if there are a lot of impls to go through -- the search box is much more helpful in that case.)

People seemed to have the same issue. Yes, it would be good to have that too but the main thing is to be able to expand all stuff without having to click on each one by one. Even pressing + twice would be fine (I tried that but did not work but not sure if it is easy to discover).

[eminence]

Just chiming in to say that I also heavily use my browsers 'find-on-page' feature (ctrl-f) and not being able to easily expand all docs is a little frustrating (because the browse search functionality will miss things).

But maybe on possible solution is to improve the built-in search functionality, so that it's not necessary to rely on in-browser search.