inch 0.2.2 → 0.2.3

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

@@ -16,10 +16,10 @@ module Inch
               [203, 203, 204, 204, 205, 206, 207]
             ].flatten.map { |s| :"color#{s}" }
 
-          def initialize(options, objects, ranges)
+          def initialize(options, objects, grade_lists)
             @options = options
             @objects = objects
-            @ranges = ranges
+            @grade_lists = grade_lists
 
             method("display_#{@options.format}").call
           end
@@ -27,19 +27,23 @@ module Inch
           private
 
           def display_text
-            display_text_grades
-            display_text_priorities
+            print_grades
+            print_grades_by_priority
+            print_priorities
             puts
             puts 'Try `--format json|yaml` for raw numbers.'.dark
           end
 
-          def display_text_grades
-            sparkline = ranges_sparkline(@ranges).to_s(' ')
+          def print_grades
+            sparkline = grade_lists_sparkline(@grade_lists).to_s(' ')
             puts
             puts 'Grade distribution: (undocumented, C, B, A)'
             puts
             puts "  Overall:  #{sparkline}  #{objects.size.to_s.rjust(5)} objects"
             puts
+          end
+
+          def print_grades_by_priority
             puts 'Grade distribution by priority:'
             puts
             PRIORITY_MAP.each do |priority_range, arrow|
@@ -51,25 +55,29 @@ module Inch
             end
           end
 
-          def display_text_priorities
+          def print_grade_list(grade_list)
+            list = grade_list.objects.map(&:priority)
+
+            priorities = {}
+            (-7..7).each do |key|
+              priorities[key.to_s] = list.select { |p| p == key }.size
+            end
+
+            sparkline = Sparkr::Sparkline.new(priorities.values)
+            sparkline.format do |tick, count, index|
+              tick.color( PRIORITY_COLORS[index] )
+            end
+            puts "  #{grade_list.grade}:  " + sparkline.to_s(' ') +
+                  " #{grade_list.objects.size.to_s.rjust(5)} objects"
+            puts
+          end
+
+          def print_priorities
             puts "Priority distribution in grades: (low to high)"
             puts
             puts "      #{PRIORITY_MAP.values.reverse.join('      ')}"
-            @ranges.reverse.each do |range|
-              list = range.objects.map(&:priority)
-
-              priorities = {}
-              (-7..7).each do |key|
-                priorities[key.to_s] = list.select { |p| p == key }.size
-              end
-
-              sparkline = Sparkr::Sparkline.new(priorities.values)
-              sparkline.format do |tick, count, index|
-                tick.color( PRIORITY_COLORS[index] )
-              end
-              puts "  #{range.grade}:  " + sparkline.to_s(' ') +
-                    " #{range.objects.size.to_s.rjust(5)} objects"
-              puts
+            @grade_lists.reverse.each do |grade_list|
+              print_grade_list(grade_list)
             end
           end
 
@@ -82,25 +90,36 @@ module Inch
           end
 
           def stats_hash
-            hash = {}
+            {
+              'grade_lists' => __grade_lists,
+              'scores' => __scores,
+              'priorities' => __priorities
+            }
+          end
 
-            hash['ranges'] = {}
-            @ranges.each do |r|
-              hash['ranges'][r.grade.to_s] = r.objects.size
+          def __grade_lists
+            hash = {}
+            @grade_lists.each do |r|
+              hash[r.grade.to_s] = r.objects.size
             end
+            hash
+          end
 
-            hash['scores'] = {}
+          def __scores
+            hash = {}
             @objects.sort_by(&:score).each do |o|
-              hash['scores'][o.score.to_i] ||= 0
-              hash['scores'][o.score.to_i] += 1
+              hash[o.score.to_i] ||= 0
+              hash[o.score.to_i] += 1
             end
+            hash
+          end
 
-            hash['priorities'] = {}
+          def __priorities
+            hash = {}
             @objects.sort_by(&:priority).each do |o|
-              hash['priorities'][o.priority.to_i] ||= 0
-              hash['priorities'][o.priority.to_i] += 1
+              hash[o.priority.to_i] ||= 0
+              hash[o.priority.to_i] += 1
             end
