inch 0.2.3 → 0.3.0.rc1

data/lib/inch/codebase/proxy.rb

@@ -0,0 +1,22 @@
+module Inch
+  module Codebase
+    class Proxy
+      attr_reader :objects
+
+      def initialize(dir = Dir.pwd, paths = nil, excluded = nil)
+        @base_dir = dir
+        provider = CodeObject::Provider.parse(dir, paths, excluded)
+        @objects = Codebase::Objects.new(provider.objects)
+      end
+
+      def grade_lists
+        lists = Evaluation.new_grade_lists
+        lists.each do |range|
+          list = objects.select { |o| range.scores.include?(o.score) }
+          range.objects = Objects.sort_by_priority(list)
+        end
+        lists
+      end
+    end
+  end
+end

data/lib/inch/config.rb

@@ -1,4 +1,7 @@
 module Inch
+  # Stores the configuration for Inch
+  #
+  # @see config/defaults.rb
   class Config
     class << self
       attr_accessor :instance
@@ -37,8 +40,12 @@ module Inch
         ::Inch::Evaluation::Grade.grade(symbol, &block)
       end
 
+      def priority(symbol, &block)
+        ::Inch::Evaluation::PriorityRange.priority_range(symbol, &block)
+      end
+
       def schema(constant_name, &block)
-        constant = eval("::Inch::Evaluation::#{constant_name}")
+        constant = eval("::Inch::Evaluation::Proxy::#{constant_name}")
         constant.criteria(&block)
       end
     end

data/lib/inch/evaluation.rb

@@ -1,4 +1,6 @@
 module Inch
+  # The Evaluation module concerns itself with the evaluation of code objects
+  # with regard to their inline code documentation
   module Evaluation
     def self.for(code_object)
       class_for(code_object).new(code_object)
@@ -13,12 +15,13 @@ module Inch
   end
 end
 
-require_relative 'evaluation/read_write_methods'
+require_relative 'utils/read_write_methods'
 
 require_relative 'evaluation/file'
 require_relative 'evaluation/grade'
 require_relative 'evaluation/grade_list'
 require_relative 'evaluation/object_schema'
+require_relative 'evaluation/priority_range'
 
 require_relative 'evaluation/role/base'
 require_relative 'evaluation/role/missing'
@@ -28,9 +31,4 @@ require_relative 'evaluation/role/method_parameter'
 require_relative 'evaluation/role/namespace'
 require_relative 'evaluation/role/constant'
 
-require_relative 'evaluation/base'
-require_relative 'evaluation/namespace_object'
-require_relative 'evaluation/class_object'
-require_relative 'evaluation/constant_object'
-require_relative 'evaluation/method_object'
-require_relative 'evaluation/module_object'
+require_relative 'evaluation/proxy'

data/lib/inch/evaluation/file.rb

@@ -11,7 +11,7 @@ module Inch
       end
 
       # @note added to be compatible with code objects
-      def path
+      def fullname
         filename
       end
 

data/lib/inch/evaluation/grade.rb

@@ -1,7 +1,7 @@
 module Inch
   module Evaluation
     class Grade
-      extend Evaluation::ReadWriteMethods
+      extend Utils::ReadWriteMethods
 
       rw_methods %w(scores label color bg_color)
 

data/lib/inch/evaluation/object_schema.rb

@@ -1,7 +1,9 @@
 module Inch
   module Evaluation
+    # An ObjectSchema describes how important certain parts of the docs are
+    # for the associated Object
     class ObjectSchema
