From affc5b44f192a7c278d6286617310e9eca135625 Mon Sep 17 00:00:00 2001 From: Sam Rawlins Date: Sun, 8 Oct 2023 16:40:27 -0700 Subject: [PATCH] Remove some old, unused options (#3511) --- lib/src/dartdoc_options.dart | 99 +++++++------------ lib/src/experiment_options.dart | 11 ++- .../templates.runtime_renderers.dart | 2 - lib/src/model/documentation_comment.dart | 22 ++--- lib/src/model/getter_setter_combo.dart | 38 ++++--- lib/src/source_linker.dart | 27 ++--- lib/src/warnings.dart | 17 ++-- 7 files changed, 93 insertions(+), 123 deletions(-) diff --git a/lib/src/dartdoc_options.dart b/lib/src/dartdoc_options.dart index ef649a6dd8..f8e3db78fb 100644 --- a/lib/src/dartdoc_options.dart +++ b/lib/src/dartdoc_options.dart @@ -1252,9 +1252,7 @@ class DartdocOptionContext extends DartdocOptionContextBase CategoryConfiguration get categories => optionSet['categories'].valueAt(context); - late final Set dropTextFrom = - Set.of(optionSet['dropTextFrom'].valueAt(context)); - + // TODO(srawlins): Remove when we remove support for `{@example}`. String? get examplePathPrefix => optionSet['examplePathPrefix'].valueAt(context); @@ -1268,8 +1266,6 @@ class DartdocOptionContext extends DartdocOptionContextBase String? get flutterRoot => optionSet['flutterRoot'].valueAt(context); - bool get hideSdkText => optionSet['hideSdkText'].valueAt(context); - late final Set include = Set.of(optionSet['include'].valueAt(context)); @@ -1375,85 +1371,59 @@ List createDartdocOptions( convertYamlToType: CategoryConfiguration.fromYamlMap, help: 'A list of all categories, their display names, and markdown ' 'documentation in the order they are to be displayed.'), - DartdocOptionSyntheticOnly>('dropTextFrom', - (DartdocSyntheticOption> option, Folder dir) { - if (option.parent['hideSdkText'].valueAt(dir)) { - return [ - 'dart.async', - 'dart.collection', - 'dart.convert', - 'dart.core', - 'dart.developer', - 'dart.html', - 'dart.indexed_db', - 'dart.io', - 'dart.isolate', - 'dart.js', - 'dart.js_util', - 'dart.math', - 'dart.mirrors', - 'dart.svg', - 'dart.typed_data', - 'dart.web_audio' - ]; - } - return const []; - }, resourceProvider, - help: 'Remove text from libraries with the following names.'), + // TODO(srawlins): Remove when we remove support for `{@example}`. DartdocOptionArgFile('examplePathPrefix', null, resourceProvider, optionIs: OptionKind.dir, - help: 'Prefix for @example paths.\n(defaults to the project root)', + help: '(deprecated) Prefix for @example paths; defaults to the project ' + 'root.', mustExist: true), DartdocOptionArgFile>('exclude', [], resourceProvider, - help: 'Library names to ignore.', splitCommas: true), + help: 'Names of libraries to exclude from documentation.', + splitCommas: true), DartdocOptionArgOnly>('excludePackages', [], resourceProvider, - help: 'Package names to ignore.', splitCommas: true), + help: 'Names of packages to exclude from documentation.', + splitCommas: true), DartdocOptionSyntheticOnly('flutterRoot', (DartdocSyntheticOption option, Folder dir) { var flutterRootEnv = packageMetaProvider.environmentProvider['FLUTTER_ROOT']; - if (flutterRootEnv == null) return null; - return resourceProvider.pathContext.resolveTildePath(flutterRootEnv); + return flutterRootEnv == null + ? null + : resourceProvider.pathContext.resolveTildePath(flutterRootEnv); }, resourceProvider, optionIs: OptionKind.dir, - help: 'Root of the Flutter SDK, specified from environment.', + help: 'Root of the Flutter SDK, specified from the environment.', mustExist: true), - DartdocOptionArgOnly('hideSdkText', false, resourceProvider, - hide: true, - help: 'Drop all text for SDK components. Helpful for integration ' - 'tests for dartdoc, probably not useful for anything else.', - negatable: true), DartdocOptionArgFile>('include', [], resourceProvider, - help: 'Library names to generate docs for.', splitCommas: true), + help: 'Names of libraries to document.', splitCommas: true), DartdocOptionArgFile>('includeExternal', [], resourceProvider, optionIs: OptionKind.file, - help: - 'Additional (external) dart files to include; use "dir/fileName", ' - 'as in lib/material.dart.', + help: 'Additional (external) dart files to include; use ' + '"/", as in "lib/material.dart".', mustExist: true, splitCommas: true), DartdocOptionArgOnly('includeSource', true, resourceProvider, help: 'Show source code blocks.', negatable: true), DartdocOptionArgOnly('injectHtml', false, resourceProvider, - help: 'Allow the use of the {@inject-html} directive to inject raw ' + help: 'Allow the use of the `{@inject-html}` directive to inject raw ' 'HTML into dartdoc output.'), DartdocOptionArgOnly('sanitizeHtml', false, resourceProvider, hide: true, - help: 'Sanitize HTML generated from markdown, {@tool} and ' - '{@inject-html} directives.'), + help: 'Sanitize HTML generated from markdown text, `{@tool}` and ' + '`{@inject-html}` directives.'), DartdocOptionArgOnly( 'input', resourceProvider.pathContext.current, resourceProvider, optionIs: OptionKind.dir, - help: 'Path to source directory', + help: 'Path to source directory.', mustExist: true), - DartdocOptionSyntheticOnly('inputDir', - (DartdocSyntheticOption option, Folder dir) { - if (option.parent['sdkDocs'].valueAt(dir)) { - return option.parent['sdkDir'].valueAt(dir); - } - return option.parent['input'].valueAt(dir); - }, resourceProvider, - help: 'Path to source directory (with override if --sdk-docs)', + DartdocOptionSyntheticOnly( + 'inputDir', + (DartdocSyntheticOption option, Folder dir) => + option.parent['sdkDocs'].valueAt(dir) == true + ? option.parent['sdkDir'].valueAt(dir) + : option.parent['input'].valueAt(dir), + resourceProvider, + help: 'Path to source directory (with override if --sdk-docs).', optionIs: OptionKind.dir, mustExist: true), DartdocOptionSet('linkTo', resourceProvider) @@ -1482,8 +1452,6 @@ List createDartdocOptions( // Prefer SDK check first, then pub cache check. var inSdk = packageMeta .sdkType(option.parent.parent['flutterRoot'].valueAt(dir)); - // Analyzer may be confused because package_meta still needs - // migrating. It can definitely return null. if (inSdk != null) { Map sdks = option.parent['sdks'].valueAt(dir); var inSdkVal = sdks[inSdk]; @@ -1501,14 +1469,16 @@ List createDartdocOptions( help: 'Allow links to be generated for packages outside this one.', negatable: true), ]), + // TODO(srawlins): Deprecate; with the advent of the unnamed library, this + // should be applied in each file, on the `library;` directive. DartdocOptionFileOnly>('nodoc', [], resourceProvider, optionIs: OptionKind.glob, - help: 'Dart symbols declared in these ' - 'files will be treated as though they have the @nodoc flag added to ' - 'their documentation comment.'), + help: 'Dart symbols declared in these files will be treated as though ' + 'they have the @nodoc directive added to their documentation ' + 'comment.'), DartdocOptionArgOnly('output', resourceProvider.pathContext.join('doc', 'api'), resourceProvider, - optionIs: OptionKind.dir, help: 'Path to output directory.'), + optionIs: OptionKind.dir, help: 'Path to the output directory.'), DartdocOptionSyntheticOnly( 'packageMeta', (DartdocSyntheticOption option, Folder dir) { @@ -1525,7 +1495,8 @@ List createDartdocOptions( splitCommas: true, help: 'A list of package names to place first when grouping libraries in ' - 'packages. Unmentioned packages are sorted after these.'), + 'packages. Unmentioned packages are placed after these.'), + // TODO(srawlins): Deprecate this option. DartdocOptionArgOnly('resourcesDir', null, resourceProvider, help: "An absolute path to dartdoc's resources directory.", hide: true), DartdocOptionArgOnly('sdkDocs', false, resourceProvider, diff --git a/lib/src/experiment_options.dart b/lib/src/experiment_options.dart index 0e573d5c50..281f6c60dc 100644 --- a/lib/src/experiment_options.dart +++ b/lib/src/experiment_options.dart @@ -22,11 +22,16 @@ mixin DartdocExperimentOptionContext implements DartdocOptionContextBase { // of [DartdocExperimentOptionContext], once a YAML file is available. List> createExperimentOptions( ResourceProvider resourceProvider) { + var knownFeatures = ExperimentStatus.knownFeatures.values; + var featureHelpTexts = + knownFeatures.map((e) => ' [no-]${e.enableString}: ${e.documentation} ' + '(default: ${e.isEnabledByDefault})'); return [ - // TODO(jcollins-g): Consider loading experiment values from dartdoc_options.yaml? + // TODO(jcollins-g): Consider loading experiment values from + // dartdoc_options.yaml? DartdocOptionArgOnly>( 'enable-experiment', ['non-nullable'], resourceProvider, - help: - 'Enable or disable listed experiments.\n${ExperimentStatus.knownFeatures.values.map((e) => ' [no-]${e.enableString}: ${e.documentation} (default: ${e.isEnabledByDefault})').join('\n')}'), + help: 'Enable or disable listed experiments.\n' + '${featureHelpTexts.join('\n')}'), ]; } diff --git a/lib/src/generator/templates.runtime_renderers.dart b/lib/src/generator/templates.runtime_renderers.dart index e2488fc9ed..c4dbb6c97e 100644 --- a/lib/src/generator/templates.runtime_renderers.dart +++ b/lib/src/generator/templates.runtime_renderers.dart @@ -16790,14 +16790,12 @@ const _invisibleGetters = { 'categories', 'categoryOrder', 'context', - 'dropTextFrom', 'examplePathPrefix', 'exclude', 'excludeFooterVersion', 'flutterRoot', 'format', 'hashCode', - 'hideSdkText', 'include', 'includeExternal', 'includeSource', diff --git a/lib/src/model/documentation_comment.dart b/lib/src/model/documentation_comment.dart index acc5a5b3a8..74a2d7dbd5 100644 --- a/lib/src/model/documentation_comment.dart +++ b/lib/src/model/documentation_comment.dart @@ -745,10 +745,10 @@ mixin DocumentationComment on Documentable, Warnable, Locatable, SourceCode { bool _documentationLocalIsSet = false; - /// Returns the documentation for this literal element unless - /// `config.dropTextFrom` indicates it should not be returned. Macro - /// definitions are stripped, but macros themselves are not injected. This is - /// a two stage process to avoid ordering problems. + /// Returns the documentation for this element. + /// + /// Macro definitions are stripped, but macros themselves are not injected. + /// This is a two stage process to avoid ordering problems. late final String _documentationLocal; String get documentationLocal { @@ -841,12 +841,7 @@ mixin DocumentationComment on Documentable, Warnable, Locatable, SourceCode { 'reentrant calls to _buildDocumentation* not allowed'); // Do not use the sync method if we need to evaluate tools or templates. assert(!isCanonical || !needsPrecache); - String rawDocs; - if (config.dropTextFrom.contains(element.library!.name)) { - rawDocs = ''; - } else { - rawDocs = _processCommentWithoutTools(documentationComment); - } + var rawDocs = _processCommentWithoutTools(documentationComment); return _rawDocs = buildDocumentationAddition(rawDocs); } @@ -854,13 +849,8 @@ mixin DocumentationComment on Documentable, Warnable, Locatable, SourceCode { Future _buildDocumentationBase() async { assert(_rawDocs == null, 'reentrant calls to _buildDocumentation* not allowed'); - String rawDocs; // Do not use the sync method if we need to evaluate tools or templates. - if (config.dropTextFrom.contains(element.library!.name)) { - rawDocs = ''; - } else { - rawDocs = await processComment(documentationComment); - } + var rawDocs = await processComment(documentationComment); return _rawDocs = buildDocumentationAddition(rawDocs); } diff --git a/lib/src/model/getter_setter_combo.dart b/lib/src/model/getter_setter_combo.dart index 79cb8074e4..2de9d4a9ef 100644 --- a/lib/src/model/getter_setter_combo.dart +++ b/lib/src/model/getter_setter_combo.dart @@ -20,7 +20,7 @@ import 'package:dartdoc/src/utils.dart'; import 'package:dartdoc/src/warnings.dart'; import 'package:meta/meta.dart'; -/// Mixin for top-level variables and fields (aka properties) +/// Mixin for top-level variables and fields (aka properties). mixin GetterSetterCombo on ModelElement { Accessor? get getter; @@ -178,7 +178,7 @@ mixin GetterSetterCombo on ModelElement { _getterSetterDocumentationComment.isNotEmpty || element.documentationComment != null; - /// Derive a documentation comment for the combo by copying documentation + /// Derives a documentation comment for the combo by copying documentation /// from the [getter] and/or [setter]. late final String _getterSetterDocumentationComment = () { // Check for synthetic before public, always, or stack overflow. @@ -188,13 +188,8 @@ mixin GetterSetterCombo on ModelElement { if (!getter.isSynthetic && getter.isPublic) { assert(getter.documentationFrom.length == 1); var fromGetter = getter.documentationFrom.first; - // We have to check against `dropTextFrom` here since - // `documentationFrom` doesn't yield the real elements for - // [GetterSetterCombo]s. - if (!config.dropTextFrom.contains(fromGetter.element.library!.name)) { - if (fromGetter.hasDocumentationComment) { - getterComment = fromGetter.documentationComment; - } + if (fromGetter.hasDocumentationComment) { + getterComment = fromGetter.documentationComment; } } } @@ -204,19 +199,17 @@ mixin GetterSetterCombo on ModelElement { } final setter = this.setter!; - if (!setter.isSynthetic && setter.isPublic) { - assert(setter.documentationFrom.length == 1); - var fromSetter = setter.documentationFrom.first; - if (!config.dropTextFrom.contains(fromSetter.element.library!.name)) { - if (fromSetter.hasDocumentationComment) { - return getterComment.isEmpty - ? fromSetter.documentationComment - : '$getterComment\n\n${fromSetter.documentationComment}'; - } - } + if (setter.isSynthetic || !setter.isPublic) return getterComment; + + assert(setter.documentationFrom.length == 1); + var fromSetter = setter.documentationFrom.first; + if (fromSetter.hasDocumentationComment) { + return getterComment.isEmpty + ? fromSetter.documentationComment + : '$getterComment\n\n${fromSetter.documentationComment}'; + } else { + return getterComment; } - - return getterComment; }(); ElementType get modelType { @@ -261,10 +254,13 @@ mixin GetterSetterCombo on ModelElement { 'GetterSetterCombo must be one of readOnly, writeOnly, or readWrite'); } + // TODO(srawlins): This should be private. bool get readOnly => hasPublicGetter && !hasPublicSetter; + // TODO(srawlins): This should be private. bool get readWrite => hasPublicGetter && hasPublicSetter; + // TODO(srawlins): This should be private. bool get writeOnly => hasPublicSetter && !hasPublicGetter; /// True if the @hideConstantImplementations directive is present diff --git a/lib/src/source_linker.dart b/lib/src/source_linker.dart index c8613e1848..f5525e50fa 100644 --- a/lib/src/source_linker.dart +++ b/lib/src/source_linker.dart @@ -33,22 +33,26 @@ List> createSourceLinkerOptions( ..addAll([ DartdocOptionArgFile>('excludes', [], resourceProvider, optionIs: OptionKind.dir, - help: - 'A list of directories to exclude from linking to a source code repository.'), - // TODO(jcollins-g): Use [DartdocOptionArgSynth], possibly in combination with a repository type and the root directory, and get revision number automatically + help: 'A list of directories to exclude from linking to a source ' + 'code repository.'), + // TODO(jcollins-g): Use [DartdocOptionArgSynth], possibly in + // combination with a repository type and the root directory, and get + // revision number automatically. DartdocOptionArgOnly('revision', null, resourceProvider, help: 'Revision number to insert into the URI.'), DartdocOptionArgFile('root', null, resourceProvider, optionIs: OptionKind.dir, help: - 'Path to a local directory that is the root of the repository we link to. All source code files under this directory will be linked.'), + 'Path to a local directory that is the root of the repository ' + 'we link to. All source code files under this directory will ' + 'be linked.'), DartdocOptionArgFile('uriTemplate', null, resourceProvider, - help: - '''Substitute into this template to generate a uri for an element's source code. - Dartdoc dynamically substitutes the following fields into the template: - %f%: Relative path of file to the repository root - %r%: Revision number - %l%: Line number'''), + help: ''' +Substitute into this template to generate a uri for an element's source code. + Dartdoc dynamically substitutes the following fields into the template: + %f%: Relative path of file to the repository root + %r%: Revision number + %l%: Line number'''), ]) ]; } @@ -73,7 +77,8 @@ class SourceLinker { if (revision != null || root != null || uriTemplate != null) { if (root == null || uriTemplate == null) { throw DartdocOptionError( - 'linkToSource root and uriTemplate must both be specified to generate repository links'); + 'linkToSource root and uriTemplate must both be specified to ' + 'generate repository links'); } var uriTemplateValue = uriTemplate; if (uriTemplateValue != null && diff --git a/lib/src/warnings.dart b/lib/src/warnings.dart index 3a2014acd6..b884dcd9c1 100644 --- a/lib/src/warnings.dart +++ b/lib/src/warnings.dart @@ -64,17 +64,22 @@ List> createPackageWarningOptions( // will override. DartdocOptionArgFile?>('errors', null, resourceProvider, splitCommas: true, - help: - 'Additional warning names to force as errors. Specify an empty list to force defaults (overriding dartdoc_options.yaml)\nDefaults:\n${_warningsListHelpText(PackageWarningMode.error)}'), + help: 'Additional warning names to force as errors. Specify an empty ' + 'list to force defaults (overriding dartdoc_options.yaml)\n' + 'Defaults:\n${_warningsListHelpText(PackageWarningMode.error)}'), DartdocOptionArgFile?>('ignore', null, resourceProvider, splitCommas: true, - help: - 'Additional warning names to ignore. Specify an empty list to force defaults (overriding dartdoc_options.yaml).\nDefaults:\n${_warningsListHelpText(PackageWarningMode.ignore)}'), + help: 'Additional warning names to ignore. Specify an empty list to ' + 'force defaults (overriding dartdoc_options.yaml).\n' + 'Defaults:\n${_warningsListHelpText(PackageWarningMode.ignore)}'), DartdocOptionArgFile?>('warnings', null, resourceProvider, splitCommas: true, help: - 'Additional warning names to show as warnings (instead of error or ignore, if not warning by default).\nDefaults:\n${_warningsListHelpText(PackageWarningMode.warn)}'), - // Synthetic option uses a factory to build a PackageWarningOptions from all the above flags. + 'Additional warning names to show as warnings (instead of error or ' + 'ignore, if not warning by default).\n' + 'Defaults:\n${_warningsListHelpText(PackageWarningMode.warn)}'), + // Synthetic option uses a factory to build a PackageWarningOptions from all + // the above flags. DartdocOptionSyntheticOnly( 'packageWarningOptions', (DartdocSyntheticOption option, Folder dir) =>