-
             hash
           end
 

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

@@ -20,13 +20,13 @@ module Inch
           # @param options [Command::Options::Suggest]
           # @param objects_to_display [Array<CodeObject::Proxy::Base>]
           # @param relevant_objects [Array<CodeObject::Proxy::Base>] the objects meeting the criteria defined in +options+
-          # @param ranges [Array<Evaluation::ScoreRange>]
+          # @param grade_lists [Array<Evaluation::GradeList>]
           # @param files [Array<Evaluation::File>]
-          def initialize(options, objects_to_display, relevant_objects, ranges, files)
+          def initialize(options, objects_to_display, relevant_objects, grade_lists, files)
             @options = options
             @objects = objects_to_display
             @relevant_objects = relevant_objects
-            @ranges = ranges
+            @grade_lists = grade_lists
             @files = files
 
             if objects.empty?
@@ -70,11 +70,11 @@ module Inch
 
           def display_list
             @options.grades_to_display.map do |grade|
-              r = range(grade)
+              r = grade_list(grade)
               grade_objects = objects.select { |o| o.grade == r.grade }
               unless grade_objects.empty?
                 trace
-                trace_header(RANGE_LABELS[r.grade], r.color, r.bg_color)
+                trace_header(RANGE_LABELS[r.grade.to_sym], r.color, r.bg_color)
                 grade_objects.each do |o|
                   grade = o.grade.to_s.ljust(2).color(r.color)
                   priority = o.priority
@@ -94,8 +94,8 @@ module Inch
             end.compact
           end
 
-          def range(grade)
-            @ranges.detect { |r| r.grade == grade }
+          def grade_list(grade_symbol)
+            @grade_lists.detect { |r| r.grade.to_sym == grade_symbol }
           end
         end
       end

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

@@ -1,7 +1,12 @@
+require_relative 'options/show'
+require_relative 'output/show'
+
 module Inch
   module CLI
     module Command
       class Show < BaseObject
+        register_command_as :show
+
         def description
           'Shows an object with its results'
         end

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

@@ -1,7 +1,12 @@
+require_relative 'options/stats'
+require_relative 'output/stats'
+
 module Inch
   module CLI
     module Command
       class Stats < List
+        register_command_as :stats
+
         def description
           'Lists all objects with their results'
         end
@@ -12,7 +17,7 @@ module Inch
 
         def run(*args)
           prepare_list(*args)
-          Output::Stats.new(@options, objects, @ranges)
+          Output::Stats.new(@options, objects, @grade_lists)
         end
       end
     end

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

@@ -1,7 +1,12 @@
+require_relative 'options/suggest'
+require_relative 'output/suggest'
+
 module Inch
   module CLI
     module Command
       class Suggest < List
+        register_command_as :suggest, true
+
         def description
           'Suggests some objects to be doucmented (better)'
         end
@@ -17,29 +22,43 @@ module Inch
         # @return [void]
         def run(*args)
           prepare_list(*args)
-          Output::Suggest.new(@options, objects_to_display, relevant_objects, @ranges, files)
+          Output::Suggest.new(@options, objects_to_display, relevant_objects, @grade_lists, files)
+        end
+
+        private
+
+        # @return [Fixnum] how many objects should be displayed in the output
+        def object_count
+          @options.object_count
+        end
+
+        # @return [Array<Fixnum>]
+        #   how many objects of each grade should be displayed in the output
+        def object_list_counts
+          @options.grade_weights.map { |w| w * object_count }
         end
 
+        # @return [Array] the objects that should be displayed in the output
         def objects_to_display
           @objects_to_display ||= filter_objects_to_display
         end
 
+        # @return [Array] the objects that should be displayed in the output
         def filter_objects_to_display
-          list = []
+          grade_list = []
           @options.grades_to_display.map do |grade|
-            r = range(grade)
+            r = grade_list(grade)
             arr = select_by_priority(r.objects, @options.object_min_priority)
             arr = arr.select { |o| o.score <= @options.object_max_score }
-            list.concat arr
+            grade_list << arr
           end
 
-          list = sort_by_priority(list)
+          weighted_list = WeightedList.new(grade_list, object_list_counts)
+
+          list = sort_by_priority(weighted_list.to_a.flatten)
 
