[rustdoc] Have a more nuanced take on what is hidden by default

[Manishearth]

https://twitter.com/mcclure111/status/1361025145125634061

By default, we:

• hide attributes
• hide structs
• hide unions
• hide traits
• hide trait implementation
• hide implementor list

I feel like traits probably should be shown by default, since everything on the trait is important, especially for implementors.

Furthermore, it might be worth splitting "structs" into "structs with all-public fields" and "structs with private fields" for the same reason (with unit structs being treated as having all public). For the former kind the actual struct declaration is super useful, for the latter kind it's not at all.

cc @rust-lang/rustdoc

[GuillaumeGomez]

The traits were the original reason why we added the possibility to change the settings. As far as I can tell, it's the same methods' header, but maybe I missed something? If not, I'm not sure to see how it would improve anything. As for the rest, why not!

[camelid]

Another way to solve the problem: #81977

[mcclure]

Hi, I'm the person linked on Twitter-- my perspective is that I am learning Rust and the first time I looked at
https://doc.rust-lang.org/std/convert/trait.Into.html
I was very confused because I was scrolling down the page trying to find the type, and once I found the type there was a "T" but I could not see where T was defined/bound. I had scrolled right past the light gray
[+] Show declaration
without even taking note that there was a clickable thing there that I was failing to click on.
Then I asked for help and one person explained it to me.
Now I know to expect that docs.rs pages have light gray [+] expandables, and I probably won't make this mistake again.
But on my very first visit, I did get confused until I asked for help.
I don't know if something needs to be fixed here or what the right fix is.

[GuillaumeGomez]

@camelid: Oh wow. thats so simple yet so nice! What do you think of it @mcclure?

[mcclure]

Honestly yes I think @camelid 's suggestion would help. Since the name up top looks like a "header" for the entire document, it is natural that we should expect "T" to be reused again and again in the same way throughout the same page if it is in that "header" name.

But it is not so obvious to me that if in a hideable (hidden by default...) section at the top you define a T within a { bracket } section you then close again, that every T throughout the page should be expected to be that T from the { brackets } at the top (if that way of putting it makes sense).

[jyn514]

I would rather show the trait definition by default than show the generic parameters. Showing the parameters won't help much for associated items, and could get overwhelming if there are a lot of parameters.

[GuillaumeGomez]

Sorry, I'm not sure to fully understand what you mean. In #81977, it's suggested that we add the generics in the "title" but also in the fields/variants.

I thought that your issue was that currently, those generics were only visible in the hidden section. If so, wouldn't #81977 fix this problem? If I'm completely off the plate, more explanations of your problem are welcome. :)

[GuillaumeGomez]

I would rather show the trait definition by default than show the generic parameters. Showing the parameters won't help much for associated items, and could get overwhelming if there are a lot of parameters.

That is a good point too. If possible, I'd prefer to not have the trait definition displayed by default. Just look at Iterator, it's (in my opinion) far too big to be really useful. As a reminder: we hid the traits' definition by default in the first place because people complained about it.

[jyn514]

As a reminder: we hid the traits' definition by default in the first place because people complained about it.

Do you have a link to that discussion? It was before I joined the team.

[GuillaumeGomez]

Time for speleology!

[Manishearth]

That is a good point too. If possible, I'd prefer to not have the trait definition displayed by default. Just look at Iterator, it's (in my opinion) far too big to be really useful. As a reminder: we hid the traits' definition by default in the first place because people complained about it.

This is kinda what I'm getting at with "nuanced take". What did people actually complain about, trait definitions or Iterator? I think short traits like Into/etc lose out by being hidden, but yes, giant traits like Iterator do not. There's a similar nuanced take to be had on Options-style structs with public fields vs structs with private fields.

I actually think our current situation with a bunch of prefs for kinds of items is suboptimal, I think we should have the prefs, but perhaps have better takes on what the defaults should be, takes that are not just based on the types of items.

[GuillaumeGomez]

That seems reasonable indeed. But on big items, wouldn't the missing generics information still be an issue?