Skip to content

Trim comments and strings to 80 columns #2306

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 1 commit into from
Aug 17, 2020
Merged

Trim comments and strings to 80 columns #2306

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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: 73 additions & 53 deletions lib/src/dartdoc_options.dart
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -99,7 +99,8 @@ class CategoryConfiguration {
pathContext.canonicalize(documentationMarkdown);
if (!File(documentationMarkdown).existsSync()) {
throw DartdocFileMissing(
'In categories definition for ${name}, "markdown" resolves to the missing file $documentationMarkdown');
'In categories definition for ${name}, "markdown" resolves to '
'the missing file $documentationMarkdown');
}
}
newCategoryDefinitions[name] =
Expand Down Expand Up @@ -266,8 +267,8 @@ class DartToolDefinition extends ToolDefinition {
Future<Tuple2<String, Function()>> modifyArgsToCreateSnapshotIfNeeded(
List<String> args) async {
assert(args[0] == command.first);
// Set up flags to create a new snapshot, if needed, and use the first run as the training
// run.
// Set up flags to create a new snapshot, if needed, and use the first run
// as the training run.
var snapshot = SnapshotCache.instance.getSnapshot(command.first);
var snapshotFile = snapshot.snapshotFile;
var needsSnapshot = snapshot.needsSnapshot;
Expand Down Expand Up @@ -432,15 +433,18 @@ class _OptionValueWithContext<T> {
p.Context pathContext;

/// Build a _OptionValueWithContext.
/// [path] is the path where this value came from (not required to be canonical)
///
/// [path] is the path where this value came from (not required to be
/// canonical).
_OptionValueWithContext(this.value, String path, {String definingFile}) {
this.definingFile = definingFile;
canonicalDirectoryPath = p.canonicalize(path);
pathContext = p.Context(current: canonicalDirectoryPath);
}

/// Assume value is a path, and attempt to resolve it. Throws [UnsupportedError]
/// if [T] isn't a [String] or [List<String>].
/// Assume value is a path, and attempt to resolve it.
///
/// Throws [UnsupportedError] if [T] isn't a [String] or [List<String>].
T get resolvedValue {
if (value is List<String>) {
return (value as List<String>)
Expand All @@ -462,12 +466,12 @@ class _OptionValueWithContext<T> {

/// An abstract class for interacting with dartdoc options.
///
/// This class and its implementations allow Dartdoc to declare options
/// that are both defined in a configuration file and specified via the
/// command line, with searching the directory tree for a proper file
/// and overriding file options with the command line built-in. A number
/// of sanity checks are also built in to these classes so that file existence
/// can be verified, types constrained, and defaults provided.
/// This class and its implementations allow Dartdoc to declare options that
/// are both defined in a configuration file and specified via the command line,
/// with searching the directory tree for a proper file and overriding file
/// options with the command line built-in. A number of sanity checks are also
/// built in to these classes so that file existence can be verified, types
/// constrained, and defaults provided.
///
/// Use via implementations [DartdocOptionSet], [DartdocOptionArgFile],
/// [DartdocOptionArgOnly], and [DartdocOptionFileOnly].
Expand Down Expand Up @@ -623,7 +627,8 @@ abstract class DartdocOption<T> {
/// Direct children of this node, mapped by name.
final Map<String, DartdocOption<Object>> _children = {};

/// Return the calculated value of this option, given the directory as context.
/// Return the calculated value of this option, given the directory as
/// context.
///
/// If [isFile] or [isDir] is set, the returned value will be transformed
/// into a canonical path relative to the current working directory
Expand Down Expand Up @@ -807,13 +812,15 @@ abstract class DartdocSyntheticOption<T> implements DartdocOption<T> {
_OptionValueWithContext<Object> valueWithContext, String missingPath) {
var description = 'Synthetic configuration option ${name} from <internal>';
throw DartdocFileMissing(
'$description, computed as ${valueWithContext.value}, resolves to missing path: "${missingPath}"');
'$description, computed as ${valueWithContext.value}, resolves to '
'missing path: "${missingPath}"');
}
}

typedef OptionGenerator = Future<List<DartdocOption<Object>>> Function();

/// A [DartdocOption] that only contains other [DartdocOption]s and is not an option itself.
/// A [DartdocOption] that only contains other [DartdocOption]s and is not an
/// option itself.
class DartdocOptionSet extends DartdocOption<Null> {
DartdocOptionSet(String name)
: super(name, null, null, false, false, false, null);
Expand Down Expand Up @@ -842,15 +849,16 @@ class DartdocOptionSet extends DartdocOption<Null> {
void _onMissing(_OptionValueWithContext<Object> valueWithContext,
String missingFilename) {}

/// Traverse skips this node, because it doesn't represent a real configuration object.
/// Traverse skips this node, because it doesn't represent a real
/// configuration object.
@override
void traverse(void Function(DartdocOption<Object> option) visitor) {
_children.values.forEach((d) => d.traverse(visitor));
}
}

/// A [DartdocOption] that only exists as a command line argument. --help would
/// be a good example.
/// A [DartdocOption] that only exists as a command line argument. `--help` is a
/// good example.
class DartdocOptionArgOnly<T> extends DartdocOption<T>
with _DartdocArgOption<T> {
String _abbr;
Expand Down Expand Up @@ -887,7 +895,8 @@ class DartdocOptionArgOnly<T> extends DartdocOption<T>
bool get splitCommas => _splitCommas;
}

/// A [DartdocOption] that works with command line arguments and dartdoc_options files.
/// A [DartdocOption] that works with command line arguments and
/// `dartdoc_options` files.
class DartdocOptionArgFile<T> extends DartdocOption<T>
with _DartdocArgOption<T>, _DartdocFileOption<T> {
String _abbr;
Expand Down Expand Up @@ -924,8 +933,8 @@ class DartdocOptionArgFile<T> extends DartdocOption<T>
}
}

/// Try to find an explicit argument setting this value, but if not, fall back to files
/// finally, the default.
/// Try to find an explicit argument setting this value, but if not, fall back
/// to files finally, the default.
@override
T valueAt(Directory dir) {
var value = _valueAtFromArgs();
Expand Down Expand Up @@ -972,8 +981,9 @@ class DartdocOptionFileOnly<T> extends DartdocOption<T>

/// Implements checking for options contained in dartdoc.yaml.
abstract class _DartdocFileOption<T> implements DartdocOption<T> {
/// If true, the parent directory's value overrides the child's. Otherwise, the child's
/// value overrides values in parents.
/// If true, the parent directory's value overrides the child's.
///
/// Otherwise, the child's value overrides values in parents.
bool get parentDirOverridesChild;

/// The name of the option, with nested options joined by [.]. For example:
Expand All @@ -995,8 +1005,9 @@ abstract class _DartdocFileOption<T> implements DartdocOption<T> {
_OptionValueWithContext<Object> valueWithContext, String missingPath) {
var dartdocYaml = p.join(
valueWithContext.canonicalDirectoryPath, valueWithContext.definingFile);
throw DartdocFileMissing(
'Field ${fieldName} from ${dartdocYaml}, set to ${valueWithContext.value}, resolves to missing path: "${missingPath}"');
throw DartdocFileMissing('Field ${fieldName} from ${dartdocYaml}, set to '
'${valueWithContext.value}, resolves to missing path: '
'"${missingPath}"');
}

@override
Expand Down Expand Up @@ -1025,9 +1036,8 @@ abstract class _DartdocFileOption<T> implements DartdocOption<T> {
return __valueAtFromFiles[key];
}

/// Searches all dartdoc_options files through parent directories,
/// starting at [dir], for the option and returns one once
/// found.
/// Searches all dartdoc_options files through parent directories, starting at
/// [dir], for the option and returns one once found.
_OptionValueWithContext<Object> _valueAtFromFilesFirstFound(Directory dir) {
_OptionValueWithContext<Object> value;
while (true) {
Expand All @@ -1038,8 +1048,8 @@ abstract class _DartdocFileOption<T> implements DartdocOption<T> {
return value;
}

/// Searches all dartdoc_options files for the option, and returns the
/// value in the top-most parent directory dartdoc_options.yaml file it is
/// 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<Object> _valueAtFromFilesLastFound(Directory dir) {
_OptionValueWithContext<Object> value;
Expand All @@ -1052,7 +1062,7 @@ abstract class _DartdocFileOption<T> implements DartdocOption<T> {
return value;
}

/// Returns null if not set in the yaml file in this directory (or its
/// Returns null if not set in the YAML file in this directory (or its
/// parents).
_OptionValueWithContext<Object> _valueAtFromFile(Directory dir) {
var yamlFileData = _yamlAtDirectory(dir);
Expand Down Expand Up @@ -1090,7 +1100,8 @@ abstract class _DartdocFileOption<T> implements DartdocOption<T> {
}
if (_convertYamlToType == null) {
throw DartdocOptionError(
'Unable to convert yaml to type for option: $fieldName, method not defined');
'Unable to convert yaml to type for option: $fieldName, method not '
'defined');
}
var canonicalDirectoryPath = p.canonicalize(contextPath);
returnData = _convertYamlToType(
Expand Down Expand Up @@ -1138,16 +1149,19 @@ abstract class _DartdocFileOption<T> implements DartdocOption<T> {

/// Mixin class implementing command-line arguments for [DartdocOption].
abstract class _DartdocArgOption<T> implements DartdocOption<T> {
/// For [ArgParser], set to true if the argument can be negated with --no on the command line.
/// For [ArgParser], set to true if the argument can be negated with `--no` on
/// the command line.
bool get negatable;

/// For [ArgParser], set to true if a single string argument will be broken into a list on commas.
/// For [ArgParser], set to true if a single string argument will be broken
/// into a list on commas.
bool get splitCommas;

/// For [ArgParser], set to true to hide this from the help menu.
bool get hide;

/// For [ArgParser], set to a single character to have a short version of the command line argument.
/// For [ArgParser], set to a single character to have a short version of the
/// command line argument.
String get abbr;

/// valueAt for arguments ignores the [dir] parameter and only uses command
Expand All @@ -1166,7 +1180,8 @@ abstract class _DartdocArgOption<T> implements DartdocOption<T> {
example = '0.76';
}
throw DartdocOptionError(
'Invalid argument value: --${argName}, set to "${value}", must be a ${T}. Example: --${argName} ${example}');
'Invalid argument value: --${argName}, set to "${value}", must be a '
'${T}. Example: --${argName} ${example}');
}

/// Returns null if no argument was given on the command line.
Expand All @@ -1183,7 +1198,8 @@ abstract class _DartdocArgOption<T> implements DartdocOption<T> {
void _onMissingFromArgs(
_OptionValueWithContext<Object> valueWithContext, String missingPath) {
throw DartdocFileMissing(
'Argument --${argName}, set to ${valueWithContext.value}, resolves to missing path: "${missingPath}"');
'Argument --${argName}, set to ${valueWithContext.value}, resolves to '
'missing path: "${missingPath}"');
}

/// Generates an _OptionValueWithContext using the value of the argument from
Expand All @@ -1194,9 +1210,9 @@ abstract class _DartdocArgOption<T> implements DartdocOption<T> {
if (!_argResults.wasParsed(argName)) return null;

T retval;
// Unlike in _DartdocFileOption, we throw here on inputs being invalid rather
// than silently proceeding. TODO(jcollins-g): throw on input formatting for
// files too?
// Unlike in _DartdocFileOption, we throw here on inputs being invalid
// rather than silently proceeding. TODO(jcollins-g): throw on input
// formatting for files too?
if (_isBool || _isListString || _isString) {
retval = _argResults[argName];
} else if (_isInt) {
Expand Down Expand Up @@ -1289,9 +1305,11 @@ abstract class DartdocOptionContextBase {
}

/// An [DartdocOptionSet] wrapped in nice accessors specific to Dartdoc, which
/// automatically passes in the right directory for a given context. Usually,
/// a single [ModelElement], [Package], [Category] and so forth has a single context
/// and so this can be made a member variable of those structures.
/// automatically passes in the right directory for a given context.
///
/// Usually, a single [ModelElement], [Package], [Category] and so forth has a
/// single context and so this can be made a member variable of those
/// structures.
class DartdocOptionContext extends DartdocOptionContextBase
with
DartdocExperimentOptionContext,
Expand Down Expand Up @@ -1325,7 +1343,8 @@ class DartdocOptionContext extends DartdocOptionContextBase
return DartdocOptionContext(optionSet, File(element.source.fullName));
}

/// Build a DartdocOptionContext from an existing [DartdocOptionContext] and a new analyzer [Element].
/// Build a DartdocOptionContext from an existing [DartdocOptionContext] and a
/// new analyzer [Element].
factory DartdocOptionContext.fromContextElement(
DartdocOptionContext optionContext, Element element) {
return DartdocOptionContext.fromElement(optionContext.optionSet, element);
Expand Down Expand Up @@ -1422,7 +1441,8 @@ class DartdocOptionContext extends DartdocOptionContextBase
/// Output format, e.g. 'html', 'md'
String get format => optionSet['format'].valueAt(context);

// TODO(jdkoren): temporary while we confirm href base behavior doesn't break important clients
// TODO(jdkoren): temporary while we confirm href base behavior doesn't break
// important clients
bool get useBaseHref => optionSet['useBaseHref'].valueAt(context);
}

Expand All @@ -1443,9 +1463,9 @@ Future<List<DartdocOption<Object>>> createDartdocOptions(
'in the current package or "include-external"',
negatable: true),
DartdocOptionArgFile<List<String>>('categoryOrder', [],
help:
"A list of categories (not package names) to place first when grouping symbols on dartdoc's sidebar. "
'Unmentioned categories are sorted after these.'),
help: 'A list of categories (not package names) to place first when '
"grouping symbols on dartdoc's sidebar. Unmentioned categories are "
'sorted after these.'),
DartdocOptionFileOnly<CategoryConfiguration>(
'categories', CategoryConfiguration.empty,
convertYamlToType: CategoryConfiguration.fromYamlMap,
Expand Down Expand Up @@ -1573,8 +1593,8 @@ Future<List<DartdocOption<Object>>> createDartdocOptions(
),
DartdocOptionArgOnly<List<String>>('packageOrder', [],
help:
'A list of package names to place first when grouping libraries in packages. '
'Unmentioned packages are sorted after these.'),
'A list of package names to place first when grouping libraries in '
'packages. Unmentioned packages are sorted after these.'),
DartdocOptionArgOnly<bool>('sdkDocs', false,
help: 'Generate ONLY the docs for the Dart SDK.'),
DartdocOptionArgSynth<String>('sdkDir',
Expand Down Expand Up @@ -1606,8 +1626,8 @@ Future<List<DartdocOption<Object>>> createDartdocOptions(
DartdocOptionArgOnly<bool>('useCategories', true,
help: 'Display categories in the sidebar of packages'),
DartdocOptionArgOnly<bool>('validateLinks', true,
help:
'Runs the built-in link checker to display Dart context aware warnings for broken links (slow)',
help: 'Runs the built-in link checker to display Dart context aware '
'warnings for broken links (slow)',
negatable: true),
DartdocOptionArgOnly<bool>('verboseWarnings', true,
help: 'Display extra debugging information and help with warnings.',
Expand All @@ -1625,7 +1645,7 @@ Future<List<DartdocOption<Object>>> createDartdocOptions(
'Use <base href> in generated files (legacy behavior). This option '
'is temporary and support will be removed in the future. Use only '
'if the default behavior breaks links between your documentation '
'pages, and please file an issue on Github.',
'pages, and please file an issue on GitHub.',
negatable: false,
hide: true),
// TODO(jdkoren): Unhide when we have good support for another format.
Expand Down