-          if list.size > @options.object_count
-            list = list[0...@options.object_count]
-          elsif list.size < @options.object_count
-            # should we add objects with lower priority to fill out the
-            # requested count?
+          if list.size > object_count
+            list = list[0...object_count]
           end
           list
         end
@@ -78,8 +97,8 @@ module Inch
           objects.map(&:grade).uniq
         end
 
-        def range(grade)
-          @ranges.detect { |r| r.grade == grade }
+        def grade_list(grade_symbol)
+          @grade_lists.detect { |r| r.grade.to_sym == grade_symbol }
         end
 
         def relevant_objects

data/lib/inch/cli/command.rb

@@ -2,22 +2,15 @@ require_relative 'command/base'
 require_relative 'command/base_list'
 require_relative 'command/base_object'
 
-require_relative 'command/list'
-require_relative 'command/show'
-require_relative 'command/stats'
-require_relative 'command/suggest'
-
 require_relative 'command/options/base'
 require_relative 'command/options/base_list'
 require_relative 'command/options/base_object'
 
-require_relative 'command/options/list'
-require_relative 'command/options/show'
-require_relative 'command/options/stats'
-require_relative 'command/options/suggest'
-
 require_relative 'command/output/base'
-require_relative 'command/output/list'
-require_relative 'command/output/show'
-require_relative 'command/output/stats'
-require_relative 'command/output/suggest'
+
+require_relative 'command_parser'
+
+require_relative 'command/list'
+require_relative 'command/show'
+require_relative 'command/stats'
+require_relative 'command/suggest'

data/lib/inch/cli/command_parser.rb

@@ -43,15 +43,8 @@ module Inch
         attr_accessor :default_command
       end
 
-      self.commands = {
-        :list => Command::List,
-        :show => Command::Show,
-        :stats => Command::Stats,
-        :suggest => Command::Suggest,
-      }
-
-      self.default_command = :suggest
-
+      self.commands = {}
+      
       # Convenience method to create a new CommandParser and call {#run}
       # @return (see #run)
       def self.run(*args)

data/lib/inch/cli/sparkline_helper.rb

@@ -1,28 +1,28 @@
 module Inch
   module CLI
     module SparklineHelper
-      def ranges_sparkline(_ranges)
-        ranges = _ranges.reverse
-        list = ranges.map { |r| r.objects.size }
-        sparkline = Sparkr::Sparkline.new(list)
-        sparkline.format do |tick, count, index|
-          t = tick.color(ranges[index].color)
-          index == 0 ? t + ' ' : t
-        end
+      def grade_lists_sparkline(_grade_lists)
+        grade_lists = _grade_lists.reverse
+        list = grade_lists.map { |r| r.objects.size }
+        __sparkline(list, grade_lists)
       end
 
       def grades_sparkline(objects)
         grades = {}
         objects.each do |o|
-          grades[o.grade] ||= 0
-          grades[o.grade] += 1
+          grades[o.grade.to_sym] ||= 0
+          grades[o.grade.to_sym] += 1
         end
-        ranges = Evaluation.new_score_ranges.reverse
-        order = ranges.map(&:grade)
+        grade_lists = Evaluation.new_grade_lists.reverse
+        order = grade_lists.map(&:to_sym)
         list = order.map { |g| grades[g] }
+        __sparkline(list, grade_lists)
+      end
+
+      def __sparkline(list, grade_lists)
         sparkline = Sparkr::Sparkline.new(list)
         sparkline.format do |tick, count, index|
-          t = tick.color(ranges[index].color)
+          t = tick.color(grade_lists[index].color)
           index == 0 ? t + ' ' : t
         end
       end

data/lib/inch/cli/weighted_list.rb

