base.rb in inch-0.1.4

- old
+ new

@@ -1,33 +1,51 @@
 require 'optparse'
 
 module Inch
   module CLI
     module Command
+      # The classes in the Command::Options namespace are concerned with
+      # parsing of command-line arguments via OptionParser and converting
+      # these arguments into instance attributes.
+      #
+      # These attributes are then read and interpreted by the Command object.
+      #
+      # @see Inch::CLI::Command::Suggest
+      # @see Inch::CLI::Command::Options::Suggest
       module Options
         # Abstract base class for CLI options. Provides some helper methods for
-        # the option parser
+        # the option parser.
         #
+        # @abstract Subclass and override #set_options
         class Base
           include TraceHelper
           include YardoptsHelper
 
           class << self
+            # Creates an attribute with an optional default value
+            #
+            # @param name [Symbol] the name of the attribute
+            # @param default [nil] the default value of the attribute
+            # @return [void]
             def attribute(name, default = nil)
               define_method(name) do
                 instance_variable_get("@#{name}") || default
               end
               define_method("#{name}=") do |value|
                 instance_variable_set("@#{name}", value)
               end
             end
           end
 
-          attribute :usage, ""
-          attribute :paths, []
-          attribute :excluded, []
+          attribute :usage, ""    # usage description for the command
+          attribute :paths, []    # the paths of the to-be-analysed sources
+          attribute :excluded, [] # paths to be excluded from the analysis
 
+          # Parses the given +args+ "into" the current Options object
+          #
+          # @param args [Array<String>] command-line arguments
+          # @return [void]
           def parse(args)
             opts = OptionParser.new
             opts.banner = usage
 
             descriptions.each do |text|
@@ -36,42 +54,64 @@
 
             set_options(opts)
             parse_options(opts, args)
           end
 
+          # Sets all options for the current Options object
+          #
+          # @note Override to fill with individual options
+          #
+          # @param opts [OptionParser]
+          # @return [void]
           def set_options(opts)
             common_options(opts)
           end
 
-          # Override and fill with validations
+          # Verifies if the given options are valid
+          #
+          # @note Override to fill with validations
+          #
+          # @return [void]
           def verify
           end
 
           protected
 
-          # Override and fill with an array of descriptions that will be
-          # shown via the help switch.
+          # Returns an array of descriptions that will be shown via the
+          # +--help+ switch
+          #
+          # @note Override to fill with an array of descriptions
+          #
+          # @return [Array<String>]
           def descriptions
             []
           end
 
-          def description_arrows
+          # Returns a decriptive hint explaining the arrows used to represent
+          # code object priorities
+          #
+          # @return [String]
+          def description_hint_arrows
             arrows = Output::Base::PRIORITY_ARROWS.join(' ')
             "Arrows (#{arrows}) hint at the importance of the object " +
               "being documented."
           end
 
-          def description_grades
+          # Returns a decriptive hint explaining the arrows used to represent
+          # code object grades
+          #
+          # @return [String]
+          def description_hint_grades
             grades = Evaluation.new_score_ranges.map(&:grade)
             "School grades (#{grades.join(', ')}) are assigned and " +
               "displayed with each object."
           end
 
           DEFAULT_PATHS = ["{lib,app}/**/*.rb", "ext/**/*.c"]
 
-          # @yard_files is assigned by YardoptsHelper#parse_yardopts_options
           def get_paths(args)
+            # @yard_files is assigned by YardoptsHelper#parse_yardopts_options
             paths = @yard_files ? @yard_files : args.dup
             if paths.empty?
               DEFAULT_PATHS
             else
               paths
@@ -96,10 +136,14 @@
               trace opts
               exit
             end
           end
 
+          # Quits the application using `exit`
+          #
+          # @param msg [String,nil] optional, message to be displayed
+          # @return [void]
           def kill(msg = nil)
             warn usage
             warn msg.red unless msg.nil?
             warn "Try `--help' for more information."
             exit 1
@@ -116,9 +160,10 @@
             opts.parse!(args)
           rescue OptionParser::ParseError => err
             kill unrecognized_option(err)
           end
 
+          # Resets the command-line interface before each run
           def reset
             # color is enabled by default, can be turned of by switch --no-color
             Term::ANSIColor::coloring = true
           end
 