inch 0.1.4 → 0.2.0

data/lib/inch/evaluation/method_object.rb

@@ -1,18 +1,41 @@
 module Inch
   module Evaluation
     class MethodObject < Base
-      DOC_SCORE = 50
-      EXAMPLE_SCORE = 10
-      MULTIPLE_EXAMPLES_SCORE = 25
-      PARAM_SCORE = 40
-      RETURN_SCORE = 10
-
       def evaluate
         eval_doc
         eval_parameters
         eval_return_type
         eval_code_example
+        eval_method
+        eval_misc
+      end
+
+      private
+
+      def eval_doc
+        if object.has_doc?
+          add_role Role::Object::WithDoc.new(object, score_for(:docstring))
+        else
+          add_role Role::Object::WithoutDoc.new(object, score_for(:docstring))
+        end
+      end
 
+      def eval_code_example
+        if object.has_code_example?
+          if object.has_multiple_code_examples?
+            add_role Role::Object::WithMultipleCodeExamples.new(object, score_for(:code_example_multi))
+          else
+            add_role Role::Object::WithCodeExample.new(object, score_for(:code_example_single))
+          end
+        else
+          add_role Role::Object::WithoutCodeExample.new(object, score_for(:code_example_single))
+        end
+      end
+
+      def eval_method
+        if object.constructor?
+          add_role Role::Method::Constructor.new(object)
+        end
         if object.overridden?
           add_role Role::Method::Overridden.new(object, object.overridden_method.score)
         end
@@ -28,12 +51,22 @@ module Inch
         if object.has_alias?
           add_role Role::Method::HasAlias.new(object)
         end
+      end
+
+      def eval_misc
         if object.nodoc?
           add_role Role::Object::TaggedAsNodoc.new(object)
         end
+        if object.api_tag?
+          if object.private_api_tag?
+            add_role Role::Object::TaggedAsPrivateAPI.new(object)
+          else
+            add_role Role::Object::TaggedAsAPI.new(object)
+          end
+        end
         if object.has_unconsidered_tags?
           count = object.unconsidered_tags.size
-          add_role Role::Object::Tagged.new(object, TAGGED_SCORE * count)
+          add_role Role::Object::Tagged.new(object, score_for(:unconsidered_tag) * count)
         end
         if object.in_root?
           add_role Role::Object::InRoot.new(object)
@@ -49,28 +82,6 @@ module Inch
         end
       end
 
-      private
-
-      def eval_doc
-        if object.has_doc?
-          add_role Role::Object::WithDoc.new(object, DOC_SCORE)
-        else
-          add_role Role::Object::WithoutDoc.new(object, DOC_SCORE)
-        end
-      end
-
-      def eval_code_example
-        if object.has_code_example?
-          if object.has_multiple_code_examples?
-            add_role Role::Object::WithMultipleCodeExamples.new(object, MULTIPLE_EXAMPLES_SCORE)
-          else
-            add_role Role::Object::WithCodeExample.new(object, EXAMPLE_SCORE)
-          end
-        else
-          add_role Role::Object::WithoutCodeExample.new(object, EXAMPLE_SCORE)
-        end
-      end
-
       def eval_parameters
         if object.has_parameters?
           eval_all_parameters
@@ -81,17 +92,17 @@ module Inch
 
       def eval_no_parameters
         if score > min_score
-          add_role Role::Method::WithoutParameters.new(object, PARAM_SCORE)
+          add_role Role::Method::WithoutParameters.new(object, score_for(:parameters))
         end
       end
 
       def eval_all_parameters
         params = object.parameters
-        per_param = PARAM_SCORE.to_f / params.size
+        per_param = score_for(:parameters) / params.size
         params.each do |param|
           if param.mentioned?
             if param.wrongly_mentioned?
-              add_role Role::MethodParameter::WithWrongMention.new(param, -PARAM_SCORE)
+              add_role Role::MethodParameter::WithWrongMention.new(param, -score_for(:parameters))
             else
               add_role Role::MethodParameter::WithMention.new(param, per_param * 0.5)
             end
@@ -120,17 +131,14 @@ module Inch
 
       def eval_return_type
         if object.return_mentioned?
-          if object.questioning_name? && !object.return_described?
-            # annotating a question mark method with the return type boolean
-            # does not give any points
-            # also, this could to be one of those cases where YARD
-            # automatically assigns a @return tag to methods ending in a
-            # question mark
-          else
-            add_role Role::Method::WithReturnType.new(object, RETURN_SCORE)
-          end
+          add_role Role::Method::WithReturnType.new(object, score_for(:return_type))
+        else
+          add_role Role::Method::WithoutReturnType.new(object, score_for(:return_type))
+        end
+        if object.return_described?
+          add_role Role::Method::WithReturnDescription.new(object, score_for(:return_description))
         else
-          add_role Role::Method::WithoutReturnType.new(object, RETURN_SCORE)
+          add_role Role::Method::WithoutReturnDescription.new(object, score_for(:return_description))
         end
       end
     end

data/lib/inch/evaluation/namespace_object.rb

