docs: improve dart docs (#28)

lib/cli_completion.dart

@@ -4,6 +4,3 @@ library cli_completion;
 
 export 'src/command_runner/commands/commands.dart';
 export 'src/command_runner/completion_command_runner.dart';
-export 'src/handling/completion_result.dart';
-export 'src/handling/completion_state.dart';
-export 'src/system_shell.dart';

lib/installer.dart

@@ -0,0 +1,8 @@
+/// Contains the functions related to the installation process
+/// {@canonicalFor system_shell.SystemShell}
+library installer;
+
+export 'src/installer/completion_installation.dart';
+export 'src/installer/exceptions.dart';
+export 'src/installer/shell_completion_configuration.dart';
+export 'src/system_shell.dart';

lib/parser.dart

@@ -0,0 +1,9 @@
+/// Contains the classes and functions related to the creation of suggestions
+/// for the completion of commands.
+library parser;
+
+export 'src/parser/completion_level.dart';
+export 'src/parser/completion_result.dart';
+export 'src/parser/completion_state.dart';
+export 'src/parser/parser.dart';
+export 'src/system_shell.dart';

lib/src/command_runner/commands/handle_completion_command.dart

@@ -1,10 +1,8 @@
 import 'dart:async';
 
 import 'package:args/command_runner.dart';
-import 'package:cli_completion/src/command_runner/completion_command_runner.dart';
-import 'package:cli_completion/src/handling/completion_level.dart';
-import 'package:cli_completion/src/handling/completion_state.dart';
-import 'package:cli_completion/src/handling/parser.dart';
+import 'package:cli_completion/cli_completion.dart';
+import 'package:cli_completion/parser.dart';
 
 /// {@template handle_completion_request_command}
 /// A hidden [Command] added by [CompletionCommandRunner] that handles the

lib/src/command_runner/commands/install_completion_files_command.dart

@@ -1,13 +1,14 @@
 import 'dart:async';
 
 import 'package:args/command_runner.dart';
-import 'package:cli_completion/src/command_runner/completion_command_runner.dart';
-
+import 'package:cli_completion/cli_completion.dart';
 import 'package:mason_logger/mason_logger.dart';
 
 /// {@template install_completion_command}
-/// A hidden [Command] added by [CompletionCommandRunner] that can be used to
-/// manually install the completion files
+/// A hidden [Command] added by [CompletionCommandRunner] that handles the
+/// "install-completion-files" sub command.
+///
+/// It can be used to manually install the completion files
 /// (otherwise automatically installed by [CompletionCommandRunner]).
 /// {@endtemplate}
 ///

lib/src/command_runner/completion_command_runner.dart

@@ -3,8 +3,8 @@ import 'dart:async';
 import 'package:args/args.dart';
 import 'package:args/command_runner.dart';
 import 'package:cli_completion/cli_completion.dart';
-import 'package:cli_completion/src/exceptions.dart';
-import 'package:cli_completion/src/install/completion_installation.dart';
+import 'package:cli_completion/installer.dart';
+import 'package:cli_completion/parser.dart';
 import 'package:mason_logger/mason_logger.dart';
 import 'package:meta/meta.dart';
 

lib/src/install/completion_installation.dart → lib/src/installer/completion_installation.dart

@@ -1,14 +1,12 @@
 import 'dart:io';
 
-import 'package:cli_completion/src/exceptions.dart';
-import 'package:cli_completion/src/install/shell_completion_configuration.dart';
-import 'package:cli_completion/src/system_shell.dart';
+import 'package:cli_completion/installer.dart';
 import 'package:mason_logger/mason_logger.dart';
 import 'package:meta/meta.dart';
 import 'package:path/path.dart' as path;
 
 /// {@template shell_completion_installation}
-/// A description of a completion installation process for a specific shell.
+/// Manages the installation of completion scripts for the current shell.
 ///
 /// Creation should be done via [CompletionInstallation.fromSystemShell].
 /// {@endtemplate}
@@ -22,7 +20,16 @@ class CompletionInstallation {
     required this.environment,
   });
 
