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.

Sign up for GitHub

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

Jump to bottom

Documentation for functions in enums are linked but not generated #3584

Closed
mkorbel1 opened this issue Nov 17, 2023 · 1 comment · Fixed by #3697
Closed

Documentation for functions in enums are linked but not generated #3584

mkorbel1 opened this issue Nov 17, 2023 · 1 comment · Fixed by #3697
Assignees
@srawlins
Labels
P1 A high priority bug; for example, a single project is unusable or has many test failures type-bug Incorrect behavior (everything from a crash to more subtle misbehavior)

Comments

@mkorbel1
Copy link

If you define an enum with a function in it, then the documentation page for that enum will have a link to a documentation page about that function (and even the doc comment for the function), however the page for the function will be missing.

In addition, since the target of the link is missing, --validate-links will trigger a warning. This was annoying to debug because of #3331. I had to run this repo in debug mode and add print statements to figure out what was missing since I didn't know what the warning was.

To reproduce, create an enum with a static function in it, for example:

enum MyEnum {
  a,
  b,
  c;

  /// Says hello!
  static void myFunction() {
    print("hello");
  }
}

The generated documentation will include MyEnum and a link to myFunction, as expected, however the link (circled) will be dead because the doc page for myFunction is not generated.

image
@mkorbel1 mkorbel1 mentioned this issue Nov 17, 2023
Merged
@mkorbel1 mkorbel1 mentioned this issue Nov 28, 2023
Merged
@srawlins srawlins added type-bug Incorrect behavior (everything from a crash to more subtle misbehavior) P1 A high priority bug; for example, a single project is unusable or has many test failures labels Feb 28, 2024
@srawlins
Copy link
Member

Sorry for the extreme delay (dartdoc has fallen through the gaps in our triage process). I think there is a sizeable blind spot here with enhanced enums. I noticed that dartdoc's Enum doesn't inherit from Class, but it really probably should.

@srawlins srawlins self-assigned this Feb 29, 2024
srawlins added a commit to srawlins/dartdoc that referenced this issue Mar 1, 2024
@srawlins
Generate docs for enum static methods.
fbb724c 
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
```
@srawlins srawlins mentioned this issue Mar 1, 2024
Merged
1 task
srawlins added a commit to srawlins/dartdoc that referenced this issue Mar 1, 2024
@srawlins
Generate docs for enum static methods.
c5a0b36 
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
```
srawlins added a commit to srawlins/dartdoc that referenced this issue Mar 6, 2024
@srawlins
Generate docs for enum static methods.
eb4394a 
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
```
srawlins added a commit that referenced this issue Mar 7, 2024
@srawlins
Generate docs for enum static methods. (#3697)
0de8aff 
* Generate docs for enum static methods.

Fixes #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 (#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
```

* Back out inheritance change
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees

@srawlins srawlins

Labels
P1 A high priority bug; for example, a single project is unusable or has many test failures type-bug Incorrect behavior (everything from a crash to more subtle misbehavior)
Projects
None yet
Milestone
No milestone
Development

Successfully merging a pull request may close this issue.

Generate docs for enum static methods. srawlins/dartdoc
2 participants
@srawlins @mkorbel1