Adds better documentation to CLI, Command, and git plugin

Author: codenamev

lib/git_commander/cli.rb

@@ -5,12 +5,17 @@
 require "optparse"
 
 module GitCommander
-  # @abstract Manages command line execution within the context of GitCommander
+  # Manages mapping commands and their arguments that are run from the command-line (via `git-cmd`)
+  # to their corresponding git-commander registered commands.
+  #
+  # @example Run a registered "start" command with a single argument
+  #   GitCommander::CLI.new.run ["start", "new-feature""]
+  #
   class CLI
     attr_reader :output, :registry
 
     # @param registry [GitCommander::Registry] (GitCommander::Registry.new) the
-    # command registry to use for matching available commands
+    #   command registry to use for matching available commands
     # @param output [IO] (STDOUT) the IO object you want to use to send output to when running commands
     def initialize(registry: GitCommander::Registry.new, output: STDOUT)
       @registry = registry
@@ -26,9 +31,7 @@ def run(args = ARGV)
       options = parse_command_options!(command, arguments)
       command.run options
     rescue Registry::CommandNotFound
-      GitCommander.logger.error <<~ERROR_LOG
-        #{command} not found in registry.  Available commands: #{registry.commands.keys.inspect}
-      ERROR_LOG
+      log_command_not_found(command)
 
       help
     rescue StandardError => e
@@ -40,7 +43,10 @@ def say(message)
       output.puts message
     end
 
-    # Parses ARGV for the provided git-cmd command name
+    # Parses an array of values (as ARGV would provide) for the provided git-cmd command name.
+    # The +arguments+ are run through Ruby's [OptionParser] for validation and
+    # then filtered through the +command+ to extract it's options with any
+    # default values.
     #
     # @param command [Command] the git-cmd command to parse the arguments for
     # @param arguments [Array] the command line arguments
@@ -74,6 +80,12 @@ def help
       say registry.commands.keys.join(", ")
     end
 
+    def log_command_not_found(command)
+      GitCommander.logger.error <<~ERROR_LOG
+        #{command} not found in registry.  Available commands: #{registry.commands.keys.inspect}
+      ERROR_LOG
+    end
+
     def configure_option_parser_for_command(command)
       valid_arguments_for_command = command.arguments.map { |arg| "[#{arg.name}]" }.join(" ")
 

lib/git_commander/command.rb

@@ -7,7 +7,7 @@
 require_relative "command_loader_options"
 
 module GitCommander
-  # @abstract Wraps domain logic for executing git-cmd commands
+  # Wraps domain logic for executing git-cmd Commands
   class Command
     include GitCommander::CommandLoaderOptions
 
@@ -16,20 +16,25 @@ class Command
 
     # @param name [String, Symbol] the name of the command
     # @param registry [GitCommander::Registry] (GitCommander::Registry.new) the
-    # command registry to use lookups
+    #   command registry to use lookups
     # @param options [Hash] the options to create the command with
+    #
     # @option options [String] :description (nil) a short description to use in the
-    # single line version of the command's help output
+    #   single line version of the command's help output
     # @option options [String] :summary (nil) the long-form description of the command
-    # to use in the command's help output
+    #   to use in the command's help output
     # @option options [IO] :output (STDOUT) the IO object you want to use to
-    # send outut from the command to
+    #   send outut from the command to
     # @option options [Array] :arguments an array of hashes describing the
-    # argument names and default values that can be supplied to the command
+    #   argument names and default values that can be supplied to the command
     # @option options [Array] :flags an array of hashes describing the
-    # flags and default values that can be supplied to the command
+    #   flags and default values that can be supplied to the command
     # @option options [Array] :switches an array of hashes describing the
-    # switches and default values that can be supplied to the command
+    #   switches and default values that can be supplied to the command
+    #
+    # @yieldparam [Array<Option>] run_options an Array of
+    #   Option instances defined from the above +options+
+    #
     def initialize(name, registry: nil, **options, &block)
       @name = name
       @description = options[:description]
@@ -43,16 +48,23 @@ def initialize(name, registry: nil, **options, &block)
 
     # Executes the block for the command with the provided run_options.
     #
-    # @param run_options
+    # @param run_options [Array<Option>] an array of Option(s) to pass to the {#block} of this Command
+    #
     def run(run_options = [])
       assign_option_values(run_options)
       Runner.new(self).run options.map(&:to_h).reduce(:merge)
     end
 
+    # Appends the +message+ to the Command's {#output}
+    #
+    # @param message [String] the string to append to the {#output}
+    #
     def say(message)
       output.puts message
     end
 
+    # Adds command-line help text to the {#output} of this Command
+    #
     def help
       say "NAME"
       say "    git-cmd #{name} – #{summary}"
@@ -63,10 +75,25 @@ def help
       options_help
     end
 
+    # Access to a unique Set of this Command's {#arguments}, {#flags}, and {#switches}
+    #
+    # @return [Set] a unique list of all options this command can accept
+    #
     def options
       Set.new(@arguments + @flags + @switches)
     end
 
+    # Add to this Command's {#arguments}, {#flags}, or {#switches}
+    #
+    # @param option_type [String, Symbol] the type of option to add
+    # @param options [Hash] the options to create the [Option] with
+    #
+    # @option options [String, Symbol] :name the name of the option to add
+    # @option options [Object] :default (nil) the default value of the Option
+    # @option options [String] :description (nil) a description of the Option to use in
+    #   help text output
+    # @option options [Object] :value (nil) the value on of the Option
+    #
     def add_option(option_type, options = {})
       case option_type.to_sym
       when :argument

lib/git_commander/plugins/git.rb

@@ -7,6 +7,7 @@
 
 CONFIG_FILE_PATH = "#{ENV["HOME"]}/.gitconfig.commander"
 
+# @private
 # Overrides Rugged::Repository#global_config so that we can use a custom config
 # file for all git-commander related configurations
 class RuggedRepositoryWithCustomConfig < SimpleDelegator