Skip to content
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

Merged
merged 3 commits into from
Mar 7, 2024
Merged

Conversation

srawlins
Copy link
Member

@srawlins srawlins commented Mar 1, 2024

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:

Also in this change:

  • Change Enum to extend Class; while the analyzer's EnumElement does not extend 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.
  • Migrate methods_test.dart to use test_reflective_loader.
  • Add method tests for methods on classes, enums, mixins, extensions, and extension types.
  • Change some clazz and eNum parameter names to class_ and enum_. More standard, and standard inside the analyzer.
  • 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:
/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

  • I’ve reviewed the contributor guide and applied the relevant portions to this PR.
Contribution guidelines:

Note that many Dart repos have a weekly cadence for reviewing PRs - please allow for some latency before initial review feedback.

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
```
lib/src/model/enum.dart Outdated Show resolved Hide resolved
/// 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.
Copy link
Member

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.

Copy link
Member Author

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

Copy link
Member Author

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.

@srawlins srawlins merged commit 0de8aff into dart-lang:main Mar 7, 2024
9 checks passed
@srawlins srawlins deleted the enum-static branch March 7, 2024 03:10
copybara-service bot pushed a commit to dart-lang/sdk that referenced this pull request Mar 7, 2024
…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 <devoncarew@google.com>
Reviewed-by: Konstantin Shcheglov <scheglov@google.com>
Commit-Queue: Konstantin Shcheglov <scheglov@google.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Documentation for functions in enums are linked but not generated
2 participants