Add extra documentation to Enum to point to EnumName. #53164
Conversation
I keep forgetting you can use `.name` because the only sign that it exists in the `Enum` documentation is the in-passing mention that `Enum` has an extension, without mentioning why. This add an explicit callout to the `Enum` class definition.
|
Thank you for your contribution! This project uses Gerrit for code reviews. Your pull request has automatically been converted into a code review at: https://dart-review.googlesource.com/c/sdk/+/319463 Please wait for a developer to review your code review at the above link; you can speed up the review if you sign into Gerrit and manually add a reviewer that has recently worked on the relevant code. See CONTRIBUTING.md to learn how to upload changes to Gerrit directly. Additional commits pushed to this PR will update both the PR and the corresponding Gerrit CL. After the review is complete on the CL, your reviewer will merge the CL (automatically closing this PR). |
sdk/lib/core/enum.dart
Outdated
| @@ -10,6 +10,9 @@ part of dart.core; | |||
| /// introduced using an `enum` declaration. | |||
| /// Non-platform classes cannot extend or mix in this class. | |||
| /// Concrete classes cannot implement the interface. | |||
| /// | |||
| /// The string name of a value is available via the `name` property | |||
There was a problem hiding this comment.
I'd go with
/// The intentifier used to name an `enum` value is available as a `String`,
/// via the [`name`][EnumName.name] extension property on the `enum` value.(If that's thow you link to other members without their full name in DartDoc. Where is the DartDoc syntax specification?)
There was a problem hiding this comment.
The grammar is currently documented at https://github.com/dart-lang/dartdoc/wiki/dartdoc-comment-references, but I don't think the doc is super well maintained.
We have a few issues open to properly document it on dart.dev but we haven't had a chance yet.
There was a problem hiding this comment.
I'm not sure if that works, but I'm happy to change it to that if you would prefer. Let me know. :-)
|
@Hixie would you like to follow up on the comments or should we close the PR? |
|
I was awaiting clarification about whether to apply @lrhn's suggestion or not. Is that the preferred syntax? It wasn't clear to me if that was what was being suggested or not. |
|
I applied the change but without the part that's risky (which has the side-effect of being more explicit, which is probably good anyway). |
|
https://dart-review.googlesource.com/c/sdk/+/319463 has been updated with the latest commits from this pull request. |
1 similar comment
|
https://dart-review.googlesource.com/c/sdk/+/319463 has been updated with the latest commits from this pull request. |
|
@lrhn friendly ping |
typo fix
|
https://dart-review.googlesource.com/c/sdk/+/319463 has been updated with the latest commits from this pull request. |
1 similar comment
|
https://dart-review.googlesource.com/c/sdk/+/319463 has been updated with the latest commits from this pull request. |
Closes #53164 GitOrigin-RevId: 0c96101 Change-Id: I26391dddde87cdea0cc6ae4a70d04be1a48576f2 Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/319463 Reviewed-by: Johnni Winther <[email protected]> Reviewed-by: Lasse Nielsen <[email protected]> Reviewed-by: Nate Bosch <[email protected]> Commit-Queue: Lasse Nielsen <[email protected]>
I keep forgetting you can use
.namebecause the only sign that it exists in theEnumdocumentation is the in-passing mention thatEnumhas an extension, without mentioning why. This add an explicit callout to theEnumclass definition.