@@ -0,0 +1,85 @@
+module Inch
+  module CLI
+    class WeightedList
+      # Trims down a list of object lists to given sizes.
+      # If there are not enough objects in any particular tier,
+      # they are filled up from the tier below/above.
+      #
+      # @example
+      #
+      #   list = [
+      #     [:B1, :B2],
+      #     [:C1, :C2, :C3, :C4, :C5, :C6, :C7, :C8, :C9, :C10],
+      #     [:U1, :U2, :U3, :U4, :U5, :U6, :U7, :U8, :U9, :U10]
+      #   ]
+      #   counts = [4, 8, 8]
+      #
+      # This means there should be 4 +:B+s, 8 +:C+s, and 8 +:U+s in the
+      # resulting list. But we only have 2 +:B+s, so the result is filled up
+      # with +:U+s:
+      #
+      #   WeightedList.new(list, counts).to_a
+      #   # => [
+      #       [:B1, :B2],
+      #       [:C1, :C2, :C3, :C4, :C5, :C6, :C7, :C8],
+      #       [:U1, :U2, :U3, :U4, :U5, :U6, :U7, :U8, :U9, :U10]
+      #     ]
+      #
+      # @param list_of_lists [Array<Array>]
+      # @param counts [Array<Fixnum>]
+      def initialize(list_of_lists, counts)
+        @original = list_of_lists
+        @max_counts = counts
+        compute_list
+      end
+
+      # @return [Array]
+      def to_a
+        @list
+      end
+
+      private
+
+      def compute_list
+        @list = init_empty_list(@original.size)
+        still_missing = fill_list_with_predefined_sizes
+
+        # all sublists are now filled up to their max capacity but we might
+        # have missed some objects (+still_missing+), because there weren't
+        # enough
+
+        @original.reverse_each.with_index do |sublist, rear_index|
+          if still_missing > 0
+            index = @original.size - rear_index - 1
+            present_count = @max_counts[index]
+            not_yet_in_list = sublist[present_count..-1]
+            if not_yet_in_list
+              put_in_list = not_yet_in_list[0...still_missing]
+              @list[index].concat put_in_list
+              still_missing -= put_in_list.size
+            end
+          end
+        end
+      end
+
+      def init_empty_list(sublist_count)
+        list = []
+        sublist_count.times { list << [] }
+        list
+      end
+
+      def fill_list_with_predefined_sizes
+        missing = 0
+        @original.each_with_index do |sublist, index|
+          target_count = @max_counts[index]
+          @list[index].concat sublist[0...target_count]
+
+          if sublist.size < target_count
+            missing += target_count - sublist.size
+          end
+        end
+        missing
+      end
+    end
+  end
+end

data/lib/inch/cli.rb

@@ -17,11 +17,12 @@ module Inch
 end
 
 require_relative 'cli/arguments'
+require_relative 'cli/weighted_list'
 require_relative 'cli/sparkline_helper'
 require_relative 'cli/trace_helper'
 require_relative 'cli/yardopts_helper'
+
 require_relative 'cli/command'
-require_relative 'cli/command_parser'
 
 console_rb = File.join(File.dirname(__FILE__), 'cli', 'command', 'console.rb')
 if File.exists?(console_rb)

data/lib/inch/code_object/nodoc_helper.rb

@@ -85,6 +85,8 @@ module Inch
       def files
         object.files
       rescue YARD::CodeObjects::ProxyMethodError
+        # this error is raised by YARD
+        # see broken.rb in test fixtures
         []
       end
 

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

@@ -9,10 +9,10 @@ module Inch
         include NodocHelper
 
         # @return [YARD::CodeObjects::Base] the actual (YARD) code object
-        attr_accessor :object
+        attr_reader :object
 
         # @return [Symbol]
-        #   when objects are assigned to ScoreRanges, this grade is set to
+        #   when objects are assigned to GradeLists, this grade is set to
         #   enable easier querying for objects of a certain grade
         attr_writer :grade
 
@@ -27,7 +27,7 @@ module Inch
 
         # @param object [YARD::CodeObjects::Base] the actual (YARD) code object
         def initialize(object)
-          self.object = object
+          @object = object
         end
 
         def api_tag?
@@ -35,7 +35,14 @@ module Inch
         end
 
         def api_tag
-          object.tag(:api) || (parent && parent.api_tag)
+          tag(:api) || (parent && parent.api_tag)
+        end
+
+        # To be overridden
+        # @see Proxy::NamespaceObject
+        # @return [CodeObject::Proxy::Base,nil] the child inside the current object or +nil+
+        def child(name)
+          nil
         end
 
         # To be overridden