@@ -3,10 +3,6 @@ module Inch
     # a namespace object can have methods and other namespace objects
     # inside itself (e.g. classes and modules)
     class NamespaceObject < Base
-      DOC_SCORE = MAX_SCORE
-      EXAMPLE_SCORE = 10
-      MULTIPLE_EXAMPLES_SCORE = 20
-
       RUBY_CORE = %w(Array Bignum BasicObject Object Module Class Complex NilClass Numeric String Float Fiber FiberError Continuation Dir File Encoding Enumerator StopIteration Enumerator::Generator Enumerator::Yielder Exception SystemExit SignalException Interrupt StandardError TypeError ArgumentError IndexError KeyError RangeError ScriptError SyntaxError LoadError NotImplementedError NameError NoMethodError RuntimeError SecurityError NoMemoryError EncodingError SystemCallError Encoding::CompatibilityError File::Stat IO Hash ENV IOError EOFError ARGF RubyVM RubyVM::InstructionSequence Math::DomainError ZeroDivisionError FloatDomainError Integer Fixnum Data TrueClass FalseClass Mutex Thread Proc LocalJumpError SystemStackError Method UnboundMethod Binding Process::Status Random Range Rational RegexpError Regexp MatchData Symbol Struct ThreadGroup ThreadError Time Encoding::UndefinedConversionError Encoding::InvalidByteSequenceError Encoding::ConverterNotFoundError Encoding::Converter RubyVM::Env) +
                   %w(Comparable Kernel File::Constants Enumerable Errno FileTest GC ObjectSpace GC::Profiler IO::WaitReadable IO::WaitWritable Marshal Math Process Process::UID Process::GID Process::Sys Signal)
 
@@ -14,24 +10,7 @@ module Inch
         eval_doc
         eval_children
         eval_code_example
-
-        if object.has_many_attributes?
-          add_role Role::Namespace::WithManyAttributes.new(object)
-        end
-        if object.nodoc?
-          add_role Role::Object::TaggedAsNodoc.new(object)
-        end
-        if object.has_unconsidered_tags?
-          count = object.unconsidered_tags.size
-          add_role Role::Object::Tagged.new(object, TAGGED_SCORE * count)
-        end
-        if object.in_root?
-          add_role Role::Object::InRoot.new(object)
-        end
-        if object.public? # this is always true for classes and modules
-          add_role Role::Object::Public.new(object)
-        end
-
+        eval_misc
         eval_core
       end
 
@@ -43,23 +22,23 @@ module Inch
         end
       end
 
-      def eval_doc
-        if object.has_doc?
-          add_role Role::Object::WithDoc.new(object, DOC_SCORE)
-        else
-          add_role Role::Object::WithoutDoc.new(object, DOC_SCORE)
-        end
-      end
-
       def eval_code_example
         if object.has_code_example?
           if object.has_multiple_code_examples?
-            add_role Role::Object::WithMultipleCodeExamples.new(object, MULTIPLE_EXAMPLES_SCORE)
+            add_role Role::Object::WithMultipleCodeExamples.new(object, score_for(:code_example_multi))
           else
-            add_role Role::Object::WithCodeExample.new(object, EXAMPLE_SCORE)
+            add_role Role::Object::WithCodeExample.new(object, score_for(:code_example_single))
           end
         else
-          add_role Role::Object::WithoutCodeExample.new(object, EXAMPLE_SCORE)
+          add_role Role::Object::WithoutCodeExample.new(object, score_for(:code_example_single))
+        end
+      end
+
+      def eval_doc
+        if object.has_doc?
+          add_role Role::Object::WithDoc.new(object, score_for(:docstring))
+        else
+          add_role Role::Object::WithoutDoc.new(object, score_for(:docstring))
         end
       end
 
@@ -80,6 +59,32 @@ module Inch
         end
       end
 
+      def eval_misc
+        if object.has_many_attributes?
+          add_role Role::Namespace::WithManyAttributes.new(object)
+        end
+        if object.nodoc?
+          add_role Role::Object::TaggedAsNodoc.new(object)
+        end
+        if object.api_tag?
+          if object.private_api_tag?
+            add_role Role::Object::TaggedAsPrivateAPI.new(object)
+          else
+            add_role Role::Object::TaggedAsAPI.new(object)
+          end
+        end
+        if object.has_unconsidered_tags?
+          count = object.unconsidered_tags.size
+          add_role Role::Object::Tagged.new(object, score_for(:unconsidered_tag) * count)
+        end
+        if object.in_root?
+          add_role Role::Object::InRoot.new(object)
+        end
+        if object.public? # this is always true for classes and modules
+          add_role Role::Object::Public.new(object)
+        end
+      end
+
       def children
         @children ||= object.children.map(&:evaluation)
       end

data/lib/inch/evaluation/role/constant.rb

@@ -1,6 +1,7 @@
 module Inch
   module Evaluation
     module Role
+      # Roles assigned to constants
       module Constant
         class WithDoc < Object::WithDoc
         end

data/lib/inch/evaluation/role/method.rb

