rustdoc: Merge "Structs", "Enums", "Unions", and "Type Definitions" sections on module pages

[camelid]

Summary

Merge the following sections that appear on module (and crate) pages into a single "Types" section:

• Structs
• Enums
• Unions
• Type Definitions

Why?

• Usually, the exact kind of type something is doesn't matter when you're looking at an overview.
• It can be confusing to have to so many sections, and it creates more places where you have to look for what you want.
• After the recent color reduction PR (rustdoc: use smaller number of colors to distinguish items #91480), the types are no longer colored differently, so it makes more sense to merge their sections.

[camelid]

cc @jsha

[jsha]

Terrific idea!

[GuillaumeGomez]

I'm not completely sold on the idea. Something about it is bothering me but I can't put the finger on it... Well, for now let's say I'm neutral.

[wackbyte]

I find the current layout simpler than what's being proposed here. I can understand the reasoning behind it, but each kind of type is fundamentally different in a way where it's quite useful to see them laid out separately.

[redgoldlace]

I understand that the intent here is to simplify the sidebar and make things seem less verbose, but (particularly relating to type definitions) I'm not really a fan of the change. It can be very helpful to know when something falls into a specific "class" of type - without having to jump to its position in the documentation or inspect the source - and I would really hate to lose that. I wouldn't be opposed to making it some sort of a configurable option, but I do think such a proposal does more harm to documentation than good.

I suppose one alternative would be to merge them into a Types section, but add a prefix to each name in the sidebar such as struct, enum, union and etc. That way you can have your cake and eat it too - there isn't a loss of information, but things do get unified nicely. One issue with that idea is the amount of horizontal space taken up by the sidebar, but I'm not sure how much of an impact that would have.

[ThePuzzlemaker]

I support what @kaylynn234 suggests.

I feel like doing this would be counterproductive. I've found that I've had many cases where I need to looking over a module and need to find a specific enum or struct but don't remember the name. And I can't necessarily search for it with enum: if I don't know the name, as doing something like just enum: doesn't work.

Take, for example, an AST module. If designed in a certain way, e.g. Rust's AST/HIR, it will have main structures Foo as well as FooKind enum. Often the module is already quite cluttered, and the structures usually don't contain all the information that you need, instead the enums. If the sections were combined it would become even harder to find a specific enum that you need, so either you have to search through a mess of types to find a struct and then navigate to the enum, or try to guess the name that you need.

For most people, this change will probably not have much effect. But for me, it honestly would likely decrease my ability to navigate certain docs, especially in my programming language projects.

I've already found that removing the color difference between structs and enums and etc. (from #91480) has impacted my ability to navigate through documentation. While I'll likely get used to this, combining the sections would amplify this problem.

[camelid]

Hmm, okay. I won't make this change then. What about just moving the sections so they're all next to each other? Currently, the type alias section is at the bottom, while the others are at the top. Instead, I think they should all be at the top.

[steffahn]

I don’t think type definitions should be grouped with the rest, it’s often important to know that you’re dealing with a type synonym, in particular for custom versions of Result with a fixed error type. (I would also appreciate if a different color for type synonyms was re-introduced.)

---

I’m not sure yet how to feel about structs vs. enums. An alternative, more useful, point for distinguishing could be “abstract types” vs. “plain types”, the latter being structs or enums where all fields are public and non-hidden (and structs / variants are not #[non_exhaustive]). I’m not 100% sure where #[non_exhaustive] enums would fit into this picture, probably still on the “plain” side, not “abstract”.

(Most) primitive types would also become “plain”, i.e. grouped with enums. E.g. bool arguably is closest to an enum anyways.

Anyways, simply merging structs and enums seems reasonable to me, too, unlike merging them with type synonyms/aliases.

[jsha]

FWIW, I'm still in favor of merging the sections. Yes, enums and structs are not exactly the same. But attention is a finite resource. By merging, we focus people on the big, important distinctions (between concrete types, traits, functions, macros and modules) rather than the less important ones - at least at the module summary page level. The pages and hover text will of course always make it clear whether something is an enum or a struct.

[camelid]

I do like the idea of just merging structs and enums. However, if we merge them but not type aliases, what would we call the section? "Algebraic data types" comes to mind, but that's a mouthful and would likely confuse new users.

[steffahn]

@camelid Just “data types”?

[camelid]

Perhaps. People may get confused that "data types" don't include type aliases though 🤷

[camelid]

I do like the idea of just merging structs and enums. However, if we merge them but not type aliases, what would we call the section? "Algebraic data types" comes to mind, but that's a mouthful and would likely confuse new users.

Hmm, maybe just "types" and "type aliases" would be clear enough.

[aloucks]

FWIW, I'm still in favor of merging the sections. Yes, enums and structs are not exactly the same. But attention is a finite resource. By merging, we focus people on the big, important distinctions (between concrete types, traits, functions, macros and modules) rather than the less important ones

I apologize for being blunt here, but you're missing the mark entirely. You're absolutely right that attention is a finite resource, but merging these sections (and making them all the same color) requires more attention, not less. When I'm searching for an enum, now I have to read through a much larger section and there is no longer any way to see what enums are available. You're forcing people with reading difficulties to read more instead of less. Having common items grouped together and color coded allows people to use visual cues to narrow down the amount of text that they need to process.

[camelid]

Could you elaborate on in what kinds of situations you'd be looking for an enum in particular, rather than any kind of type? I think that would help me understand your use case better.

[aloucks]

For example, I want to select an adapter based on a particular device API. I remember that this is a flag, so it's likely an enum, but I can't remember it's name. I scroll down until I see green and then start checking the items. I find Backend.

https://docs.rs/wgpu/0.12.0/wgpu/

When you ask about looking for an enum in particular, why is enum being treated any differently than structs or traits? Why not merge all of the sections into one giant section and color code them all the same way? Why do we have groupings or visual cues at all?

Let's take a step back and try to understand what problem we're trying to solve here. We want to make items more discoverable and easier to narrow down. Groups, color cues, and distinctive sections allow you to do that without having to read though large chunks of text.

[nox]

FYI I already asked for all those sections to be merged into a single one in #64454. I understand that not everyone thinks the same way I do, so I'm not going to claim either way requires less or more attention than the other, and neither should anyone else.

[camelid]

When you ask about looking for an enum in particular, why is enum being treated any differently than structs or traits? Why not merge all of the sections into one giant section and color code them all the same way? Why do we have groupings or visual cues at all?

I think of structs and enums as being very similar (they're both algebraic data types), and in fact, in languages related to Rust like Haskell and OCaml, the same language feature is used to represent both structs and enums. So I think of them as belonging to the same category, whereas traits are a different concept (behavior rather than data).

[camelid]

I'll close this issue since it seems many people prefer the current design.