Skip to content

Clean up GeneratorBackend. #3673

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

Merged
merged 2 commits into from
Feb 23, 2024
Merged

Clean up GeneratorBackend. #3673

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
4b690ac
Merge GeneratorBackend and GeneratorBackendBase.
kallentu Feb 22, 2024
62824fb
Remove the unnecessary helpers.
kallentu Feb 22, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
126 changes: 21 additions & 105 deletions lib/src/generator/generator_backend.dart
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -56,90 +56,16 @@ class DartdocGeneratorBackendOptions implements TemplateOptions {
packageOrder = context.packageOrder;
}

/// An interface for classes which are responsible for outputing the generated
/// documentation.
abstract interface class GeneratorBackend {
FileWriter get writer;

/// Emits JSON describing the [categories] defined by the package.
void generateCategoryJson(List<Categorization> categories);

/// Emits a JSON catalog of [indexedElements] for use with a search index.
void generateSearchIndex(List<Indexable> indexedElements);

/// Emits documentation content for the [package].
void generatePackage(PackageGraph packageGraph, Package package);

/// Emits documentation content for the [category].
void generateCategory(PackageGraph packageGraph, Category category);

/// Emits documentation content for the [library].
void generateLibrary(PackageGraph packageGraph, Library library);

/// Emits documentation content for the [clazz].
void generateClass(PackageGraph packageGraph, Library library, Class clazz);

/// Emits documentation content for the [eNum].
void generateEnum(PackageGraph packageGraph, Library library, Enum eNum);

/// Emits documentation content for the [extension].
void generateExtension(
PackageGraph packageGraph, Library library, Extension extension);

/// Emits documentation content for the [extensionType].
void generateExtensionType(
PackageGraph packageGraph, Library library, ExtensionType extensionType);

/// Emits documentation content for the [mixin].
void generateMixin(PackageGraph packageGraph, Library library, Mixin mixin);

/// Emits documentation content for the [constructor].
void generateConstructor(PackageGraph packageGraph, Library library,
Constructable constructable, Constructor constructor);

/// Emits documentation content for the [field].
void generateConstant(
PackageGraph packageGraph, Library library, Container clazz, Field field);

/// Emits documentation content for the [field].
void generateProperty(
PackageGraph packageGraph, Library library, Container clazz, Field field);

/// Emits documentation content for the [method].
void generateMethod(PackageGraph packageGraph, Library library,
Container clazz, Method method);

/// Emits documentation content for the [function].
void generateFunction(
PackageGraph packageGraph, Library library, ModelFunction function);

/// Emits documentation content for the [constant].
void generateTopLevelConstant(
PackageGraph packageGraph, Library library, TopLevelVariable constant);

/// Emits documentation content for the [property].
void generateTopLevelProperty(
PackageGraph packageGraph, Library library, TopLevelVariable property);

/// Emits documentation content for the [typedef].
void generateTypeDef(
PackageGraph packageGraph, Library library, Typedef typedef);

/// Emits files not specific to a Dart language element (like a favicon, etc).
Future<void> generateAdditionalFiles();
}

