inch 0.1.3 → 0.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: ba6f65c0ae25dc579fbdef3eebccf8ada06f3d68
-  data.tar.gz: 8485e6393a208e59aa9d961ec67117bd657b6ba8
+  metadata.gz: 94f45218f025da4fe625a569967db6d85e9231a0
+  data.tar.gz: 481b2138c2c48c35e1ca884e078d8265e578e39b
 SHA512:
-  metadata.gz: 0f4ceeb144048f28a6ed9ca7f889be809a16a49c64e2ab7d572ecd59dee5b0442294c842d6da17adcd2ffe57c24f45ba4dbd3122fc65f53c3784d21a8c070899
-  data.tar.gz: 7ed146606d3c0604cd0c574d8120d960c1ed1982039e97b51e423192341d5f5ff8a60d261375ceb1576ae272f9ce0d754ea15de3af8c5510b8660c68e6a6b1d9
+  metadata.gz: 9d91370b78a36eb2a5fbd9541109a2b4bc5f97d6b67e3ce0de0cf9d8f22617821a9cd359dae170de49a6a80dde0e79e8437556e2a800c331d0bd0c45b96ab429
+  data.tar.gz: c47ca4717186e9ed78161c3db7baa2742c1aac96a8208f0cae4e08c2b81a75bafe42fd23f356680180165b2dbe94cf69855c59a1fdfa0d3683ec2d79bac37e2b

data/README.md

@@ -1,12 +1,10 @@
-# Inch
+# Inch [![Build Status](https://travis-ci.org/rrrene/inch.png)](https://travis-ci.org/rrrene/inch)
 
