rustdoc: remove redundant toggles for "undocumented items"

[jsha]

Rustdoc has some code to hide "undocumented items." As far as I can tell, that applies to trait implementors (on trait pages) and trait implementations (on struct pages). However, there's already an outer layer of toggles for both the implementors and implementations. For instance, this is what the "implementations" section looks like for the Read trait, if your settings expand implementations by default:

---

---

The toggle for each implementation is redundant with the inner toggle for the undocumented items. I think we should remove either the outer toggle or the inner. I'm not sure which is better. One argument in favor of removing the outer toggles: If someone has gone to the trouble of documenting a trait implementation, we should try to display that by default. For instance, here's what the implementations section looks like for String, by default:

---

---

However, if you know to expand it, there's actually some really nice documentation there:

---

---

There's a similar situation in rustls: Its Read implementation has important documentation on how to use it properly, but you wouldn't know that documentation was there because it's toggled closed by default.

[jsha]

Also worth noting that the "Show hidden undocumented items" don't respond to the "show all / collapse all" toggle in the upper right, and don't have a corresponding settings.html entry to show or hide them by default.

Part of #83332

[GuillaumeGomez]

Done in #84754. Don't hesitate to re-open if I missed something but from what I read, it's now done.

[jsha]

In #84754, we migrated the existing toggles to <details> But what I'd like to consider is either removing the toggles for "undocumented items", or removing the toggles for "implementors," or otherwise finding some improvement so we don't have two levels of toggles when it's generally not necessary.

[jsha]

I think we should split this into two cases:

Implementations on struct and enum pages

Example (default view)

Example (toggles expanded)

This demonstrates that the wording "Show hidden undocumented items" is incorrect - these items actually are documented, on the trait itself. That documentation gets copied to the struct or enum page. We're paying the cost in bytes and DOM size for these docs; we should show them by default. And that default can be modified by the "Auto-hide trait implementations" setting.

Or, another way of looking at it: If you are looking at some code that calls a method on ErrorKind, and you want to know what that method does, you'll go to the ErrorKind page and Ctrl-F for it. You should be able to find the method regardless of whether it was implemented as part of a trait or not. This is a use case I definitely had early in my Rust journey, and still occasionally do.

Implementors on trait pages

Example (default view)

Example (toggles expanded)

When you're on a trait page, the thing that's most useful to know is that type T implements the trait. The "undocumented methods" really are repetitive on a trait page and should be hidden. But I think, more than hidden, they should actually be entirely unrendered, since they duplicate information already on the page in the trait definition.

There are two things that should potentially be shown under each implementation in the Implementors section of a trait page:

• Methods that have documentation (but this probably belongs on the docs for the implementing type, not on the trait page)
• Whether the type implements any of the optional methods of the trait.

Proposal

I propose to remove the toggle for "undocumented items" on struct and enum pages, making the contents always visible. I propose to remove the method documentation for Implementors on trait pages, leaving that information to the implementor's own doc page.

[GuillaumeGomez]

That would simplify the code a bit. I don't have a strong opinion on this topic though.

What do you think @rust-lang/rustdoc?

[jyn514]

I really like both those ideas :) although maybe it makes sense to collapse the method descriptions by default on type pages, since they're always the same and can be long? I don't feel strongly about that though.

[Nemo157]

One thing I'm unsure about is how this will feel on pages like Box that have all the traits.

I somewhat commonly skim through the trait list looking for specific traits I care about, but I could just turn "Auto-hide trait implementation documentation" back on (sidenote, it appears to be broken on nightly).