Skip to content

Commit

Permalink
Generate docs for enum static methods.
Browse files Browse the repository at this point in the history
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
```
  • Loading branch information
srawlins committed Mar 1, 2024
1 parent 2760d25 commit c5a0b36
Show file tree
Hide file tree
Showing 14 changed files with 448 additions and 571 deletions.
5 changes: 4 additions & 1 deletion lib/src/generator/file_structure.dart
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,8 @@ abstract class FileStructure {
// This should be the common case.
FileStructure._fromModelElement(documentable),
_ => throw UnimplementedError(
'Tried to build a FileStructure for an unknown subtype of Documentable: ${documentable.runtimeType}')
'Tried to build a FileStructure for an unknown subtype of '
"Documentable: '${documentable.runtimeType}'")
};
}

Expand All @@ -42,6 +43,8 @@ abstract class FileStructure {
return switch (modelElement) {
Library() => FileStructureImpl(modelElement.dirName, 'library'),
Mixin() => FileStructureImpl(modelElement.name, 'mixin'),
// Probably just an archaic state, but enums do not have a file suffix.
Enum() => FileStructureImpl(modelElement.name, null),
Class() => FileStructureImpl(modelElement.name, 'class'),
ExtensionType() => FileStructureImpl(modelElement.name, 'extension-type'),
Operator() => FileStructureImpl(
Expand Down
24 changes: 12 additions & 12 deletions lib/src/generator/generator_backend.dart
Original file line number Diff line number Diff line change
Expand Up @@ -125,11 +125,11 @@ abstract class GeneratorBackend {
runtimeStats.incrementAccumulator('writtenCategoryFileCount');
}

/// Emits documentation content for the [clazz].
void generateClass(PackageGraph packageGraph, Library library, Class clazz) {
var data = ClassTemplateData(options, packageGraph, library, clazz);
/// Emits documentation content for the [class_].
void generateClass(PackageGraph packageGraph, Library library, Class class_) {
var data = ClassTemplateData(options, packageGraph, library, class_);
var content = templates.renderClass(data);
write(writer, clazz.filePath, data, content);
write(writer, class_.filePath, data, content);
runtimeStats.incrementAccumulator('writtenClassFileCount');
}

Expand All @@ -143,11 +143,11 @@ abstract class GeneratorBackend {
runtimeStats.incrementAccumulator('writtenConstructorFileCount');
}

/// Emits documentation content for the [eNum].
void generateEnum(PackageGraph packageGraph, Library library, Enum eNum) {
var data = EnumTemplateData(options, packageGraph, library, eNum);
/// Emits documentation content for the [enum_].
void generateEnum(PackageGraph packageGraph, Library library, Enum enum_) {
var data = EnumTemplateData(options, packageGraph, library, enum_);
var content = templates.renderEnum(data);
write(writer, eNum.filePath, data, content);
write(writer, enum_.filePath, data, content);
runtimeStats.incrementAccumulator('writtenEnumFileCount');
}

Expand Down Expand Up @@ -189,9 +189,9 @@ abstract class GeneratorBackend {

/// Emits documentation content for the [method].
void generateMethod(PackageGraph packageGraph, Library library,
Container clazz, Method method) {
Container container, Method method) {
var data =
MethodTemplateData(options, packageGraph, library, clazz, method);
MethodTemplateData(options, packageGraph, library, container, method);
var content = templates.renderMethod(data);
write(writer, method.filePath, data, content);
runtimeStats.incrementAccumulator('writtenMethodFileCount');
Expand All @@ -215,9 +215,9 @@ abstract class GeneratorBackend {

/// Emits documentation content for the [field].
void generateProperty(PackageGraph packageGraph, Library library,
Container clazz, Field field) {
Container container, Field field) {
var data =
PropertyTemplateData(options, packageGraph, library, clazz, field);
PropertyTemplateData(options, packageGraph, library, container, field);
var content = templates.renderProperty(data);
write(writer, field.filePath, data, content);
runtimeStats.incrementAccumulator('writtenPropertyFileCount');
Expand Down
Loading

0 comments on commit c5a0b36

Please sign in to comment.