-      extend Evaluation::ReadWriteMethods
+      extend Utils::ReadWriteMethods
 
       rw_methods %w(
         docstring

data/lib/inch/evaluation/priority_range.rb

@@ -0,0 +1,44 @@
+module Inch
+  module Evaluation
+    class PriorityRange
+      extend Utils::ReadWriteMethods
+      extend Forwardable
+
+      rw_methods %w(priorities arrow)
+
+      def_delegators :priorities, :include?, :min, :max
+
+      def initialize(symbol)
+        @symbol = symbol
+      end
+
+      def update(&block)
+        instance_eval(&block)
+      end
+
+      def to_sym
+        @symbol
+      end
+
+      def to_s
+        arrow
+      end
+
+      class << self
+        attr_reader :priority_map
+
+        def all
+          @priority_map ||= {}
+          @priority_map.values
+        end
+
+        def priority_range(symbol, &block)
+          @priority_map ||= {}
+          @priority_map[symbol] ||= PriorityRange.new(symbol)
+          @priority_map[symbol].update(&block) if block
+          @priority_map[symbol]
+        end
+      end
+    end
+  end
+end

data/lib/inch/evaluation/proxy.rb

@@ -0,0 +1,25 @@
+module Inch
+  # The Evaluation module concerns itself with the evaluation of code objects
+  # with regard to their inline code documentation
+  module Evaluation
+    module Proxy
+      def self.for(code_object)
+        class_for(code_object).new(code_object)
+      end
+
+      private
+
+      def self.class_for(code_object)
+        class_name = code_object.class.to_s.split('::').last
+        eval(class_name)
+      end
+    end
+  end
+end
+
+require_relative 'proxy/base'
+require_relative 'proxy/namespace_object'
+require_relative 'proxy/class_object'
+require_relative 'proxy/constant_object'
+require_relative 'proxy/method_object'
+require_relative 'proxy/module_object'

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

@@ -0,0 +1,146 @@
+module Inch
+  module Evaluation
+    module Proxy
+      # @abstract
+      class Base
+        extend Forwardable
+
+        MIN_SCORE = 0
+        MAX_SCORE = 100
+
+        TAGGED_SCORE = 20 # assigned per unconsidered tag
+
+        # @return [CodeObject::Proxy::Base]
+        attr_accessor :object
+
+        attr_reader :min_score, :max_score
+
+        class << self
+          attr_reader :criteria_map
+
+          # Defines the weights during evaluation for different criteria
+          #
+          #   MethodObject.criteria do
+          #     docstring           0.5
+          #     parameters          0.4
+          #     return_type         0.1
+          #
+          #     if object.constructor?
+          #       parameters        0.5
+          #       return_type       0.0
+          #     end
+          #   end
+          #
+          # @return [void]
+          def criteria(&block)
+            @criteria_map ||= {}
+            @criteria_map[to_s] ||= ObjectSchema.new(&block)
+          end
+        end
+
+        # @param object [CodeObject::Proxy::Base]
+        def initialize(object)
+          self.object = object
+          @roles = []
+          evaluate
+        end
+
+        # Evaluates the objects and assigns roles
+        def evaluate
+          __evaluate(object, relevant_roles)
+        end
+
+        def __evaluate(object, role_classes)
+          role_classes.each do |role_class, score|
+            if role_class.applicable?(object)
+              add_role role_class.new(object, score)
+            end
+          end
+        end
+
+        # @return [Float]
+        def max_score
+          arr = @roles.map(&:max_score).compact
+          [MAX_SCORE].concat(arr).min
+        end
+
+        # @return [Float]
+        def min_score
+          arr = @roles.map(&:min_score).compact
+          [MIN_SCORE].concat(arr).max
+        end
+
+        # @return [Float]
+        def score
+          value = @roles.inject(0) { |sum,r| sum + r.score.to_f }
+          if value < min_score
+            min_score
+          elsif value > max_score
+            max_score
+          else
+            value
+          end
+        end
+
+        # @return [Fixnum]
+        def priority
+          @roles.inject(0) { |sum,r| sum + r.priority.to_i }
+        end
+
+        # @return [Array<Evaluation::Role::Base>]
+        def roles
+          @roles
+        end
+
+        protected
+
+        def add_role(role)
+          @roles << role
+        end
+
+        def criteria
+          @criteria ||= begin
+            c = self.class.criteria_map[self.class.to_s]
+            c.evaluate(object)
+            c
+          end
+        end
+
+        def relevant_base_roles
+          {
+            Role::Object::InRoot => nil,
+            Role::Object::Public => nil,
+            Role::Object::Protected => nil,
+            Role::Object::Private => nil,
+            Role::Object::TaggedAsNodoc => nil,
+            Role::Object::WithDoc => score_for(:docstring),
+            Role::Object::WithoutDoc => score_for(:docstring),
+            Role::Object::WithCodeExample => score_for(:code_example_single),
+            Role::Object::WithMultipleCodeExamples => score_for(:code_example_multi),
+            Role::Object::WithoutCodeExample => score_for(:code_example_single),
+            Role::Object::Tagged => score_for_unconsidered_tags,
+            Role::Object::TaggedAsAPI => nil,
+            Role::Object::TaggedAsPrivateAPI => nil,
+          }
+        end
+
+        def score_for_unconsidered_tags
+          count = object.unconsidered_tag_count
+          score_for(:unconsidered_tag) * count
+        end
+
+        # Returns a key-value pair of Role classes and potential scores for
+        # each role (can be nil)
+        #
+        # @return [Hash]
+        def relevant_roles
+          {}
+        end
+
+        def score_for(criteria_name)
+          criteria.send(criteria_name) * MAX_SCORE
+        end
+      end
+    end
+  end
+end

data/lib/inch/evaluation/proxy/class_object.rb

@@ -0,0 +1,8 @@
+module Inch
+  module Evaluation
+    module Proxy
+      class ClassObject < NamespaceObject
+      end
+    end
+  end
+end

data/lib/inch/evaluation/proxy/constant_object.rb

@@ -0,0 +1,19 @@
+module Inch
+  module Evaluation
+    module Proxy
+      class ConstantObject < Base
+        protected
+
+        def relevant_roles
+          {
+            Role::Constant::WithDoc => score_for(:docstring),
+            Role::Constant::WithoutDoc => score_for(:docstring),
+            Role::Constant::TaggedAsNodoc => nil,
+            Role::Constant::Public => nil,
+            Role::Constant::Private => nil,
+          }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,65 @@
+module Inch
+  module Evaluation
+    module Proxy
+      class MethodObject < Base
+        def evaluate
+          super
+          evaluate_parameters
+        end
+
+        protected
+
+        def relevant_roles
+          relevant_base_roles.merge(relevant_method_roles)
+        end
+
+        private
+
+        def evaluate_parameters
+          params = object.parameters
+          per_param = score_for_single_parameter
+          params.each do |param|
+            role_classes = relevant_parameter_roles(param, per_param)
+            __evaluate(param, role_classes)
+          end
+        end
+
+        def relevant_method_roles
+          {
+            Role::Method::Constructor => nil,
+            Role::Method::Getter => nil,
+            Role::Method::Setter => nil,
+            Role::Method::Overridden => object.overridden? ? object.overridden_method.score : nil,
+            Role::Method::WithManyLines => nil,
+            Role::Method::WithBangName => nil,
+            Role::Method::WithQuestioningName => nil,
+            Role::Method::HasAlias => nil,
+            Role::Method::WithReturnType => score_for(:return_type),
+            Role::Method::WithoutReturnType => score_for(:return_type),
+            Role::Method::WithReturnDescription => score_for(:return_description),
+            Role::Method::WithoutReturnDescription => score_for(:return_description),
+            Role::Method::WithoutParameters => score_for(:parameters),
+            Role::Method::WithManyParameters => nil,
+          }
+        end
+
+        def relevant_parameter_roles(param, per_param)
+          {
+            Role::MethodParameter::WithWrongMention => -score_for(:parameters),
+            Role::MethodParameter::WithMention => per_param * 0.5,
+            Role::MethodParameter::WithoutMention => per_param * 0.5,
+            Role::MethodParameter::WithType => per_param * 0.5,
+            Role::MethodParameter::WithoutType => per_param * 0.5,
+            Role::MethodParameter::WithBadName => nil,
+            Role::MethodParameter::Block => nil,
+            Role::MethodParameter::Splat => nil,
+          }
+        end
+
+        def score_for_single_parameter
+          @param_score ||= score_for(:parameters) / object.parameters.size
+        end
+      end
+    end
+  end
+end

data/lib/inch/evaluation/proxy/module_object.rb

@@ -0,0 +1,8 @@
+module Inch
+  module Evaluation
+    module Proxy
+      class ModuleObject < NamespaceObject
+      end
+    end
+  end
+end

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

@@ -0,0 +1,27 @@
+module Inch
+  module Evaluation
+    module Proxy
+      # a namespace object can have methods and other namespace objects
+      # inside itself (e.g. classes and modules)
+      class NamespaceObject < Base
+        protected
+
+        def relevant_roles
+          relevant_base_roles.merge(relevant_namespace_roles)
+        end
+
+        def relevant_namespace_roles
+          {
+            Role::Namespace::Core => nil,
+            Role::Namespace::WithManyAttributes => nil,
+            Role::Namespace::WithoutChildren => nil,
+            Role::Namespace::WithChildren => nil,
+            Role::Namespace::WithManyChildren => nil,
+            Role::Namespace::WithoutMethods => nil,
+            Role::Namespace::Pure => nil,
+          }
+        end
+      end
+    end
+  end
+end