/// Base [GeneratorBackend] for Dartdoc's supported formats.
abstract class GeneratorBackendBase implements GeneratorBackend {
/// Outputs generated documentation.
abstract class GeneratorBackend {
final DartdocGeneratorBackendOptions options;
final Templates templates;

@override
final FileWriter writer;
final ResourceProvider resourceProvider;
final p.Context _pathContext;

GeneratorBackendBase(
GeneratorBackend(
this.options, this.templates, this.writer, this.resourceProvider)
: _pathContext = resourceProvider.pathContext;

Expand All @@ -164,7 +90,7 @@ abstract class GeneratorBackendBase implements GeneratorBackend {
element: element is Warnable ? element : null);
}

@override
/// Emits JSON describing the [categories] defined by the package.
void generateCategoryJson(List<Categorization> categories) {
var json = '[]';
if (categories.isNotEmpty) {
Expand All @@ -178,7 +104,7 @@ abstract class GeneratorBackendBase implements GeneratorBackend {
writer.write(_pathContext.join('categories.json'), '$json\n');
}

@override
/// Emits a JSON catalog of [indexedElements] for use with a search index.
void generateSearchIndex(List<Indexable> indexedElements) {
var json = generator_util.generateSearchIndexJson(
indexedElements,
Expand All @@ -191,28 +117,23 @@ abstract class GeneratorBackendBase implements GeneratorBackend {
writer.write(_pathContext.join('index.json'), '$json\n');
}

@override
/// Emits documentation content for the [category].
void generateCategory(PackageGraph packageGraph, Category category) {
var data = CategoryTemplateData(options, packageGraph, category);
var content = templates.renderCategory(data);
write(writer, category.filePath, data, content);
runtimeStats.incrementAccumulator('writtenCategoryFileCount');
}

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

@override
void generateConstant(PackageGraph packageGraph, Library library,
Container clazz, Field field) =>
generateProperty(packageGraph, library, clazz, field);

@override
/// Emits documentation content for the [constructor].
void generateConstructor(PackageGraph packageGraph, Library library,
Constructable constructable, Constructor constructor) {
var data = ConstructorTemplateData(
Expand All @@ -222,15 +143,15 @@ abstract class GeneratorBackendBase implements GeneratorBackend {
runtimeStats.incrementAccumulator('writtenConstructorFileCount');
}

@override
/// 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);
runtimeStats.incrementAccumulator('writtenEnumFileCount');
}

@override
/// Emits documentation content for the [extension].
void generateExtension(
PackageGraph packageGraph, Library library, Extension extension) {
var data = ExtensionTemplateData(options, packageGraph, library, extension);
Expand All @@ -239,7 +160,7 @@ abstract class GeneratorBackendBase implements GeneratorBackend {
runtimeStats.incrementAccumulator('writtenExtensionFileCount');
}

@override
/// Emits documentation content for the [extensionType].
void generateExtensionType(
PackageGraph packageGraph, Library library, ExtensionType extensionType) {
var data = ExtensionTypeTemplateData(
Expand All @@ -249,7 +170,7 @@ abstract class GeneratorBackendBase implements GeneratorBackend {
runtimeStats.incrementAccumulator('writtenExtensionTypeFileCount');
}

@override
/// Emits documentation content for the [function].
void generateFunction(
PackageGraph packageGraph, Library library, ModelFunction function) {
var data = FunctionTemplateData(options, packageGraph, library, function);
Expand All @@ -258,15 +179,15 @@ abstract class GeneratorBackendBase implements GeneratorBackend {
runtimeStats.incrementAccumulator('writtenFunctionFileCount');
}

@override
/// Emits documentation content for the [library].
void generateLibrary(PackageGraph packageGraph, Library library) {
var data = LibraryTemplateData(options, packageGraph, library);
var content = templates.renderLibrary(data);
write(writer, library.filePath, data, content);
runtimeStats.incrementAccumulator('writtenLibraryFileCount');
}

@override
/// Emits documentation content for the [method].
void generateMethod(PackageGraph packageGraph, Library library,
Container clazz, Method method) {
var data =
Expand All @@ -276,23 +197,23 @@ abstract class GeneratorBackendBase implements GeneratorBackend {
runtimeStats.incrementAccumulator('writtenMethodFileCount');
}

@override
/// Emits documentation content for the [mixin].
void generateMixin(PackageGraph packageGraph, Library library, Mixin mixin) {
var data = MixinTemplateData(options, packageGraph, library, mixin);
var content = templates.renderMixin(data);
write(writer, mixin.filePath, data, content);
runtimeStats.incrementAccumulator('writtenMixinFileCount');
}

@override
/// Emits documentation content for the [package].
void generatePackage(PackageGraph packageGraph, Package package) {
var data = PackageTemplateData(options, packageGraph, package);
var content = templates.renderIndex(data);
write(writer, package.filePath, data, content);
runtimeStats.incrementAccumulator('writtenPackageFileCount');
}

@override
/// Emits documentation content for the [field].
void generateProperty(PackageGraph packageGraph, Library library,
Container clazz, Field field) {
var data =
Expand All @@ -302,12 +223,7 @@ abstract class GeneratorBackendBase implements GeneratorBackend {
runtimeStats.incrementAccumulator('writtenPropertyFileCount');
}

@override
void generateTopLevelConstant(PackageGraph packageGraph, Library library,
TopLevelVariable constant) =>
generateTopLevelProperty(packageGraph, library, constant);

@override
/// Emits documentation content for the [property].
void generateTopLevelProperty(
PackageGraph packageGraph, Library library, TopLevelVariable property) {
var data =
Expand All @@ -317,7 +233,7 @@ abstract class GeneratorBackendBase implements GeneratorBackend {
runtimeStats.incrementAccumulator('writtenTopLevelPropertyFileCount');
}

@override
/// Emits documentation content for the [typedef].
void generateTypeDef(
PackageGraph packageGraph, Library library, Typedef typedef) {
var data = TypedefTemplateData(options, packageGraph, library, typedef);
Expand All @@ -326,6 +242,6 @@ abstract class GeneratorBackendBase implements GeneratorBackend {
runtimeStats.incrementAccumulator('writtenTypedefFileCount');
}

@override
Future<void> generateAdditionalFiles() async {}
/// Emits files not specific to a Dart language element (like a favicon, etc).
Future<void> generateAdditionalFiles();
}
18 changes: 9 additions & 9 deletions lib/src/generator/generator_frontend.dart
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -99,7 +99,7 @@ class GeneratorFrontEnd implements Generator {
if (!constant.isCanonical) continue;

indexAccumulator.add(constant);
_generatorBackend.generateConstant(
_generatorBackend.generateProperty(
packageGraph, lib, clazz, constant);
}

Expand Down Expand Up @@ -149,7 +149,7 @@ class GeneratorFrontEnd implements Generator {

for (var constant in filterNonDocumented(extension.constantFields)) {
indexAccumulator.add(constant);
_generatorBackend.generateConstant(
_generatorBackend.generateProperty(
packageGraph, lib, extension, constant);
}

Expand Down Expand Up @@ -206,7 +206,7 @@ class GeneratorFrontEnd implements Generator {
for (var constant
in filterNonDocumented(extensionType.constantFields)) {
indexAccumulator.add(constant);
_generatorBackend.generateConstant(
_generatorBackend.generateProperty(
packageGraph, lib, extensionType, constant);
}

Expand Down Expand Up @@ -254,7 +254,7 @@ class GeneratorFrontEnd implements Generator {
for (var constant in filterNonDocumented(mixin.constantFields)) {
if (!constant.isCanonical) continue;
indexAccumulator.add(constant);
_generatorBackend.generateConstant(
_generatorBackend.generateProperty(
packageGraph, lib, mixin, constant);
}

Expand All @@ -263,15 +263,15 @@ class GeneratorFrontEnd implements Generator {
if (!property.isCanonical) continue;

indexAccumulator.add(property);
_generatorBackend.generateConstant(
_generatorBackend.generateProperty(
packageGraph, lib, mixin, property);
}

for (var property in filterNonDocumented(mixin.instanceFields)) {
if (!property.isCanonical) continue;

indexAccumulator.add(property);
_generatorBackend.generateConstant(
_generatorBackend.generateProperty(
packageGraph, lib, mixin, property);
}

Expand Down Expand Up @@ -311,7 +311,7 @@ class GeneratorFrontEnd implements Generator {
if (!constant.isCanonical) continue;

indexAccumulator.add(constant);
_generatorBackend.generateConstant(
_generatorBackend.generateProperty(
packageGraph, lib, enum_, constant);
}

Expand All @@ -325,7 +325,7 @@ class GeneratorFrontEnd implements Generator {

for (var property in filterNonDocumented(enum_.instanceFields)) {
indexAccumulator.add(property);
_generatorBackend.generateConstant(
_generatorBackend.generateProperty(
packageGraph, lib, enum_, property);
}
for (var operator in filterNonDocumented(enum_.instanceOperators)) {
Expand All @@ -341,7 +341,7 @@ class GeneratorFrontEnd implements Generator {

for (var constant in filterNonDocumented(lib.constants)) {
indexAccumulator.add(constant);
_generatorBackend.generateTopLevelConstant(
_generatorBackend.generateTopLevelProperty(
packageGraph, lib, constant);
}

Expand Down
2 changes: 1 addition & 1 deletion lib/src/generator/html_generator.dart
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,7 @@ Future<Generator> initHtmlGenerator(
}

/// Generator backend for HTML output.
class HtmlGeneratorBackend extends GeneratorBackendBase {
class HtmlGeneratorBackend extends GeneratorBackend {
HtmlGeneratorBackend(
super.options, super.templates, super.writer, super.resourceProvider);

Expand Down
2 changes: 1 addition & 1 deletion lib/src/generator/template_data.dart
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -70,7 +70,7 @@ abstract class TemplateDataBase {
/// When not using the HTML 'base' tag (default behavior), this represents the
/// path from this page back to the HTML base.
///
/// See [GeneratorBackendBase.write] for how this text is used in generating
/// See [GeneratorBackend.write] for how this text is used in generating
/// link URLs.
String get htmlBase;

Expand Down