inch 0.1.3 → 0.1.4

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

@@ -2,13 +2,18 @@ module Inch
   module CLI
     module Command
       module Options
+        # Abstract base class for CLI options concerning lists of objects
+        #
+        # @abstract Subclass and override #set_options
         class BaseList < Base
-          attribute :full, false
+          attribute :show_all, false
           attribute :visibility, [:public, :protected]
           attribute :namespaces
           attribute :undocumented
           attribute :depth
 
+          alias :show_all? :show_all
+
           def parse(args)
             opts = OptionParser.new
             opts.banner = usage
@@ -33,12 +38,17 @@ module Inch
 
           protected
 
+
+          # Sets all list related options for the current Options object
+          #
+          # @param opts [OptionParser]
+          # @return [void]
           def list_options(opts)
             opts.separator ""
             opts.separator "List options:"
 
             opts.on("--all", "Show all objects in the output") do
-              @full = true
+              @show_all = true
             end
 
             opts.on("--only-namespaces", "Only show namespaces (classes, modules)") do
@@ -70,11 +80,21 @@ module Inch
             end
           end
 
-          def set_visibility(_visibility, true_or_false)
+          # Sets the visibility of a given +kind+ of objects
+          #
+          # @example
+          #   set_visibility :private, false
+          #   set_visibility :protected, true
+          #
+          # @param kind [Symbol] +:public+, +:protected:, or +:private+
+          # @param true_or_false [Boolean]
+          # @return [void]
+          def set_visibility(kind, true_or_false)
+            @visibility ||= visibility.dup # initialize with attribute default
             if true_or_false
-              visibility.push(_visibility)
+              @visibility.push(kind)
             else
-              visibility.delete(_visibility)
+              @visibility.delete(kind)
             end
           end
         end

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

@@ -29,8 +29,6 @@ module Inch
 
           private
 
-          # TODO: really check the last parameters if they are globs, files
-          # or switches and find the object_name(s) that way
           def parse_object_names(args)
             arguments = Arguments.new(args)
             object_names = arguments.object_names

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

@@ -12,8 +12,8 @@ module Inch
               "",
               "Example: " + "$ inch list lib/**/*.rb --all".cyan,
               "",
-              description_grades,
-              description_arrows
+              description_hint_grades,
+              description_hint_arrows
             ]
           end
 

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

@@ -10,8 +10,8 @@ module Inch
               "Example: " + "$ inch show lib/**/*.rb Foo::Bar#initialize".cyan,
               "",
               "Shows one or more objects in detail.",
-              description_grades,
-              description_arrows
+              description_hint_grades,
+              description_hint_arrows
             ]
           end
 

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

@@ -28,8 +28,8 @@ module Inch
               "",
               "Example: " + "$ inch suggest lib/**/*.rb --pedantic".cyan,
               "",
-              description_grades,
-              description_arrows
+              description_hint_grades,
+              description_hint_arrows
             ]
           end
 

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

@@ -3,9 +3,18 @@ require 'optparse'
 module Inch
   module CLI
     module Command
+      # The classes in the Command::Output namespace act as presenter
+      # objects to the classes in the Command namespace.
+      #
+      # They are given all the objects and data they are supposed
+      # to display to the user. They do not filter the received data.
+      #
+      # @see Inch::CLI::Command::Suggest
+      # @see Inch::CLI::Command::Output::Suggest
       module Output
         # Abstract base class for CLI output
         #
+        # @abstract
         class Base
           include TraceHelper
 

data/lib/inch/cli/command/output/console.rb

@@ -16,6 +16,10 @@ module Inch
           COLOR = :color198     # magenta-ish
           BG_COLOR = :color207  # magenta-ish
 
+          # @param options [Options::Console]
+          # @param object [CodeObject::Proxy::Base]
+          # @param objects [Array<CodeObject::Proxy::Base>]
+          # @param source_parser [SourceParser]
           def initialize(options, object, objects, source_parser)
             @options = options
             @object = object

data/lib/inch/cli/command/output/inspect.rb

@@ -91,7 +91,7 @@ module Inch
 
           def print_doc_info(o)
             if o.nodoc?
-              echo "The object was tagged not to documented.".yellow
+              echo "The object was tagged not to be documented.".yellow
             else
               echo "Docstring".ljust(LJUST) + "#{o.has_doc? ? 'Yes' : 'No text'}"
               if o.method?
@@ -107,7 +107,7 @@ module Inch
 
           def print_namespace_info(o)
             if o.namespace?
