inch 0.0.1 → 0.1.0

data/lib/inch/evaluation/method_object.rb

@@ -0,0 +1,127 @@
+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
+
+        if object.overridden?
+          add_role Role::Method::Overridden.new(object, object.overridden_method.score)
+        end
+        if object.has_many_lines?
+          add_role Role::Method::WithManyLines.new(object)
+        end
+        if object.bang_name?
+          add_role Role::Method::WithBangName.new(object)
+        end
+        if object.has_alias?
+          add_role Role::Method::HasAlias.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?
+          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
+      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
+        else
+          eval_no_parameters
+        end
+      end
+
+      def eval_no_parameters
+        if score > min_score
+          add_role Role::Method::WithoutParameters.new(object, PARAM_SCORE)
+        end
+      end
+
+      def eval_all_parameters
+        params = object.parameters
+        per_param = PARAM_SCORE.to_f / params.size
+        params.each do |param|
+          if param.mentioned?
+            if param.wrongly_mentioned?
+              add_role Role::MethodParameter::WithWrongMention.new(param, -PARAM_SCORE)
+            else
+              add_role Role::MethodParameter::WithMention.new(param, per_param * 0.5)
+            end
+          else
+            add_role Role::MethodParameter::WithoutMention.new(param, per_param * 0.5)
+          end
+          if param.typed?
+            add_role Role::MethodParameter::WithType.new(param, per_param * 0.5)
+          else
+            add_role Role::MethodParameter::WithoutType.new(param, per_param * 0.5)
+          end
+          if param.bad_name?
+            add_role Role::MethodParameter::WithBadName.new(param)
+          end
+          if param.block?
+            add_role Role::MethodParameter::Block.new(param)
+          end
+          if param.splat?
+            add_role Role::MethodParameter::Splat.new(param)
+          end
+        end
+        if object.has_many_parameters?
+          add_role Role::Method::WithManyParameters.new(object)
+        end
+      end
+
+      def eval_return_type
+        if object.return_mentioned?
+          add_role Role::Method::WithReturnType.new(object, RETURN_SCORE)
+        else
+          add_role Role::Method::WithoutReturnType.new(object, RETURN_SCORE)
+        end
+      end
+    end
+  end
+end

data/lib/inch/evaluation/module_object.rb

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

data/lib/inch/evaluation/namespace_object.rb

@@ -0,0 +1,94 @@
+module Inch
+  module Evaluation
+    # 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)
+
+      def evaluate
+        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?
+          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
+
+      private
+
+      def eval_core
+        if RUBY_CORE.include?(object.path)
+          add_role Role::Namespace::Core.new(object)
+        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)
+          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_children
+        if children.empty?
+          add_role Role::Namespace::WithoutChildren.new(object)
+        else
+          add_role Role::Namespace::WithChildren.new(object, children.map(&:score).min)
+          if object.pure_namespace?
+            add_role Role::Namespace::Pure.new(object)
+          end
+          if object.no_methods?
+            add_role Role::Namespace::WithoutMethods.new(object)
+          end
+          if object.has_many_children?
+            add_role Role::Namespace::WithManyChildren.new(object)
+          end
+        end
+      end
+
+      def children
+        @children ||= object.children.map(&:evaluation)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,49 @@
+module Inch
+  module Evaluation
+    module Role
+      class Base
+        attr_reader :object
+
+        def initialize(object, value = nil)
+          @object = object
+          @value = value
+        end
+
+        # Override this method to that a max_score for the evaluation.
+        def max_score
+        end
+
+        # Override this method to that a min_score for the evaluation.
+        def min_score
+        end
+
+        # Returns a score that will be added to the associated object's
+        # overall score.
+        #
+        # Override this method to that a score for the role.
+        def score
+          @value.to_f
+        end
+
+        # @return [Float]
+        #  a score that can be achieved by adding the missing thing mentioned
+        #  by the role
+        def potential_score
+          nil
+        end
+
+        def priority
+          0
+        end
+
+        def suggestion
+          nil
+        end
+
+        def object_type
+          object.class.to_s.split('::').last.gsub(/Object$/, '').downcase
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,43 @@
+module Inch
+  module Evaluation
+    module Role
+      module Constant
+        class WithDoc < Object::WithDoc
+        end
+        class WithoutDoc < Object::WithoutDoc
+        end
+
+        class TaggedAsNodoc < Object::TaggedAsNodoc
+        end
+        class InRoot < Object::InRoot
+        end
+
+        class Public < Object::Public
+          def priority
+            -1
+          end
+        end
+        class Protected < Object::Protected
+          def priority
+            -2
+          end
+        end
+        class Private < Object::Private
+          def priority
+            -3
+          end
+        end
+
+        class WithCodeExample < Object::WithCodeExample
+        end
+        class WithMultipleCodeExamples < Object::WithMultipleCodeExamples
+        end
+        class WithoutCodeExample < Object::WithoutCodeExample
+          def suggestion
+            nil
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,60 @@
+module Inch
+  module Evaluation
+    module Role
+      module Method
+        class WithoutParameters < Base
+        end
+        class WithManyParameters < Base
+          # +priority
+          def priority
+            +2
+          end
+        end
+        class WithManyLines < Base
+          # +priority
+          def priority
+            +2
+          end
+        end
+        class WithBangName < Base
+          # +priority
+          def priority
+            +3
+          end
+        end
+        class HasAlias < Base
+          # +priority
+          def priority
+            +2
+          end
+        end
+
+        class WithReturnType < Base
+        end
+        class WithoutReturnType < Missing
+          def suggestion
+            "Describe the return type of '#{object.name}'"
+          end
+        end
+
+        class Overridden < Base
+          # It seems more important to document the overridden method,
+          # than the overriding one
+          def priority
+            -2
+          end
+
+          # This role doesnot assign a score.
+          def score
+            nil
+          end
+
+          # This role sets a min_score.
+          def min_score
+            @value.to_f
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,46 @@
+module Inch
+  module Evaluation
+    module Role
+      module MethodParameter
+        class WithMention < Base
+        end
+        class WithoutMention < Missing
+          def suggestion
+            "Describe the parameter '#{object.name}'"
+          end
+        end
+
+        class WithType < Base
+        end
+        class WithoutType < Missing
+        end
+
+        class Splat < Base
+          def priority
+            +1
+          end
+        end
+        class Block < Base
+          def priority
+            +1
+          end
+        end
+
+        class WithWrongMention < Missing
+          def suggestion
+            "The parameter '#{object.name}' seems not to be part of the signature."
+          end
+          def priority
+            +1
+          end
+        end
+        class WithBadName < Base
+          # +priority
+          def priority
+            +1
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,20 @@
+module Inch
+  module Evaluation
+    module Role
+      # Missing is the base class for things that can be improved in the doc
+      #
+      class Missing < Base
+        def score
+          nil
+        end
+
+        # @return [Float]
+        #  a score that can be achieved by adding the missing thing mentioned
+        #  by the role
+        def potential_score
+          @value.to_f
+        end
+      end
+    end
+  end
+end