From a7322c2f47f4804366e80f7f96098a2357a1776a Mon Sep 17 00:00:00 2001 From: Janice Collins Date: Tue, 17 Aug 2021 09:57:18 -0700 Subject: [PATCH 1/3] Switch to using CompilationUnitElement.classes (#2743) --- lib/src/model/library.dart | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lib/src/model/library.dart b/lib/src/model/library.dart index 0d473879b0..b79109b623 100644 --- a/lib/src/model/library.dart +++ b/lib/src/model/library.dart @@ -102,13 +102,13 @@ class Library extends ModelElement with Categorization, TopLevelContainer { CompilationUnitElement compilationUnit) { return quiver.concat([ compilationUnit.accessors, + compilationUnit.classes, compilationUnit.enums, compilationUnit.extensions, compilationUnit.functions, compilationUnit.mixins, compilationUnit.topLevelVariables, compilationUnit.typeAliases, - compilationUnit.types, ]); } From 1d9181151a27731c836de239cf898e19a2edba40 Mon Sep 17 00:00:00 2001 From: Janice Collins Date: Tue, 17 Aug 2021 15:21:44 -0700 Subject: [PATCH 2/3] Prepare dartdoc_options for migration (#2745) * more specific imports in options * do not allow autoinitialization * dartfmt * parameterize the valueWithContext type * Use alternative constructors instead of externalizing, didn't realize the autodetect was so widely used * more subclasses --- lib/options.dart | 16 +++- lib/src/dartdoc_options.dart | 110 +++++++++++----------- test/end2end/dartdoc_test.dart | 4 +- test/mustachio/renderers_output_test.dart | 4 +- test/src/utils.dart | 7 +- 5 files changed, 75 insertions(+), 66 deletions(-) diff --git a/lib/options.dart b/lib/options.dart index 537c83084f..9af65023ab 100644 --- a/lib/options.dart +++ b/lib/options.dart @@ -2,8 +2,11 @@ import 'dart:io' show stderr, exitCode; import 'package:analyzer/file_system/file_system.dart'; import 'package:args/args.dart'; -import 'package:dartdoc/dartdoc.dart'; +import 'package:dartdoc/dartdoc.dart' show dartdocVersion, programName; +import 'package:dartdoc/src/dartdoc_options.dart'; +import 'package:dartdoc/src/generator/generator.dart'; import 'package:dartdoc/src/logging.dart'; +import 'package:dartdoc/src/package_meta.dart'; /// Helper class that consolidates option contexts for instantiating generators. class DartdocGeneratorOptionContext extends DartdocOptionContext { @@ -11,6 +14,10 @@ class DartdocGeneratorOptionContext extends DartdocOptionContext { DartdocOptionSet optionSet, Folder dir, ResourceProvider resourceProvider) : super(optionSet, dir, resourceProvider); + DartdocGeneratorOptionContext.fromDefaultContextLocation( + DartdocOptionSet optionSet, ResourceProvider resourceProvider) + : super.fromDefaultContextLocation(optionSet, resourceProvider); + // TODO(migration): Make late final with initializer when Null Safe. String _header; @@ -57,6 +64,9 @@ class DartdocProgramOptionContext extends DartdocGeneratorOptionContext DartdocProgramOptionContext( DartdocOptionSet optionSet, Folder dir, ResourceProvider resourceProvider) : super(optionSet, dir, resourceProvider); + DartdocProgramOptionContext.fromDefaultContextLocation( + DartdocOptionSet optionSet, ResourceProvider resourceProvider) + : super.fromDefaultContextLocation(optionSet, resourceProvider); bool get generateDocs => optionSet['generateDocs'].valueAt(context); bool get help => optionSet['help'].valueAt(context); @@ -118,8 +128,8 @@ Future parseOptions( DartdocProgramOptionContext config; try { - config = DartdocProgramOptionContext( - optionSet, null, packageMetaProvider.resourceProvider); + config = DartdocProgramOptionContext.fromDefaultContextLocation( + optionSet, packageMetaProvider.resourceProvider); } on DartdocOptionError catch (e) { stderr.writeln(' fatal error: ${e.message}'); stderr.writeln(''); diff --git a/lib/src/dartdoc_options.dart b/lib/src/dartdoc_options.dart index b8eba96f65..844012e232 100644 --- a/lib/src/dartdoc_options.dart +++ b/lib/src/dartdoc_options.dart @@ -396,10 +396,10 @@ abstract class DartdocOption { bool get _isDouble => _kDoubleVal is T; - DartdocOption _parent; + DartdocOption _parent; /// The parent of this DartdocOption, or null if this is the root. - DartdocOption get parent => _parent; + DartdocOption get parent => _parent; final Map __yamlAtCanonicalPathCache = {}; @@ -424,18 +424,18 @@ abstract class DartdocOption { /// Throw [DartdocFileMissing] with a detailed error message indicating where /// the error came from when a file or directory option is missing. void _onMissing( - _OptionValueWithContext valueWithContext, String missingFilename); + _OptionValueWithContext valueWithContext, String missingFilename); /// Call [_onMissing] for every path that does not exist. - void _validatePaths(_OptionValueWithContext valueWithContext) { + void _validatePaths(_OptionValueWithContext valueWithContext) { if (!mustExist) return; assert(isDir || isFile); List resolvedPaths; var value = valueWithContext.value; if (value is String) { - resolvedPaths = [valueWithContext.resolvedValue]; + resolvedPaths = [valueWithContext.resolvedValue as String]; } else if (value is List) { - resolvedPaths = valueWithContext.resolvedValue as List; + resolvedPaths = valueWithContext.resolvedValue as List; } else if (value is Map) { resolvedPaths = (valueWithContext.resolvedValue as Map).values.toList(); } else { @@ -456,7 +456,7 @@ abstract class DartdocOption { /// For a [List] or [String] value, if [isDir] or [isFile] is set, /// resolve paths in value relative to canonicalPath. - T _handlePathsInContext(_OptionValueWithContext valueWithContext) { + T _handlePathsInContext(_OptionValueWithContext valueWithContext) { if (valueWithContext?.value == null || !(isDir || isFile || isGlob)) { return valueWithContext?.value; } @@ -472,15 +472,15 @@ abstract class DartdocOption { ArgResults get _argResults => root.__argResults; /// Set the parent of this [DartdocOption]. Do not call more than once. - set parent(DartdocOption newParent) { + set parent(DartdocOption newParent) { assert(_parent == null); _parent = newParent; } /// The root [DartdocOption] containing this object, or [this] if the object /// has no parent. - DartdocOption get root { - DartdocOption p = this; + DartdocOption get root { + DartdocOption p = this; while (p.parent != null) { p = p.parent; } @@ -490,7 +490,7 @@ abstract class DartdocOption { /// All object names starting at the root. Iterable get keys { var keyList = []; - DartdocOption option = this; + DartdocOption option = this; while (option?.name != null) { keyList.add(option.name); option = option.parent; @@ -499,7 +499,7 @@ abstract class DartdocOption { } /// Direct children of this node, mapped by name. - final Map> _children = {}; + final Map _children = {}; /// Return the calculated value of this option, given the directory as /// context. @@ -531,7 +531,7 @@ abstract class DartdocOption { resourceProvider.pathContext.basename(element.source.fullName)))); /// Adds a DartdocOption to the children of this DartdocOption. - void add(DartdocOption option) { + void add(DartdocOption option) { if (_children.containsKey(option.name)) { throw DartdocOptionError( 'Tried to add two children with the same name: ${option.name}'); @@ -545,7 +545,7 @@ abstract class DartdocOption { void _onAdd() {} /// Adds a list of dartdoc options to the children of this DartdocOption. - void addAll(Iterable> options) => options.forEach(add); + void addAll(Iterable options) => options.forEach(add); /// Get the immediate child of this node named [name]. DartdocOption operator [](String name) { @@ -553,7 +553,7 @@ abstract class DartdocOption { } /// Apply the function [visit] to [this] and all children. - void traverse(void Function(DartdocOption option) visit) { + void traverse(void Function(DartdocOption option) visit) { visit(this); _children.values.forEach((d) => d.traverse(visit)); } @@ -590,7 +590,7 @@ class DartdocOptionFileSynth extends DartdocOption @override void _onMissing( - _OptionValueWithContext valueWithContext, String missingPath) { + _OptionValueWithContext valueWithContext, String missingPath) { if (valueWithContext.definingFile != null) { _onMissingFromFiles(valueWithContext, missingPath); } else { @@ -632,7 +632,7 @@ class DartdocOptionArgSynth extends DartdocOption @override void _onMissing( - _OptionValueWithContext valueWithContext, String missingPath) { + _OptionValueWithContext valueWithContext, String missingPath) { _onMissingFromArgs(valueWithContext, missingPath); } @@ -687,12 +687,12 @@ abstract class DartdocSyntheticOption implements DartdocOption { } @override - void _onMissing(_OptionValueWithContext valueWithContext, - String missingPath) => + void _onMissing( + _OptionValueWithContext valueWithContext, String missingPath) => _onMissingFromSynthetic(valueWithContext, missingPath); void _onMissingFromSynthetic( - _OptionValueWithContext valueWithContext, String missingPath) { + _OptionValueWithContext valueWithContext, String missingPath) { var description = 'Synthetic configuration option $name from '; throw DartdocFileMissing( '$description, computed as ${valueWithContext.value}, resolves to ' @@ -700,7 +700,7 @@ abstract class DartdocSyntheticOption implements DartdocOption { } } -typedef OptionGenerator = Future>> Function( +typedef OptionGenerator = Future> Function( PackageMetaProvider); /// A [DartdocOption] that only contains other [DartdocOption]s and is not an @@ -734,13 +734,13 @@ class DartdocOptionSet extends DartdocOption { /// Since we have no value, [_onMissing] does nothing. @override - void _onMissing(_OptionValueWithContext valueWithContext, - String missingFilename) {} + void _onMissing( + _OptionValueWithContext valueWithContext, String missingFilename) {} /// Traverse skips this node, because it doesn't represent a real /// configuration object. @override - void traverse(void Function(DartdocOption option) visitor) { + void traverse(void Function(DartdocOption option) visitor) { _children.values.forEach((d) => d.traverse(visitor)); } } @@ -815,7 +815,7 @@ class DartdocOptionArgFile extends DartdocOption @override void _onMissing( - _OptionValueWithContext valueWithContext, String missingPath) { + _OptionValueWithContext valueWithContext, String missingPath) { if (valueWithContext.definingFile != null) { _onMissingFromFiles(valueWithContext, missingPath); } else { @@ -887,12 +887,12 @@ abstract class _DartdocFileOption implements DartdocOption { String get fieldName => keys.join('.'); @override - void _onMissing(_OptionValueWithContext valueWithContext, - String missingPath) => + void _onMissing( + _OptionValueWithContext valueWithContext, String missingPath) => _onMissingFromFiles(valueWithContext, missingPath); void _onMissingFromFiles( - _OptionValueWithContext valueWithContext, String missingPath) { + _OptionValueWithContext valueWithContext, String missingPath) { var dartdocYaml = resourceProvider.pathContext.join( valueWithContext.canonicalDirectoryPath, valueWithContext.definingFile); throw DartdocFileMissing('Field $fieldName from $dartdocYaml, set to ' @@ -914,7 +914,7 @@ abstract class _DartdocFileOption implements DartdocOption { T _valueAtFromFiles(Folder dir) { var key = resourceProvider.pathContext.canonicalize(dir.path); if (!__valueAtFromFiles.containsKey(key)) { - _OptionValueWithContext valueWithContext; + _OptionValueWithContext valueWithContext; if (parentDirOverridesChild) { valueWithContext = _valueAtFromFilesLastFound(dir); } else { @@ -927,8 +927,8 @@ abstract class _DartdocFileOption implements DartdocOption { /// Searches all dartdoc_options files through parent directories, starting at /// [dir], for the option and returns one once found. - _OptionValueWithContext _valueAtFromFilesFirstFound(Folder folder) { - _OptionValueWithContext value; + _OptionValueWithContext _valueAtFromFilesFirstFound(Folder folder) { + _OptionValueWithContext value; for (var dir in folder.withAncestors) { value = _valueAtFromFile(dir); if (value != null) break; @@ -939,8 +939,8 @@ abstract class _DartdocFileOption implements DartdocOption { /// Searches all dartdoc_options files for the option, and returns the value /// in the top-most parent directory `dartdoc_options.yaml` file it is /// mentioned in. - _OptionValueWithContext _valueAtFromFilesLastFound(Folder folder) { - _OptionValueWithContext value; + _OptionValueWithContext _valueAtFromFilesLastFound(Folder folder) { + _OptionValueWithContext value; for (var dir in folder.withAncestors) { var tmpValue = _valueAtFromFile(dir); if (tmpValue != null) value = tmpValue; @@ -950,7 +950,7 @@ abstract class _DartdocFileOption implements DartdocOption { /// Returns null if not set in the YAML file in this directory (or its /// parents). - _OptionValueWithContext _valueAtFromFile(Folder dir) { + _OptionValueWithContext _valueAtFromFile(Folder dir) { var yamlFileData = _yamlAtDirectory(dir); var contextPath = yamlFileData.canonicalDirectoryPath; Object yamlData = yamlFileData.data ?? {}; @@ -1081,12 +1081,12 @@ abstract class _DartdocArgOption implements DartdocOption { } @override - void _onMissing(_OptionValueWithContext valueWithContext, - String missingPath) => + void _onMissing( + _OptionValueWithContext valueWithContext, String missingPath) => _onMissingFromArgs(valueWithContext, missingPath); void _onMissingFromArgs( - _OptionValueWithContext valueWithContext, String missingPath) { + _OptionValueWithContext valueWithContext, String missingPath) { throw DartdocFileMissing( 'Argument --$argName, set to ${valueWithContext.value}, resolves to ' 'missing path: "$missingPath"'); @@ -1096,7 +1096,7 @@ abstract class _DartdocArgOption implements DartdocOption { /// the [argParser] and the working directory from [_directoryCurrent]. /// /// Throws [UnsupportedError] if [T] is not a supported type. - _OptionValueWithContext _valueAtFromArgsWithContext() { + _OptionValueWithContext _valueAtFromArgsWithContext() { if (!_argResults.wasParsed(argName)) return null; T retval; @@ -1215,21 +1215,23 @@ class DartdocOptionContext extends DartdocOptionContextBase // TODO(jcollins-g): Allow passing in structured data to initialize a // [DartdocOptionContext]'s arguments instead of having to parse strings // via optionSet. - /// If [entity] is null, assume this is the initialization case and use - /// the inputDir flag to determine the context. - DartdocOptionContext( - this.optionSet, Resource resource, ResourceProvider resourceProvider) { - if (resource == null) { - var current = resourceProvider.pathContext.current; - String inputDir = - optionSet['inputDir'].valueAt(resourceProvider.getFolder(current)) ?? - current; - context = resourceProvider.getFolder(inputDir); - } else { - context = resourceProvider.getFolder(resourceProvider.pathContext - .canonicalize( - resource is File ? resource.parent2.path : resource.path)); - } + DartdocOptionContext(this.optionSet, Resource contextLocation, + ResourceProvider resourceProvider) { + assert(contextLocation != null); + context = resourceProvider.getFolder(resourceProvider.pathContext + .canonicalize(contextLocation is File + ? contextLocation.parent2.path + : contextLocation.path)); + } + + /// Build a DartdocOptionContext via the 'inputDir' command line option. + DartdocOptionContext.fromDefaultContextLocation( + this.optionSet, ResourceProvider resourceProvider) { + var current = resourceProvider.pathContext.current; + String inputDir = + optionSet['inputDir'].valueAt(resourceProvider.getFolder(current)) ?? + current; + context = resourceProvider.getFolder(inputDir); } /// Build a DartdocOptionContext from an analyzer element (using its source @@ -1366,7 +1368,7 @@ class DartdocOptionContext extends DartdocOptionContextBase /// Instantiate dartdoc's configuration file and options parser with the /// given command line arguments. -Future>> createDartdocOptions( +Future> createDartdocOptions( PackageMetaProvider packageMetaProvider, ) async { var resourceProvider = packageMetaProvider.resourceProvider; diff --git a/test/end2end/dartdoc_test.dart b/test/end2end/dartdoc_test.dart index 91ccfc83f1..2e90715203 100644 --- a/test/end2end/dartdoc_test.dart +++ b/test/end2end/dartdoc_test.dart @@ -55,8 +55,8 @@ Future _generatorContextFromArgv( ], pubPackageMetaProvider); optionSet.parseArguments(argv); - return DartdocGeneratorOptionContext( - optionSet, null, pubPackageMetaProvider.resourceProvider); + return DartdocGeneratorOptionContext.fromDefaultContextLocation( + optionSet, pubPackageMetaProvider.resourceProvider); } class DartdocLoggingOptionContext extends DartdocGeneratorOptionContext diff --git a/test/mustachio/renderers_output_test.dart b/test/mustachio/renderers_output_test.dart index b1c3ec4446..89bbc0ebea 100644 --- a/test/mustachio/renderers_output_test.dart +++ b/test/mustachio/renderers_output_test.dart @@ -27,8 +27,8 @@ Future _generatorContextFromArgv( ], pubPackageMetaProvider); optionSet.parseArguments(argv); - return DartdocGeneratorOptionContext( - optionSet, null, pubPackageMetaProvider.resourceProvider); + return DartdocGeneratorOptionContext.fromDefaultContextLocation( + optionSet, pubPackageMetaProvider.resourceProvider); } void main() { diff --git a/test/src/utils.dart b/test/src/utils.dart index 779fc77839..be6bd69529 100644 --- a/test/src/utils.dart +++ b/test/src/utils.dart @@ -34,14 +34,11 @@ final Folder testPackageToolError = _resourceProvider.getFolder(_pathContext /// [DartdocOptionSet] based on the current working directory. Future contextFromArgv( List argv, PackageMetaProvider packageMetaProvider) async { - var resourceProvider = packageMetaProvider.resourceProvider; var optionSet = await DartdocOptionSet.fromOptionGenerators( 'dartdoc', [createDartdocOptions], packageMetaProvider); optionSet.parseArguments(argv); - return DartdocOptionContext( - optionSet, - resourceProvider.getFolder(resourceProvider.pathContext.current), - pubPackageMetaProvider.resourceProvider); + return DartdocOptionContext.fromDefaultContextLocation( + optionSet, pubPackageMetaProvider.resourceProvider); } Future bootBasicPackage( From 58730e9bb44bbc862af47bd1fbe7b52c6757f251 Mon Sep 17 00:00:00 2001 From: Janice Collins Date: Tue, 17 Aug 2021 15:42:58 -0700 Subject: [PATCH 3/3] Empty commit to straighten out GitHub Actions