-              echo "Children (height: #{o.height}):"
+              echo "Children:"
               o.children.each do |child|
                 echo "+ " + child.path.color(COLOR)
               end

data/lib/inch/cli/command/output/list.rb

@@ -37,7 +37,7 @@ module Inch
           end
 
           def display_range(range)
-            display_count = @options.full ? range.objects.size : PER_RANGE
+            display_count = @options.show_all? ? range.objects.size : PER_RANGE
             list = range.objects[0...display_count]
             list.each do |o|
               echo range.color, result(o, range.color)

data/lib/inch/cli/command_parser.rb

@@ -1,12 +1,34 @@
-# This was adapted from https://github.com/lsegal/yard/blob/master/lib/yard/cli/command_parser.rb
 module Inch
   module CLI
-    # This class parses a command name out of the +inch+ CLI command and calls
-    # that command in the form:
+    # CommandParser parses a command-line arguments to decide which Command to run.
+    #
+    # The basic form translates this shell command
     #
     #   $ inch command_name [options]
     #
-    # If no command_name is specified, the {default_command} will be used.
+    # into a method call on the corresponding Command class.
+    #
+    # Some examples:
+    #
+    #   $ inch
+    #   # >>> Command::Suggest.new.run()
+    #
+    #   $ inch --pedantic
+    #   # >>> Command::Suggest.new.run("--pedantic")
+    #
+    # As you can see, if no command_name is given, the {default_command}
+    # will be used.
+    #
+    #   $ inch list --all
+    #   # >>> Command::List.new.run("--all")
+    #
+    # If a command_name is found to match a Command, that Command will be
+    # used.
+    #
+    #   $ inch --help
+    #   # >>> CommandParser#list_commands
+    #
+    # The +--help+ switch is an exception and lists all available commands.
     #
     class CommandParser
       include TraceHelper
@@ -38,13 +60,9 @@ module Inch
         new.run(*args)
       end
 
-      def initialize
-        #log.show_backtraces = false
-      end
-
       # Runs the {Command} object matching the command name of the first
       # argument.
-      # @return [void]
+      # @return [Command::Base]
       def run(*args)
         if ['--help', '-h'].include?(args.join)
           list_commands
@@ -69,6 +87,9 @@ module Inch
         end
       end
 
+      # Runs the {Command} object matching the command name of the first
+      # argument.
+      # @return [Command::Base]
       def run_command(*args)
         if args.empty?
           command_name = self.class.default_command

data/lib/inch/code_object/nodoc_helper.rb

@@ -60,21 +60,42 @@ module Inch
         end
       end
 
+      # Returns all lines in all files declaring the object
+      #
+      # @example
+      #   declarations # => ["class Base # :nodoc:", "class Foo < Base"]
+      #
+      # @return [Array<String>]
       def declarations
         @declarations ||= files.map do |(filename, line_no)|
           get_line_no(filename, line_no)
         end
       end
 
+      # Returns all files declaring the object in the form of an Array of
+      # Arrays containing the filename and the line number of their
+      # declaration.
+      #
+      # @example
+      #   files # => [["lib/inch.rb", 3],
+      #                ["lib/inch/cli.rb", 1],
+      #                 ["lib/inch/version.rb", 1],
+      #
+      # @return [Array<Array(String, Fixnum)>]
       def files
         object.files
       rescue YARD::CodeObjects::ProxyMethodError
         []
       end
 
-      def get_line_no(filename, n)
+      # Returns a +line_number+ from a file
+      #
+      # @param filename [String]
+      # @param line_number [Fixnum]
+      # @return [String]
+      def get_line_no(filename, line_number)
         f = File.open(filename)
-        n.times{f.gets}
+        line_number.times{f.gets}
         result = $_
         f.close
         result

data/lib/inch/code_object/proxy.rb

@@ -1,7 +1,14 @@
 module Inch
   module CodeObject
+    # CodeObject::Proxy object represent code objects in the analaysed
+    # codebase.
+    #
     module Proxy
       class << self
+        # Returns a Proxy object for the given +code_object+
+        #
+        # @param code_object [YARD::CodeObject]
+        # @return [CodeObject::Proxy::Base]
         def for(code_object)
           @cache ||= {}
           if proxy_object = @cache[cache_key(code_object)]
@@ -13,6 +20,10 @@ module Inch
 
         private
 
+        # Returns a Proxy class for the given +code_object+
+        #
+        # @param code_object [YARD::CodeObject]
+        # @return [Class]
         def class_for(code_object)
           class_name = code_object.class.to_s.split('::').last
           eval("::Inch::CodeObject::Proxy::#{class_name}")
