TRPL: Fix the enums chapter #25348
TRPL: Fix the enums chapter #25348
Conversation
| `Character` to be either a `Digit` or something else. | ||
| relates a set of alternates to a specific name. Each variant of an | ||
| `enum` is defined like a struct, and can hold any data (or no data, like | ||
| a unit-like struct). |
There was a problem hiding this comment.
I'm not sure how I feel about this characterization. I can see where you're coming from, but these things are very separate in my brain.
There was a problem hiding this comment.
I'm mostly going for the fact that, syntactically, each variant of an enum is written like one of the ways to write a struct definition. If you're getting at, e.g., people wrongly thinking that you can use a variant of an enum as a standalone thing (like write an impl for a single enum variant), then yeah, I get that distinction. Would rephrasing this to make it clear that it's about syntax, not (so much) semantics, help?
There was a problem hiding this comment.
Yeah, I think that might make it better :)
|
Hey @geofft ! Thanks for this. Looking back at those chapters, it's true that there's a little lack of coherency now. I still feel that enums belong before match, as they're perfectly suited for each other. I like a large number of these changes, but do have some nits. |
The match chapter doesn't match on enums at the moment, so I put enums immediately after match, so that I could give an example of exhaustive matches on enums (which I think is one of the most useful things about them, and also a good example of tagged unions in particular) without having to explain match. If you want to do structs, enums, and then matches, then we should put an example of matching on enum variants in the matches chapter. I can update the PR to do that. |
|
Yeah, let's do that move. :) Do you have time to make these changes in the next few hours? The deadline for what makes it in is approaching quickly, and since this is TOC change, I'd like to make it in. |
|
I'm on a train with spotty wifi, but yes, I'll rebase this branch shortly to take your comments into account. I think I also want to rework the first paragraph, since "sum type" is not particularly explanatory, so I may pull the discussion of tags up there. |
We generally are interested in using actual CS terms in the docs, but linking to the glossary to explain them. no worries, i'm gonna go get dinner, so take your time ❤️ |
|
@steveklabnik, just wanted to make sure you saw the new |
|
Ah! It doesn't. Let me check it out |
|
@bors: r+ rollup |
|
📌 Commit f59f41e has been approved by |
|
manually merged into #25352 |
The enums chapter at the moment is ... weird. The examples aren't about enums, they're about structs, and most of the chapter talks about how enums don't support comparison operators by default (which is also true of other compound data types.) I think there was a story here once, but some coherency got lost in refactoring. There are two preliminary patches here, one to combine the struct and tuple-struct chapters, and one to document unit-like structs, because enum syntax is easier to explain once you have those three. The final patch moves the enum chapter after the struct chapter, and rewrites most of it to talk about enums usefully (including covering matches on enums). r? @steveklabnik
The enums chapter at the moment is ... weird. The examples aren't about enums, they're about structs, and most of the chapter talks about how enums don't support comparison operators by default (which is also true of other compound data types.) I think there was a story here once, but some coherency got lost in refactoring.
There are two preliminary patches here, one to combine the struct and tuple-struct chapters, and one to document unit-like structs, because enum syntax is easier to explain once you have those three. The final patch moves the enum chapter after the struct chapter, and rewrites most of it to talk about enums usefully (including covering matches on enums).
r? @steveklabnik