-[![Build Status](https://travis-ci.org/rrrene/inch.png)](https://travis-ci.org/rrrene/inch)
+Take a look at the project page for an [introduction with screenshots (live and in full color)](http://rrrene.github.io/inch/).
 
-Inch is a documentation measurement tool for Ruby, based on
-[YARD](http://yardoc.org/).
+Inch is a documentation measurement tool for the Ruby programming language
+that gives you hints where to improve your docs. One Inch at a time.
 
-It does not measure *coverage*, but gives you hints where to improve your
-docs. One Inch at a time.
 
 
 ## Installation
@@ -24,6 +22,7 @@ Or install it yourself as:
     $ gem install inch
 
 
+
 ## Usage
 
 To run Inch, simply type

data/TODOS.md

@@ -7,3 +7,10 @@
   visibility options
 * Add support for multiple signatures for methods
   (realized via the @overload tag in YARD)
+* Think about implicit cases in terms of evaluation:
+  * constructors without docstring/return_type
+  * ?-methods with a return description
+* Think about limiting the number of `B`-objects in `inch suggest`
+  `inch suggest` shows too many `B`s even though there are still undocumented
+  objects in the codebase. this becomes a problem, when one thinks of `B` as
+  "good enough", which Inch itself suggests.

data/lib/inch/cli/arguments.rb

@@ -1,8 +1,21 @@
 module Inch
   module CLI
+    # Arguments parses given command-line arguments into the categories
+    # +files+, +object_names+, and +switches+.
+    #
+    # @example
+    #
+    #   args = ["lib/*.rb", "README", "Foo", "Foo::Bar", "--color", "--all"]
+    #   arguments = ::Inch::CLI::Arguments.new(args)
+    #
+    #   arguments.files         # => ["lib/*.rb", "README"]
+    #   arguments.object_names  # => ["Foo", "Foo::Bar"]
+    #   arguments.switches      # => ["--color", "--all"]
+    #
     class Arguments
       attr_reader :files, :object_names, :switches
 
+      # @param args [Array<String>]
       def initialize(args)
         @files = []
         @object_names = []
@@ -12,8 +25,10 @@ module Inch
 
       private
 
+      # @param args [Array<String>]
+      # @return [void]
       def parse(args)
-        if first_non_file = args.find_index { |e| !file_or_glob?(e) }
+        if first_non_file = args.find_index { |e| !glob_or_file?(e) }
           @files = args[0...first_non_file]
           rest = args[first_non_file..-1]
           if first_switch = rest.find_index { |e| switch?(e) }
@@ -29,7 +44,17 @@ module Inch
         end
       end
 
-      def file_or_glob?(f)
+      # Returns +true+ if a given String is a glob or a filename
+      #
+      # @example
+      #
+      #   glob_or_file?("lib/*.rb") # => true
+      #   glob_or_file?("README")   # => true
+      #   glob_or_file?("--help")   # => false
+      #
+      # @param f [String]
+      # @return [Boolean]
+      def glob_or_file?(f)
         if f =~ /[\*\{]/
           true
         else
@@ -37,6 +62,15 @@ module Inch
         end
       end
 
+      # Returns +true+ if a given String is an option switch
+      #
+      # @example
+      #
+      #   switch?("--help")   # => true
+      #   switch?("README")   # => false
+      #
+      # @param f [String]
+      # @return [Boolean]
       def switch?(f)
         f =~ /^\-/
       end

data/lib/inch/cli/command/base.rb

@@ -1,19 +1,49 @@
 module Inch
   module CLI
+    # The classes in the Command namespace are controller objects for the
+    # command-line interface.
+    #
+    # A Command object is run via the class method +run+ (see {Base.run}).
+    # Its parameters are the command-line arguments (typically ARGV).
+    #
+    # A Command object utilizes an {Options} object to interpret the command-
+    # line arguments, then processes files and/or objects and finally uses an
+    # {Output} object to present the results to the user.
+    #
+    #
+    # To create a new command +Foo+ you must first subclass any of
+    #
+    # * Command::Base
+    # * Command::BaseList
+    # * Command::BaseObject
+    #
+    # Then you have to subclass Options and Output
+    # classes as well, to finally get something like this:
+    #
+    # * Command::Foo
+    # * Command::Options::Foo
+    # * Command::Output::Foo
+    #
+    # For an example, take a look at the Suggest command.
+    #
+    # @see Inch::CLI::Command::Suggest
+    # @see Inch::CLI::Command::Options::Suggest
+    # @see Inch::CLI::Command::Output::Suggest
     module Command
-      # Abstract base class for CLI utilities. Provides some helper methods for
-      # the option parser
+      # Abstract base class for CLI controller objects
       #
-      # @abstract
-      # @note This was adapted from YARD.
-      # @see https://github.com/lsegal/yard/blob/master/lib/yard/cli/command.rb
+      # @abstract Subclass and override #run to implement a new command
+      # @note This was adapted from YARD
+      #   https://github.com/lsegal/yard/blob/master/lib/yard/cli/command.rb
       class Base
         include TraceHelper
 
-        attr_reader :source_parser
+        attr_reader :source_parser # @return [SourceParser]
 
-        # Helper method to run the utility on an instance.
+        # Helper method to run an instance with the given +args+
+        #
         # @see #run
+        # @return [Command::Base] the instance that ran
         def self.run(*args)
           command = new
           command.run(*args)
@@ -27,13 +57,15 @@ module Inch
         end
 
         # Returns a description of the command
+        #
         # @return [String]
         def description
           ""
         end
 
         # Returns the name of the command by which it is referenced
-        # in the command list.
+        # in the command list
+        #
         # @return [String]
         def name
           CommandParser.commands.each do |name, klass|
@@ -41,7 +73,17 @@ module Inch
           end
         end
 
+        # Runs the command with the given +args+
+        #
+        # @abstract
+        # @note Override with implementation
+        # @param *args [Array<String>]
+        def run(*args)
+          raise NotImplementedError
+        end
+
         # Returns a description of the command's usage pattern
+        #
         # @return [String]
         def usage
           "Usage: inch #{name} [options]"
@@ -49,6 +91,12 @@ module Inch
 
         private
 
+        # Returns the source parser against the given +paths+, while
+        # excluding all paths given in +excluded+
+        #
+        # @param paths [Array<String>]
+        # @param excluded [Array<String>]
+        # @return [void]
         def run_source_parser(paths, excluded)
           debug "Parsing:\n" \
                 "  files:    #{paths.inspect}\n" \

data/lib/inch/cli/command/base_list.rb

@@ -1,6 +1,14 @@
 module Inch
   module CLI
     module Command
+      # Base class for Command objects concerned with lists of objects
+      #
+      # Commands subclassing from this class are called with an optional list
+      # of paths in the form:
+      #
+      #   $ inch COMMAND [paths] [options]
+      #
+      # @abstract
       class BaseList < Base
         attr_writer :objects
 
@@ -12,7 +20,7 @@ module Inch
         # Prepares the list of objects and ranges, parsing arguments and
         # running the source parser.
         #
-        # @param [Array<String>] args the list of arguments.
+        # @param *args [Array<String>] the list of arguments.
         # @return [void]
         def prepare_list(*args)
           @options.parse(args)
@@ -25,7 +33,7 @@ module Inch
         private
 
         # Assigns the objects returned by {#objects} to the score ranges in
-        # @ranges based on their score
+        # +@ranges+ based on their score
         #
         def assign_objects_to_ranges
           @ranges.each do |range|
@@ -34,6 +42,9 @@ module Inch
           end
         end
 
+        # Filters the +@objects+ based on the settings in +@options+
+        #
+        # @return [void]
         def filter_objects
           if @options.namespaces == :only
             self.objects = objects.select(&:namespace?)
@@ -48,7 +59,7 @@ module Inch
             self.objects = objects.reject(&:undocumented?)
           end
           if @options.depth
-            self.objects = objects.select { |o| o.depth <= @depth }
+            self.objects = objects.select { |o| o.depth <= @options.depth }
           end
           self.objects = objects.select do |o|
             @options.visibility.include?(o.visibility)
@@ -60,10 +71,13 @@ module Inch
           end
         end
 
+        # @return [Array<CodeObject::Proxy::Base>]
         def objects
           @objects ||= sort_by_priority(source_parser.all_objects)
         end
 
+        # @param objects [Array<CodeObject::Proxy::Base>]
+        # @return [Array<CodeObject::Proxy::Base>]
         def sort_by_priority(objects)
           objects.sort_by do |o|
             [o.priority, o.score, o.path.size]

data/lib/inch/cli/command/base_object.rb

@@ -1,6 +1,15 @@
 module Inch
   module CLI
     module Command
+      # Base class for Command objects concerned with clearly specified
+      # objects.
+      #
+      # Commands subclassing from this class are called with a list of object
+      # names (most commonly only one) in the form:
+      #
+      #   $ inch COMMAND [paths] OBJECT_NAME [, OBJECT_NAME2, ...] [options]
+      #
+      # @abstract
       class BaseObject < Base
         attr_accessor :object, :objects
 
@@ -9,23 +18,27 @@ module Inch
           @ranges = Evaluation.new_score_ranges
         end
 
-        # Prepares the (list of) objects, parsing arguments and
+        # Prepares the given objects, parsing arguments and
         # running the source parser.
         #
-        # @param [Array<String>] args the list of arguments.
+        # @param *args [Array<String>] the list of arguments
         # @return [void]
         def prepare_objects(*args)
           @options.parse(args)
           @options.verify
           run_source_parser(@options.paths, @options.excluded)
 
-          self.objects = find_object_names(@options.object_names)
+          self.objects = find_objects_with_names(@options.object_names)
           self.object = @objects.first
         end
 
         private
 
-        def find_object_names(object_names)
+        # Returns all objects matching the given +object_names+
+        #
+        # @param object_names [Array<String>]
+        # @return [Array<CodeObject::Proxy::Base>]
+        def find_objects_with_names(object_names)
           object_names.map do |object_name|
             if object = source_parser.find_object(object_name)
               object

data/lib/inch/cli/command/options/base.rb

@@ -3,15 +3,29 @@ 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
@@ -22,10 +36,14 @@ module Inch
             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
@@ -38,29 +56,51 @@ module Inch
             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."
@@ -68,8 +108,8 @@ module Inch
 
           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
@@ -98,6 +138,10 @@ module Inch
             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?
@@ -118,6 +162,7 @@ module Inch
             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