@@ -65,8 +72,8 @@ module Inch
 
         # @return [Symbol]
         def grade
-          @grade ||= Evaluation.new_score_ranges.detect { |range|
-                range.range.include?(score)
+          @grade ||= Evaluation.new_grade_lists.detect { |range|
+                range.scores.include?(score)
               }.grade
         end
 
@@ -75,7 +82,7 @@ module Inch
         end
 
         def has_code_example?
-          !object.tags(:example).empty? ||
+          !tags(:example).empty? ||
             docstring.contains_code_example?
         end
 
@@ -84,10 +91,10 @@ module Inch
         end
 
         def has_multiple_code_examples?
-          if object.tags(:example).size > 1 || docstring.code_examples.size > 1
+          if tags(:example).size > 1 || docstring.code_examples.size > 1
             true
           else
-            if tag = object.tag(:example)
+            if tag = tag(:example)
               multi_code_examples?(tag.text)
             elsif text = docstring.code_examples.first
               multi_code_examples?(text)
@@ -148,7 +155,11 @@ module Inch
         # @return [Boolean]
         #   +true+ if the object or its parent is tagged as @private
         def private_tag?
-          !object.tag(:private).nil? || (parent && parent.private_tag?)
+          !private_tag.nil?
+        end
+
+        def private_tag
+          tag(:private) || (parent && parent.private_tag)
         end
 
         def private_api_tag?
@@ -165,13 +176,13 @@ module Inch
 
         # @return [Boolean] +true+ if the object has no documentation at all
         def undocumented?
-          docstring.empty? && object.tags.empty?
+          docstring.empty? && tags.empty?
         end
 
         # @return [Array]
         #   YARD tags that are not already covered by other wrapper methods
         def unconsidered_tags
-          @unconsidered_tags ||= object.tags.reject do |tag|
+          @unconsidered_tags ||= tags.reject do |tag|
               CONSIDERED_YARD_TAGS.include?(tag.tag_name)
             end
         end
@@ -180,11 +191,23 @@ module Inch
           "#<#{self.class.to_s}: #{path}>"
         end
 
-        private
+        protected
 
         def multi_code_examples?(text)
           text.scan(/\b(#{Regexp.escape(name)})[^_0-9\!\?]/m).size > 1
         end
+
+        def tag(name)
+          tags(name).first
+        end
+
+        def tags(name = nil)
+          object.tags(name)
+        rescue YARD::CodeObjects::ProxyMethodError
+          # this error is raised by YARD
+          # see broken.rb in test fixtures
+          []
+        end
       end
     end
   end

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

@@ -16,6 +16,20 @@ module Inch
           name =~ /\!$/
         end
 
+        def getter?
+          attr_info = object.attr_info || {}
+          read_info = attr_info[:read]
+          if read_info
+            read_info.path == path
+          else
+            parent.child(:"#{name}=")
+          end
+        end
+
+        def has_doc?
+          super && !implicit_docstring?
+        end
+
         def has_parameters?
           !parameters.empty?
         end
@@ -68,6 +82,10 @@ module Inch
           (return_tag && !return_tag.text.empty?) || docstring.describes_return?
         end
 
+        def setter?
+          name =~ /\=$/ && parameters.size == 1
+        end
+
         def questioning_name?
           name =~ /\?$/
         end
@@ -109,6 +127,17 @@ module Inch
           lines.reverse
         end
 
+        def implicit_docstring?
+          if getter?
+            docstring == "Returns the value of attribute #{name}"
+          elsif setter?
+            basename = name.to_s.gsub(/(\=)$/, '')
+            docstring == "Sets the attribute #{basename}"
+          else
+            false
+          end
+        end
+
         def signature_parameter_names
           object.parameters.map(&:first)
         end

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

@@ -4,6 +4,12 @@ module Inch
       # a namespace object can have methods and other namespace objects
       # inside itself (e.g. classes and modules)
       class NamespaceObject < Base
+        def child(name)
+          if children
+            children.detect { |child| child.name == name }
+          end
+        end
+
         def children
           object.children.map do |o|
             Proxy.for(o)