@@ -2,46 +2,77 @@ module Inch
   module Evaluation
     module Role
       module Method
+        # Role assigned to methods without parameters
         class WithoutParameters < Base
         end
+
+        # Role assigned to methods with many parameters
+        #
+        # @see CodeObject::Proxy::MethodObject#has_many_parameters?
         class WithManyParameters < Base
-          # +priority
           def priority
             +2
           end
         end
+
+        # Role assigned to methods where the return value is typed in the docs
+        class WithReturnType < Base
+        end
+
+        # Role assigned to methods where the return value is not typed
+        class WithoutReturnType < Missing
+          def suggestion
+            "Describe what '#{object.name}' returns"
+          end
+        end
+
+        # Role assigned to methods where the return value is decribed in the docs
+        class WithReturnDescription < Base
+        end
+
+        # Role assigned to methods where the return value is not decribed
+        class WithoutReturnDescription < Missing
+          def suggestion
+            "Describe what '#{object.name}' returns"
+          end
+        end
+
+
+        # Role assigned to methods with many lines
+        #
+        # @see CodeObject::Proxy::MethodObject#has_many_lines?
         class WithManyLines < Base
-          # +priority
           def priority
             +2
           end
         end
+
+        # Role assigned to methods whose name end in a '!'
         class WithBangName < Base
-          # +priority
           def priority
             +3
           end
         end
+
+        # Role assigned to methods whose name end in a '?'
         class WithQuestioningName < Base
           def priority
             -4
           end
         end
+
+        # Role assigned to methods which are aliased
         class HasAlias < Base
-          # +priority
           def priority
             +2
           end
         end
 
-        class WithReturnType < Base
-        end
-        class WithoutReturnType < Missing
-          def suggestion
-            "Describe what '#{object.name}' returns"
-          end
+        # Role assigned to methods that are constructors
+        class Constructor < Base
         end
 
+        # Role assigned to methods that are overriding another method
         class Overridden < Base
           # It seems more important to document the overridden method,
           # than the overriding one

data/lib/inch/evaluation/role/method_parameter.rb

@@ -1,31 +1,43 @@
 module Inch
   module Evaluation
     module Role
+      # Roles assigned to method parameters
       module MethodParameter
+        # Role assigned to parameters that are mentioned in the docs
         class WithMention < Base
         end
+
+        # Role assigned to parameters that are not mentioned in the docs
         class WithoutMention < Missing
           def suggestion
             "Describe the parameter '#{object.name}'"
           end
         end
 
+        # Role assigned to parameters that are typed in the docs
         class WithType < Base
         end
+
+        # Role assigned to parameters that are not typed in the docs
         class WithoutType < Missing
         end
 
+        # Role assigned to parameters that are spalts, e.g. +*args+
         class Splat < Base
           def priority
             +1
           end
         end
+
+        # Role assigned to parameters that are blocks, e.g. +&block+
         class Block < Base
           def priority
             +1
           end
         end
 
+        # Role assigned to parameters that are documented, but not part of
+        # the method signature
         class WithWrongMention < Missing
           def suggestion
             "The parameter '#{object.name}' seems not to be part of the signature."
@@ -34,8 +46,11 @@ module Inch
             +1
           end
         end
+
+        # Role assigned to parameters that have a 'bad' name
+        #
+        # @see CodeObject::Proxy::MethodParameterObject#bad_name?
         class WithBadName < Base
-          # +priority
           def priority
             +1
           end

data/lib/inch/evaluation/role/namespace.rb

@@ -1,7 +1,9 @@
 module Inch
   module Evaluation
     module Role
+      # Roles assigned to namespaces (classes and modules)
       module Namespace
+        # Role assigned to namespaces with children
         class WithChildren < Base
           # This role doesnot assign a score.
           def score
@@ -13,12 +15,20 @@ module Inch
             # @value.to_f
           end
         end
+
+        # Role assigned to namespaces with many children
+        #
+        # @see CodeObject::Proxy::NamespaceObject#has_many_children?
         class WithManyChildren < Base
           # +priority
           def priority
             +1
           end
         end
+
+        # Role assigned to namespaces with many attributes
+        #
+        # @see CodeObject::Proxy::NamespaceObject#has_many_attributes?
         class WithManyAttributes < Base
           # +priority
           def priority
@@ -26,28 +36,30 @@ module Inch
           end
         end
 
+        # Role assigned to namespaces without any children
         class WithoutChildren < Base
         end
+
+        # Role assigned to namespaces without any methods
         class WithoutMethods < Base
-          # --priority
           def priority
             -2
           end
         end
+
         # A 'pure' namespace has only namespaces as children
         class Pure < Base
-          # --priority
           def priority
             -2
           end
         end
+
         # A 'core' namespace is a class or module that is part of the Ruby
         # core. It might appear in the object tree when monkey-patching
         # functionality.
-        # But just because we patch Hash does not mean we need to document
-        # the Hash class itself.
+        # (the reasoning here is: just because we patch Hash does not mean
+        # we need to document the Hash class itself)
         class Core < Base
-          # --priority
           def priority
             -7
           end