-
Notifications
You must be signed in to change notification settings - Fork 118
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Generate docs for enum static methods. #3697
Conversation
Fixes dart-lang#3584 The GeneratorFrontEnd code was really long, and I think that made it easy to omit things. I've refactored it to reuse more code. Also, the repeated code had bugs: * For extensions and extension types, we likely _over_-documented, because we didn't omit things that we're canonical. * For enums, we omitted static methods and static fields (dart-lang#3584). Also in this change: * Change some `clazz` and `eNum` parameter names to `class_` and `enum_`. More standard, and standard inside the analyzer. * Migrate methods_test.dart to use test_reflective_loader. * Add method tests for methods on classes, enums, mixins, extensions, and extension types. * In the shared testing code, add some code that prints out the in-memory files when a file cannot be read. Here's a snippet of what that looks like: ```none /temp/method_test/doc/ ├─ index.html ├─ __404error.html ├─ search.html ├─ lib/ │ ├─ lib-library.html │ ├─ lib-library-sidebar.html │ ├─ E-class.html │ ├─ E-enum-sidebar.html │ └─ E/ │ │ ├─ values-constant.html ```
/// The total list of public enum values. | ||
/// | ||
/// This is defined on [Container] instead of just [Enum], because the | ||
/// `ContainerSidebar` Mustache template needs to refer to this field. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think this is just the side effect of using Mustache templates, but this doesn't feel great. I wouldn't choose to have publicEnumValues
on the superclass of enum.
But alas.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Oh yeah. A bummer. There are a few of these. More than being an issue with Mustache templates, it is an issue specifically with our implementation. I haven't looked at this stuff in years, and it might be ripe for fixing. :D
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I looked a bit and remembered. A bit of history 😁
When I initially wrote Mustachio, our mirrorless Mustache renderer, I envisioned it might be extracted into its own package some day. But I wanted to bake it in dartdoc first. That was a good decision because a few of the little designs are optimized for dartdoc. We have never opened it as a stand-alone Mustache renderer, and that's fine. One less headache 😬 .
It also kind of opens some doors. We can add some custom syntax on Mustache. There are two I've wanted:
- A boolean block based on static typing.
{{ #foo is Foo }}
. There are a handful of places where it would come in handy, and we wouldn't need as much shoe-horning like this. - An awaited Future value.
{{ await foo }}
maybe. In particular, one reason we have to pre-process all doc comments is so that they are waiting patiently on each ModelElement by the time Mustachio comes by to read them. Mustachio cannot currently ask an object for a value which is Future-typed.
…h, web, webdriver, webkit_inspection_protocol Revisions updated by `dart tools/rev_sdk_deps.dart`. dartdoc (https://github.com/dart-lang/dartdoc/compare/cec45fb..0de8aff): 0de8aff3 2024-03-06 Sam Rawlins Generate docs for enum static methods. (dart-lang/dartdoc#3697) 9eafdc64 2024-03-06 Sam Rawlins Rewrite Library.allOriginalModelElementNames. (dart-lang/dartdoc#3698) e8f36333 2024-03-06 Sam Rawlins Fix SDK GitHub action with some stub headers and footers (dart-lang/dartdoc#3704) 58c065d4 2024-03-05 Sam Rawlins Bump snippets activated to 0.4.3 (dart-lang/dartdoc#3702) http (https://github.com/dart-lang/http/compare/470d2c3..8d3c647): 8d3c647 2024-03-06 Brian Quinlan Add support for negotiating a subprotocol (dart-lang/http#1150) e71e739 2024-03-05 Brian Quinlan Add `WebSocket.connect` as a cross-platform connection method (dart-lang/http#1149) f14b5aa 2024-03-04 Brian Quinlan Include a description and version number in web_socket pubspec (dart-lang/http#1148) 5b656a9 2024-03-04 Brian Quinlan Add a LICENSE file to package:web_socket (dart-lang/http#1147) 557c420 2024-03-04 Brian Quinlan Implement WebSocket for the browser (dart-lang/http#1142) markdown (https://github.com/dart-lang/markdown/compare/dd47c5d..1ca5166): 1ca5166 2024-03-06 Devon Carew fix a crash when parsing alert block syntax (dart-lang/markdown#593) package_config (https://github.com/dart-lang/package_config/compare/4a7042b..3d90e69): 3d90e69 2024-03-05 Michael Thomsen Fix typo (dart-lang/package_config#149) shelf (https://github.com/dart-lang/shelf/compare/da6a69b..1acbc67): 1acbc67 2024-03-06 Andy Add shelf_router middleware examples (dart-lang/shelf#417) vector_math (https://github.com/google/vector_math.dart/compare/3706feb..7e705f7): 7e705f7 2024-03-06 6y Fix quaternion negate (google/vector_math.dart#316) 1ed8ac6 2024-03-06 6y Resolve Inconsistency in Matrix3 and Matrix4 `rotateY` Implementations (google/vector_math.dart#317) web (https://github.com/dart-lang/web/compare/8870d04..51e594b): 51e594b 2024-03-05 Srujan Gaddam Fix dictionary constructors to accept supertype members and create an empty object when there are no fields (dart-lang/web#197) 4af904f 2024-03-05 Srujan Gaddam Publish 0.5.1 (dart-lang/web#196) c72ec1a 2024-03-04 Devon Carew add instructions for re-generating the package (dart-lang/web#195) webdriver (https://github.com/google/webdriver.dart/compare/2c1b6f8..73a7ac8): 73a7ac8 2024-03-04 dependabot[bot] Bump nanasess/setup-chromedriver from 2.2.1 to 2.2.2 (google/webdriver.dart#294) webkit_inspection_protocol (https://github.com/google/webkit_inspection_protocol.dart/compare/07295b9..153fea4): 153fea4 2024-03-04 dependabot[bot] Bump nanasess/setup-chromedriver (google/webkit_inspection_protocol.dart#120) Change-Id: Ic213677a1e2430a6de56a94e0bfaa1f33e2fc7d4 Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/356300 Auto-Submit: Devon Carew <[email protected]> Reviewed-by: Konstantin Shcheglov <[email protected]> Commit-Queue: Konstantin Shcheglov <[email protected]>
Fixes #3584
The big function in GeneratorFrontEnd was really big, and I think that made it easy to omit things. I've refactored it to reuse more code. Also, the repeated code had bugs:
enum
s are linked but not generated #3584).Also in this change:
ClassElement
, behaviorally, it's too good to pass up. I think this also fixes a bug linkifying enum values, as seen in the enum tests.clazz
andeNum
parameter names toclass_
andenum_
. More standard, and standard inside the analyzer.Contribution guidelines:
dart format
.Note that many Dart repos have a weekly cadence for reviewing PRs - please allow for some latency before initial review feedback.