-  /// Creates a [CompletionInstallation] given the current [SystemShell].
+  /// Creates a [CompletionInstallation] given the current [systemShell].
+  ///
+  /// If [systemShell] is null, it will assume that the current shell is
+  /// unknown and [configuration] will be null.
+  ///
+  /// Pass [isWindowsOverride] to override the default value of
+  /// [Platform.isWindows].
+  ///
+  /// Pass [environmentOverride] to override the default value of
+  /// [Platform.environment].
   factory CompletionInstallation.fromSystemShell({
     required SystemShell? systemShell,
     required Logger logger,
@@ -54,11 +61,18 @@ class CompletionInstallation {
   /// equals to [Platform.environment].
   final Map<String, String> environment;
 
-  /// The associated [ShellCompletionConfiguration].
+  /// The associated [ShellCompletionConfiguration] inferred from the current
+  /// shell. It is null if the current shell is unknown.
   final ShellCompletionConfiguration? configuration;
 
   /// Define the [Directory] in which the
   /// completion configuration files will be stored.
+  ///
+  /// If [isWindows] is true, it will return the directory defined by
+  /// %LOCALAPPDATA%/DartCLICompletion
+  ///
+  /// If [isWindows] is false, it will return the directory defined by
+  /// $HOME/.dart_cli_completion
   @visibleForTesting
   Directory get completionConfigDir {
     if (isWindows) {
@@ -72,8 +86,17 @@ class CompletionInstallation {
     }
   }
 
-  /// Install completion configuration hooks for a [rootCommand] in the
+  /// Install completion configuration files for a [rootCommand] in the
   /// current shell.
+  ///
+  /// It will create:
+  /// - A completion script file in [completionConfigDir] that is named after
+  /// the [rootCommand] and the current shell (e.g. `very_good.bash`).
+  /// - A config file in [completionConfigDir] that is named after the current
+  /// shell (e.g. `bash-config.bash`) that sources the aforementioned
+  /// completion script file.
+  /// - A line in the shell config file (e.g. `.bash_profile`) that sources
+  /// the aforementioned config file.
   void install(String rootCommand) {
     final configuration = this.configuration;
 
@@ -95,7 +118,10 @@ class CompletionInstallation {
     writeToShellConfigFile(rootCommand);
   }
 
-  /// Create a directory in which the completion config files shall be saved
+  /// Create a directory in which the completion config files shall be saved.
+  /// If the directory already exists, it will do nothing.
+  ///
+  /// The directory is defined by [completionConfigDir].
   @visibleForTesting
   void createCompletionConfigDir() {
     final completionConfigDirPath = completionConfigDir.path;
@@ -117,6 +143,13 @@ class CompletionInstallation {
 
   /// Creates a configuration file exclusively to [rootCommand] and the
   /// identified shell.
+  ///
+  /// The file will be named after the [rootCommand] and the current shell
+  /// (e.g. `very_good.bash`).
+  ///
+  /// The file will be created in [completionConfigDir].
+  ///
+  /// If the file already exists, it will do nothing.
   @visibleForTesting
   void writeCompletionScriptForCommand(String rootCommand) {
     final configuration = this.configuration!;
@@ -185,7 +218,7 @@ class CompletionInstallation {
       _resolveHome(configuration!.shellRCFile, environment);
 
   /// Write a source to the completion global script in the shell configuration
-  /// file, which its location is described by the [configuration]
+  /// file, which its location is described by the [configuration].
   @visibleForTesting
   void writeToShellConfigFile(String rootCommand) {
     final configuration = this.configuration!;

lib/src/install/shell_completion_configuration.dart → lib/src/installer/shell_completion_configuration.dart

@@ -1,4 +1,4 @@
-import 'package:cli_completion/src/system_shell.dart';
+import 'package:cli_completion/installer.dart';
 import 'package:meta/meta.dart';
 
 /// A type definition for functions that creates the content of a
@@ -10,10 +10,12 @@ typedef CompletionScriptTemplate = String Function(String rootCommand);
 typedef SourceStringTemplate = String Function(String scriptPath);
 
 /// {@template shell_completion_configuration}
-/// Describes the configuration of a completion script in a specific shell.
+/// Describes all the configuration needed to install completion scripts on a
+/// specific shell.
 ///
 /// See:
-/// - [zshConfiguration] for zsh
+/// - [ShellCompletionConfiguration.fromSystemShell] to retrieve the
+/// configuration for a [SystemShell].
 @immutable
 class ShellCompletionConfiguration {
   /// {@macro shell_completion_configuration}

lib/src/handling/arg_parser_extension.dart → lib/src/parser/arg_parser_extension.dart

@@ -2,20 +2,23 @@ import 'package:args/args.dart';
 
 final _optionRegex = RegExp(r'^--(([a-zA-Z\-_0-9]+)(=(.*))?)?$');
 
-/// Defines if [string] is an option.
+/// Defines if [string] complies with the GNU argument syntax.
+///
+/// Does not match abbreviated options.
 bool isOption(String string) => _optionRegex.hasMatch(string);
 
 final _abbrRegex = RegExp(r'^-(([a-zA-Z0-9]+)(.*))?$');
 
-/// Defines if [string] is an option in an abbreviated form.
+/// Defines if [string] complies with the GNU argument syntax in an
+/// abbreviated form.
 bool isAbbr(String string) => _abbrRegex.hasMatch(string);
 
 /// Extends [ArgParser] with utility methods that allow parsing a completion
 /// input, which in most cases only regards part of the rules.
 extension ArgParserExtension on ArgParser {
   /// Parses [args] with this [ArgParser]'s command structure only, ignore
   /// option strict rules (mandatory, allowed values, non negatable flags,
-  /// default values);
+  /// default values, etc);
   ///
   /// Still breaks if an unknown option/alias is passed.
   ///

lib/src/handling/completion_level.dart → lib/src/parser/completion_level.dart

@@ -1,10 +1,10 @@
 import 'package:args/args.dart';
 import 'package:args/command_runner.dart';
-import 'package:cli_completion/src/handling/arg_parser_extension.dart';
+import 'package:cli_completion/src/parser/arg_parser_extension.dart';
 import 'package:meta/meta.dart';
 
 /// {@template completion_level}
-/// The necessary information to produce completion for [CommandRunner] based
+/// The necessary information to produce completion for [CommandRunner]-based
 /// cli applications.
 /// {@endtemplate}
 ///
@@ -33,16 +33,17 @@ class CompletionLevel {
   /// ```
   /// root_command -f command1 command2 -o
   /// ```
-  /// Consider `root_command` the cli executable and command1`  a sub command
+  /// Consider `root_command` the cli executable and command1` a sub command
   /// of `root_command` and `command2` a sub command of `command1`.
   ///
   /// In a scenario where the user requests completion for this line, all
   /// possible suggestions (options, flags and sub commands) should be declared
   /// under the [ArgParser] object belonging to `command2`, all the args
-  /// preceding `command2` are not considered for completion.
+  /// preceding `command2` are **not** considered for completion.
   ///
-  /// if the user input does not respect the known structure of commands,
-  /// it returns null.
+  /// if the user input does not respect the known structure of commands, or if
+  /// there is any error when parsing the command structure, the
+  /// [CompletionLevel] will be `null`.
   static CompletionLevel? find(
     Iterable<String> rootArgs,
     ArgParser runnerGrammar,

lib/src/handling/completion_result.dart → lib/src/parser/completion_result.dart

@@ -1,5 +1,5 @@
 import 'package:args/args.dart';
-import 'package:cli_completion/src/handling/completion_level.dart';
+import 'package:cli_completion/parser.dart';
 import 'package:meta/meta.dart';
 
 /// {@template completion_result}
@@ -124,7 +124,7 @@ class MatchingCommandsCompletionResult extends CompletionResult {
 
 /// {@template matching_options_completion_result}
 /// A [CompletionResult] that suggests the options in a [completionLevel] that
-/// matches [pattern] (A.K.A: startsWith).
+/// starts with [pattern].
 /// {@endtemplate}
 ///
 /// If an option does not match the pattern, its aliases will be checked.
@@ -161,15 +161,15 @@ class MatchingOptionsCompletionResult extends CompletionResult {
 }
 
 /// {@template option_values_completion_result}
-/// A [CompletionResult] that suggests the values of options given an
+/// A [CompletionResult] that suggests the values of an option given its
 /// [optionName] and its [completionLevel].
 /// {@endtemplate}
 ///
-/// For Options with [Option.allowed] values, the suggestions will be those
+/// For options with [Option.allowed] values, the suggestions will be those
 /// values with [Option.allowedHelp] as description.
 ///
-/// If [pattern] is not null, only the values that match the pattern will be
-/// suggested.
+/// If [pattern] is not null, only the values that start with the pattern will
+/// be suggested.
 ///
 /// Use [OptionValuesCompletionResult.isAbbr] to suggest the values of an option
 /// in an abbreviated form.
@@ -191,7 +191,7 @@ class OptionValuesCompletionResult extends CompletionResult {
   })  : isAbbr = true,
         optionName = abbrName;
 
-  /// The [CompletionLevel] in which the suggested options are supposed to be
+  /// The [CompletionLevel] in which the suggested option is supposed to be
   /// located at.
   final CompletionLevel completionLevel;
 
@@ -206,6 +206,9 @@ class OptionValuesCompletionResult extends CompletionResult {
 
   /// Whether the option name should be included in the suggestions.
   /// This is only used when [isAbbr] is true.
+  ///
+  /// If true, suggestions will look like `-psomething` where `p` is the
+  /// abbreviated option name and `something` is the suggested value.
   final bool includeAbbrName;
 
   @override