Skip to content

Commit

Permalink
Remove some old, unused options (#3511)
Browse files Browse the repository at this point in the history
  • Loading branch information
@srawlins
srawlins committed Oct 8, 2023
1 parent c147aa1 commit affc5b4
Show file tree
Hide file tree
Showing 7 changed files with 93 additions and 123 deletions.
99 changes: 35 additions & 64 deletions lib/src/dartdoc_options.dart
View file
Original file line number Diff line number Diff line change
Expand Up @@ -1252,9 +1252,7 @@ class DartdocOptionContext extends DartdocOptionContextBase
CategoryConfiguration get categories =>
optionSet['categories'].valueAt(context);

late final Set<String> dropTextFrom =
Set.of(optionSet['dropTextFrom'].valueAt(context));

// TODO(srawlins): Remove when we remove support for `{@example}`.
String? get examplePathPrefix =>
optionSet['examplePathPrefix'].valueAt(context);

Expand All @@ -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<String> include =
Set.of(optionSet['include'].valueAt(context));

Expand Down Expand Up @@ -1375,85 +1371,59 @@ List<DartdocOption> 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<List<String>>('dropTextFrom',
(DartdocSyntheticOption<List<String>> 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<String?>('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<List<String>>('exclude', [], resourceProvider,
help: 'Library names to ignore.', splitCommas: true),
help: 'Names of libraries to exclude from documentation.',
splitCommas: true),
DartdocOptionArgOnly<List<String>>('excludePackages', [], resourceProvider,
help: 'Package names to ignore.', splitCommas: true),
help: 'Names of packages to exclude from documentation.',
splitCommas: true),
DartdocOptionSyntheticOnly<String?>('flutterRoot',
(DartdocSyntheticOption<String?> 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<bool>('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<List<String>>('include', [], resourceProvider,
help: 'Library names to generate docs for.', splitCommas: true),
help: 'Names of libraries to document.', splitCommas: true),
DartdocOptionArgFile<List<String>>('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 '
'"<directory name>/<file name>", as in "lib/material.dart".',
mustExist: true,
splitCommas: true),
DartdocOptionArgOnly<bool>('includeSource', true, resourceProvider,
help: 'Show source code blocks.', negatable: true),
DartdocOptionArgOnly<bool>('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<bool>('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<String>(
'input', resourceProvider.pathContext.current, resourceProvider,
optionIs: OptionKind.dir,
help: 'Path to source directory',
help: 'Path to source directory.',
mustExist: true),
DartdocOptionSyntheticOnly<String>('inputDir',
(DartdocSyntheticOption<String> 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<String>(
'inputDir',
(DartdocSyntheticOption<String> 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)
Expand Down Expand Up @@ -1482,8 +1452,6 @@ List<DartdocOption> 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<String, String> sdks = option.parent['sdks'].valueAt(dir);
var inSdkVal = sdks[inSdk];
Expand All @@ -1501,14 +1469,16 @@ List<DartdocOption> 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<List<String>>('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<String>('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>(
'packageMeta',
(DartdocSyntheticOption<PackageMeta> option, Folder dir) {
Expand All @@ -1525,7 +1495,8 @@ List<DartdocOption> 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<String?>('resourcesDir', null, resourceProvider,
help: "An absolute path to dartdoc's resources directory.", hide: true),
DartdocOptionArgOnly<bool>('sdkDocs', false, resourceProvider,
Expand Down
11 changes: 8 additions & 3 deletions lib/src/experiment_options.dart
View file
Original file line number Diff line number Diff line change
Expand Up @@ -22,11 +22,16 @@ mixin DartdocExperimentOptionContext implements DartdocOptionContextBase {
// of [DartdocExperimentOptionContext], once a YAML file is available.
List<DartdocOption<Object>> 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<List<String>>(
'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')}'),
];
}
2 changes: 0 additions & 2 deletions lib/src/generator/templates.runtime_renderers.dart
View file
Original file line number Diff line number Diff line change
Expand Up @@ -16790,14 +16790,12 @@ const _invisibleGetters = {
'categories',
'categoryOrder',
'context',
'dropTextFrom',
'examplePathPrefix',
'exclude',
'excludeFooterVersion',
'flutterRoot',
'format',
'hashCode',
'hideSdkText',
'include',
'includeExternal',
'includeSource',
Expand Down
22 changes: 6 additions & 16 deletions lib/src/model/documentation_comment.dart
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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 {
Expand Down Expand Up @@ -841,26 +841,16 @@ 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);
}

/// Can only be used as part of `PackageGraph.setUpPackageGraph`.
Future<String> _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);
}

Expand Down
38 changes: 17 additions & 21 deletions lib/src/model/getter_setter_combo.dart
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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;

Expand Down Expand Up @@ -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.
Expand All @@ -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;
}
}
}
Expand All @@ -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 {
Expand Down Expand Up @@ -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
Expand Down
27 changes: 16 additions & 11 deletions lib/src/source_linker.dart
View file
Original file line number Diff line number Diff line change
Expand Up @@ -33,22 +33,26 @@ List<DartdocOption<Object?>> createSourceLinkerOptions(
..addAll([
DartdocOptionArgFile<List<String>>('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<String?>('revision', null, resourceProvider,
help: 'Revision number to insert into the URI.'),
DartdocOptionArgFile<String?>('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<String?>('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'''),
])
];
}
Expand All @@ -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 &&
Expand Down
Loading

0 comments on commit affc5b4

Please sign in to comment.