@@ -20,8 +31,11 @@ module Inch
           Base
         end
 
-        def cache_key(o)
-          o.path
+        # Returns a cache key for the given +code_object+
+        #
+        # @return [String]
+        def cache_key(code_object)
+          code_object.path
         end
       end
     end

data/lib/inch/code_object/proxy/base.rb

@@ -3,6 +3,7 @@ require 'forwardable'
 module Inch
   module CodeObject
     module Proxy
+      # @abstract
       class Base
         extend Forwardable
         include NodocHelper
@@ -113,28 +114,6 @@ module Inch
           end
         end
 
-        # In the following example, the height of +Foo+ is 3
-        # (the height of the top-level is 4):
-        #
-        #   Foo::Bar::Baz#initialize
-        #    ^    ^    ^      ^
-        #    0 >> 1 >> 2  >>  3
-        #
-        # +height+ answers the question "how many layers of code objects are
-        # underneath this one?"
-        #
-        # @param i [Fixnum] a counter for recursive method calls
-        # @return [Fixnum] the height of the object in terms of namespace
-        def height(i = 0)
-          if children && !children.empty?
-            children.map do |child|
-              child.height(i+1)
-            end.max
-          else
-            i
-          end
-        end
-
         # @return [Boolean] +true+ if the object represents a method
         def method?
           false
@@ -186,7 +165,7 @@ module Inch
         private
 
         def multi_code_examples?(text)
-          text =~ /\b#{Regexp.escape(name)}[^_0-9\!\?]/
+          text.scan(/\b(#{Regexp.escape(name)})[^_0-9\!\?]/m).size > 1
         end
       end
     end

data/lib/inch/code_object/proxy/method_object.rb

@@ -1,6 +1,7 @@
 module Inch
   module CodeObject
     module Proxy
+      # Proxy class for methods
       class MethodObject < Base
         def comment_and_abbrev_source
           comments.join('') + abbrev_source

data/lib/inch/code_object/proxy/method_parameter_object.rb

@@ -1,8 +1,9 @@
 module Inch
   module CodeObject
     module Proxy
+      # Proxy class for method parameters
       class MethodParameterObject
-        attr_reader :name
+        attr_reader :name # @return [String]
 
         # @param method [Inch::CodeObject::Proxy::MethodObject] the method the parameter belongs_to
         # @param name [String] the name of the parameter
@@ -17,6 +18,8 @@ module Inch
 
         BAD_NAME_EXCEPTIONS = %w(id)
         BAD_NAME_THRESHOLD = 3
+
+        # @return [Boolean] +true+ if the name of the parameter is uncommunicative
         def bad_name?
           return false if BAD_NAME_EXCEPTIONS.include?(name)
           name.size < BAD_NAME_THRESHOLD || name =~ /[0-9]$/

data/lib/inch/evaluation.rb

@@ -9,8 +9,6 @@ module Inch
     def self.class_for(code_object)
       class_name = code_object.class.to_s.split('::').last
       eval(class_name)
-    rescue
-      Base
     end
   end
 end

data/lib/inch/evaluation/base.rb

@@ -1,5 +1,6 @@
 module Inch
   module Evaluation
+    # @abstract
     class Base
       extend Forwardable
 

data/lib/inch/evaluation/constant_object.rb

@@ -22,9 +22,6 @@ module Inch
         if object.public?
           add_role Role::Constant::Public.new(object)
         end
-        if object.protected?
-          add_role Role::Constant::Protected.new(object)
-        end
         if object.private?
           add_role Role::Constant::Private.new(object)
         end

data/lib/inch/evaluation/file.rb

@@ -42,10 +42,6 @@ module Inch
         objects.map(&:priority)
       end
 
-      def scores
-        objects.map(&:score)
-      end
-
       def median(sorted_list)
         index = (sorted_list.size / 2).round
         sorted_list[index]

data/lib/inch/evaluation/namespace_object.rb

@@ -28,15 +28,9 @@ module Inch
         if object.in_root?
           add_role Role::Object::InRoot.new(object)
         end
-        if object.public?
+        if object.public? # this is always true for classes and modules
           add_role Role::Object::Public.new(object)
         end
-        if object.protected?
-          add_role Role::Object::Protected.new(object)
-        end
-        if object.private?
-          add_role Role::Object::Private.new(object)
-        end
 
         eval_core
       end