Clean up some doc comments and code style (#147)
- Note some argument restrictions when `name` must be a valid option.
- Remove a comment that adds no information on a constructor.
- Use a consistent pattern for checking valid option names -
`containsKey` rather than check for a `null` value.
- End a doc comment with a period.
- Change a getter doc comment to a noun phrase.
- Remove some repetitive details from doc comments, like types.
- Add explicit `show` to all exports rather than rely on catching all
package private stuff with a `hide`.
- Use `.toSet()` over `Set.from` to copy a set.
diff --git a/lib/args.dart b/lib/args.dart
index 97b47b5..a49c536 100644
--- a/lib/args.dart
+++ b/lib/args.dart
@@ -2,7 +2,7 @@
// for details. All rights reserved. Use of this source code is governed by a
// BSD-style license that can be found in the LICENSE file.
-export 'src/arg_parser.dart';
-export 'src/arg_parser_exception.dart';
-export 'src/arg_results.dart' hide newArgResults;
-export 'src/option.dart' hide newOption;
+export 'src/arg_parser.dart' show ArgParser;
+export 'src/arg_parser_exception.dart' show ArgParserException;
+export 'src/arg_results.dart' show ArgResults;
+export 'src/option.dart' show Option;
diff --git a/lib/src/arg_results.dart b/lib/src/arg_results.dart
index ca0f493..6345076 100644
--- a/lib/src/arg_results.dart
+++ b/lib/src/arg_results.dart
@@ -32,8 +32,8 @@
/// The option values that were parsed from arguments.
final Map<String, dynamic> _parsed;
- /// If these are the results for parsing a command's options, this will be the
- /// name of the command. For top-level results, this returns `null`.
+ /// The name of the command for which these options are parsed, or `null` if
+ /// these are the top-level results.
final String name;
/// The command that was selected, or `null` if none was.
@@ -49,16 +49,17 @@
/// `--` was reached.
final List<String> rest;
- /// The original list of arguments that were parsed.
+ /// The original arguments that were parsed.
final List<String> arguments;
- /// Creates a new [ArgResults].
ArgResults._(this._parser, this._parsed, this.name, this.command,
List<String> rest, List<String> arguments)
: rest = UnmodifiableListView(rest),
arguments = UnmodifiableListView(arguments);
- /// Gets the parsed command-line option named [name].
+ /// Returns the parsed ore default command-line option named [name].
+ ///
+ /// [name] must be a valid option name in the parser.
dynamic operator [](String name) {
if (!_parser.options.containsKey(name)) {
throw ArgumentError('Could not find an option named "$name".');
@@ -67,12 +68,12 @@
return _parser.options[name].getOrDefault(_parsed[name]);
}
- /// Get the names of the available options as an [Iterable].
+ /// The names of the available options.
///
- /// This includes the options whose values were parsed or that have defaults.
- /// Options that weren't present and have no default will be omitted.
+ /// Includes the options whose values were parsed or that have defaults.
+ /// Options that weren't present and have no default are omitted.
Iterable<String> get options {
- var result = Set<String>.from(_parsed.keys);
+ var result = _parsed.keys.toSet();
// Include the options that have defaults.
_parser.options.forEach((name, option) {
@@ -87,9 +88,10 @@
///
/// Returns `false` if it wasn't provided and the default value or no default
/// value would be used instead.
+ ///
+ /// [name] must be a valid option name in the parser.
bool wasParsed(String name) {
- var option = _parser.options[name];
- if (option == null) {
+ if (!_parser.options.containsKey(name)) {
throw ArgumentError('Could not find an option named "$name".');
}
diff --git a/lib/src/option.dart b/lib/src/option.dart
index 897f968..7fd9160 100644
--- a/lib/src/option.dart
+++ b/lib/src/option.dart
@@ -52,7 +52,7 @@
/// A map from values in [allowed] to documentation for those values.
final Map<String, String> allowedHelp;
- /// The value this option will have if the user doesn't explicitly pass it in
+ /// The value this option will have if the user doesn't explicitly pass it.
final dynamic defaultsTo;
@Deprecated('Use defaultsTo instead.')