From 4b690acf9c16d248d9d57146790ea6a488b77901 Mon Sep 17 00:00:00 2001 From: Kallen Tu Date: Thu, 22 Feb 2024 21:35:43 +0000 Subject: [PATCH 1/2] Merge GeneratorBackend and GeneratorBackendBase. --- lib/src/generator/generator_backend.dart | 120 +++++------------------ lib/src/generator/html_generator.dart | 2 +- lib/src/generator/template_data.dart | 2 +- 3 files changed, 25 insertions(+), 99 deletions(-) diff --git a/lib/src/generator/generator_backend.dart b/lib/src/generator/generator_backend.dart index 522fb399d1..2f58e767c1 100644 --- a/lib/src/generator/generator_backend.dart +++ b/lib/src/generator/generator_backend.dart @@ -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 categories); - - /// Emits a JSON catalog of [indexedElements] for use with a search index. - void generateSearchIndex(List 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 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; @@ -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 categories) { var json = '[]'; if (categories.isNotEmpty) { @@ -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 indexedElements) { var json = generator_util.generateSearchIndexJson( indexedElements, @@ -191,7 +117,7 @@ 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); @@ -199,7 +125,7 @@ abstract class GeneratorBackendBase implements GeneratorBackend { 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); @@ -207,12 +133,12 @@ abstract class GeneratorBackendBase implements GeneratorBackend { runtimeStats.incrementAccumulator('writtenClassFileCount'); } - @override + /// Emits documentation content for the [field]. 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( @@ -222,7 +148,7 @@ 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); @@ -230,7 +156,7 @@ abstract class GeneratorBackendBase implements GeneratorBackend { 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); @@ -239,7 +165,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( @@ -249,7 +175,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); @@ -258,7 +184,7 @@ 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); @@ -266,7 +192,7 @@ abstract class GeneratorBackendBase implements GeneratorBackend { runtimeStats.incrementAccumulator('writtenLibraryFileCount'); } - @override + /// Emits documentation content for the [method]. void generateMethod(PackageGraph packageGraph, Library library, Container clazz, Method method) { var data = @@ -276,7 +202,7 @@ 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); @@ -284,7 +210,7 @@ abstract class GeneratorBackendBase implements GeneratorBackend { 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); @@ -292,7 +218,7 @@ abstract class GeneratorBackendBase implements GeneratorBackend { runtimeStats.incrementAccumulator('writtenPackageFileCount'); } - @override + /// Emits documentation content for the [field]. void generateProperty(PackageGraph packageGraph, Library library, Container clazz, Field field) { var data = @@ -302,12 +228,12 @@ abstract class GeneratorBackendBase implements GeneratorBackend { runtimeStats.incrementAccumulator('writtenPropertyFileCount'); } - @override + /// Emits documentation content for the [constant]. 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 = @@ -317,7 +243,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); @@ -326,6 +252,6 @@ abstract class GeneratorBackendBase implements GeneratorBackend { runtimeStats.incrementAccumulator('writtenTypedefFileCount'); } - @override - Future generateAdditionalFiles() async {} + /// Emits files not specific to a Dart language element (like a favicon, etc). + Future generateAdditionalFiles(); } diff --git a/lib/src/generator/html_generator.dart b/lib/src/generator/html_generator.dart index 8e20f60ee9..a8a2869e85 100644 --- a/lib/src/generator/html_generator.dart +++ b/lib/src/generator/html_generator.dart @@ -31,7 +31,7 @@ Future initHtmlGenerator( } /// Generator backend for HTML output. -class HtmlGeneratorBackend extends GeneratorBackendBase { +class HtmlGeneratorBackend extends GeneratorBackend { HtmlGeneratorBackend( super.options, super.templates, super.writer, super.resourceProvider); diff --git a/lib/src/generator/template_data.dart b/lib/src/generator/template_data.dart index 31f9fbedbc..3c953cda57 100644 --- a/lib/src/generator/template_data.dart +++ b/lib/src/generator/template_data.dart @@ -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; From 62824fb8c95c2346c074a6f0916be2ba43ee63f7 Mon Sep 17 00:00:00 2001 From: Kallen Tu Date: Thu, 22 Feb 2024 21:39:41 +0000 Subject: [PATCH 2/2] Remove the unnecessary helpers. --- lib/src/generator/generator_backend.dart | 10 ---------- lib/src/generator/generator_frontend.dart | 18 +++++++++--------- 2 files changed, 9 insertions(+), 19 deletions(-) diff --git a/lib/src/generator/generator_backend.dart b/lib/src/generator/generator_backend.dart index 2f58e767c1..4f6a976e93 100644 --- a/lib/src/generator/generator_backend.dart +++ b/lib/src/generator/generator_backend.dart @@ -133,11 +133,6 @@ abstract class GeneratorBackend { runtimeStats.incrementAccumulator('writtenClassFileCount'); } - /// Emits documentation content for the [field]. - void generateConstant(PackageGraph packageGraph, Library library, - Container clazz, Field field) => - generateProperty(packageGraph, library, clazz, field); - /// Emits documentation content for the [constructor]. void generateConstructor(PackageGraph packageGraph, Library library, Constructable constructable, Constructor constructor) { @@ -228,11 +223,6 @@ abstract class GeneratorBackend { runtimeStats.incrementAccumulator('writtenPropertyFileCount'); } - /// Emits documentation content for the [constant]. - void generateTopLevelConstant(PackageGraph packageGraph, Library library, - TopLevelVariable constant) => - generateTopLevelProperty(packageGraph, library, constant); - /// Emits documentation content for the [property]. void generateTopLevelProperty( PackageGraph packageGraph, Library library, TopLevelVariable property) { diff --git a/lib/src/generator/generator_frontend.dart b/lib/src/generator/generator_frontend.dart index 4dc7d0943d..1f744beeb6 100644 --- a/lib/src/generator/generator_frontend.dart +++ b/lib/src/generator/generator_frontend.dart @@ -99,7 +99,7 @@ class GeneratorFrontEnd implements Generator { if (!constant.isCanonical) continue; indexAccumulator.add(constant); - _generatorBackend.generateConstant( + _generatorBackend.generateProperty( packageGraph, lib, clazz, constant); } @@ -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); } @@ -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); } @@ -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); } @@ -263,7 +263,7 @@ class GeneratorFrontEnd implements Generator { if (!property.isCanonical) continue; indexAccumulator.add(property); - _generatorBackend.generateConstant( + _generatorBackend.generateProperty( packageGraph, lib, mixin, property); } @@ -271,7 +271,7 @@ class GeneratorFrontEnd implements Generator { if (!property.isCanonical) continue; indexAccumulator.add(property); - _generatorBackend.generateConstant( + _generatorBackend.generateProperty( packageGraph, lib, mixin, property); } @@ -311,7 +311,7 @@ class GeneratorFrontEnd implements Generator { if (!constant.isCanonical) continue; indexAccumulator.add(constant); - _generatorBackend.generateConstant( + _generatorBackend.generateProperty( packageGraph, lib, enum_, constant); } @@ -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)) { @@ -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); }