inch 0.5.0.rc3 → 0.5.0.rc4

data/lib/inch/language/ruby/code_object/namespace_object.rb

@@ -0,0 +1,35 @@
+module Inch
+  module Language
+    module Ruby
+      module CodeObject
+        # a namespace object can have methods and other namespace objects
+        # inside itself (e.g. classes and modules)
+        class NamespaceObject < Base
+          # The wording is a bit redundant, but this means the class and
+          # instance attributes of the namespace
+          def attributes
+            self[:attributes]
+          end
+
+          MANY_ATTRIBUTES_THRESHOLD = 5
+          def has_many_attributes?
+            attributes.size > MANY_ATTRIBUTES_THRESHOLD
+          end
+
+          MANY_CHILDREN_THRESHOLD = 20
+          def has_many_children?
+            children.size > MANY_CHILDREN_THRESHOLD
+          end
+
+          def has_methods?
+            children.any?(&:method?)
+          end
+
+          def pure_namespace?
+            children.all?(&:namespace?)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/inch/language/ruby/evaluation/base.rb

@@ -0,0 +1,45 @@
+module Inch
+  module Language
+    module Ruby
+      module Evaluation
+        # Base class for all Ruby related evaluations
+        #
+        # @abstract
+        class Base < Inch::Evaluation::Proxy
+          protected
+
+          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::TaggedAsInternalAPI => nil,
+              Role::Object::TaggedAsPrivate => nil,
+              Role::Object::Alias =>
+                if object.alias?
+                  object.aliased_object.score
+                else
+                  nil
+                end
+            }
+          end
+
+          def score_for_unconsidered_tags
+            count = object.unconsidered_tag_count
+            score_for(:unconsidered_tag) * count
+          end
+        end
+      end
+    end
+  end
+end

data/lib/inch/language/ruby/evaluation/class_object.rb

@@ -0,0 +1,10 @@
+module Inch
+  module Language
+    module Ruby
+      module Evaluation
+        class ClassObject < NamespaceObject
+        end
+      end
+    end
+  end
+end

data/lib/inch/language/ruby/evaluation/class_variable_object.rb

@@ -0,0 +1,21 @@
+module Inch
+  module Language
+    module Ruby
+      module Evaluation
+        class ClassVariableObject < Base
+          protected
+
+          def relevant_roles
+            {
+              Role::ClassVariable::WithDoc => score_for(:docstring),
+              Role::ClassVariable::WithoutDoc => score_for(:docstring),
+              Role::ClassVariable::TaggedAsNodoc => nil,
+              Role::ClassVariable::Public => nil,
+              Role::ClassVariable::Private => nil
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/inch/language/ruby/evaluation/constant_object.rb

@@ -0,0 +1,21 @@
+module Inch
+  module Language
+    module Ruby
+      module Evaluation
+        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
+end

data/lib/inch/language/ruby/evaluation/method_object.rb

@@ -0,0 +1,74 @@
+module Inch
+  module Language
+    module Ruby
+      module Evaluation
+        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 =>
+                if object.overridden?
+                  object.overridden_method.score
+                else
+                  nil
+                end,
+              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
+end

data/lib/inch/language/ruby/evaluation/module_object.rb

@@ -0,0 +1,10 @@
+module Inch
+  module Language
+    module Ruby
+      module Evaluation
+        class ModuleObject < NamespaceObject
+        end
+      end
+    end
+  end
+end

data/lib/inch/language/ruby/evaluation/namespace_object.rb

@@ -0,0 +1,30 @@
+module Inch
+  module Language
+    module Ruby
+      module Evaluation
+        # 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
+
+          # @see Evaluation::Ruby::Base
+          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
+end

data/lib/inch/language/ruby/import.rb

@@ -0,0 +1,34 @@
+module Inch
+  module Language
+    module Ruby
+    end
+  end
+end
+
+require "inch/language/ruby/provider/yard"
+
+require "inch/language/ruby/code_object/base"
+require "inch/language/ruby/code_object/namespace_object"
+require "inch/language/ruby/code_object/class_object"
+require "inch/language/ruby/code_object/class_variable_object"
+require "inch/language/ruby/code_object/constant_object"
+require "inch/language/ruby/code_object/method_object"
+require "inch/language/ruby/code_object/method_parameter_object"
+require "inch/language/ruby/code_object/module_object"
+
+require "inch/language/ruby/evaluation/base"
+require "inch/language/ruby/evaluation/namespace_object"
+require "inch/language/ruby/evaluation/class_object"
+require "inch/language/ruby/evaluation/class_variable_object"
+require "inch/language/ruby/evaluation/constant_object"
+require "inch/language/ruby/evaluation/method_object"
+require "inch/language/ruby/evaluation/module_object"
+
+require "inch/language/ruby/roles/base"
+require "inch/language/ruby/roles/missing"
+require "inch/language/ruby/roles/object"
+require "inch/language/ruby/roles/method"
+require "inch/language/ruby/roles/method_parameter"
+require "inch/language/ruby/roles/namespace"
+require "inch/language/ruby/roles/constant"
+require "inch/language/ruby/roles/class_variable"

data/lib/inch/language/ruby/provider/yard.rb

@@ -0,0 +1,58 @@
+module Inch
+  module Language
+    module Ruby
+      module Provider
+        # Parses the source tree (using YARD)
+        module YARD
+          # Returns +true+ if the docstring was generated by YARD
+          #
+          # @param docstring [Docstring,String]
+          # @param method [MethodObject]
+          def self.implicit_docstring?(docstring, method)
+            name = method.name
+            if method.getter?
+              docstring.to_s == "Returns the value of attribute #{name}"
+            elsif method.setter?
+              basename = name.to_s.gsub(/(\=)$/, "")
+              docstring.to_s == "Sets the attribute #{basename}"
+            else
+              false
+            end
+          end
+
+          # Returns +true+ if the tag was generated by YARD
+          #
+          # @param tag [::YARD::Tag]
+          # @param method [MethodObject]
+          def self.implicit_tag?(tag, method)
+            name = method.name
+            if method.getter?
+              tag.tag_name == "return" &&
+                tag.text == "the current value of #{name}"
+            elsif method.setter?
+              tag.tag_name == "return" &&
+                tag.text == "the newly set value"
+            else
+              false
+            end
+          end
+
+          # @see Provider.parse
+          def self.parse(dir, config)
+            Parser.parse(dir, config)
+          end
+        end
+      end
+    end
+  end
+end
+
+require "logger"
+require "yard"
+
+log.level = ::Logger::UNKNOWN # basically disable YARD's logging
+
+require "inch/language/ruby/provider/yard/parser"
+require "inch/language/ruby/provider/yard/docstring"
+require "inch/language/ruby/provider/yard/nodoc_helper"
+require "inch/language/ruby/provider/yard/object"

data/lib/inch/language/ruby/provider/yard/docstring.rb

@@ -0,0 +1,162 @@
+module Inch
+  module Language
+    module Ruby
+      module Provider
+        module YARD
+          class Docstring
+            def initialize(text)
+              @text = text.to_s
+            end
+
+            def describes_internal_api?
+              first_line =~ /^Internal\:\ .+/
+            end
+
+            def describes_private_object?
+              first_line =~ /^Private\:\ .+/
+            end
+
+            def empty?
+              @text.strip.empty?
+            end
+
+            def contains_code_example?
+              !code_examples.empty?
+            end
+
+            def code_examples
+              @code_examples ||= parse_code_examples
+            end
+
+            def describes_parameter?(name)
+              return false if name.nil?
+              describe_parameter_regexps(name).any? do |pattern|
+                @text.index(pattern)
+              end
+            end
+
+            def mentions_parameter?(name)
+              return false if name.nil?
+              mention_parameter_regexps(name).any? do |pattern|
+                @text.index(pattern)
+              end
+            end
+
+            def mentions_return?
+              last_lines.any? do |line|
+                line =~ /^#{tomdoc_modifiers}Returns\ /
+              end
+            end
+
+            def describes_return?
+              last_lines.any? do |line|
+                line =~ /^#{tomdoc_modifiers}Returns\ (\w+\s){2,}/i ||
+                  line =~ /^#{tomdoc_modifiers}Returns\ (nil|nothing)\.*/i
+              end
+            end
+
+            def to_s
+              @text
+            end
+
+            private
+
+            def first_line
+              @first_line ||= @text.lines.to_a.first
+            end
+
+            # Returns the last lines of the docstring.
+            # @return [Array<String>] the last line and, if the last line(s) is
+            #   indented, the last unindented line
+            def last_lines
+              @last_lines ||= begin
+                list = []
+                @text.lines.to_a.reverse.each do |line|
+                  list << line
+                  break if line =~ /^\S/
+                end
+                list.reverse
+              end
+            end
+
+            def parse_code_examples
+              code_examples = []
+              example = nil
+              @text.lines.each do |line|
+                if line =~ /^\s*+$/
+                  code_examples << example if example
+                  example = []
+                elsif line =~ /^\ {2,}\S+/
+                  example << line if example
+                else
+                  code_examples << example if example
+                  example = nil
+                end
+              end
+              code_examples << example if example
+              code_examples.delete_if(&:empty?).map(&:join)
+            end
+
+            # Returns patterns in which method parameters are mentioned
+            # in inline docs.
+            #
+            # @param name [String] the name of the method parameter
+            # @return [Array<Regexp>]
+            def mention_parameter_patterns(name)
+              escaped_name = Regexp.escape(name)
+              type = /<[^>]+>/
+              [
+                escaped_name,
+                /#{escaped_name}#{type}/ # matches "param1<String,nil>"
+              ].map do |expr|
+                [
+                  /#{expr}\:\:/,            # param1::
+                  /\+#{expr}\+/,            # +param1+
+                  /\+#{expr}\+\:\:/,        # +param1+::
+                  /<tt>#{expr}<\/tt>/,      # <tt>param1</tt>
+                  /<tt>#{expr}<\/tt>\:\:/,  # <tt>param1</tt>::
+                  /^#{expr}\ \-\ /          # param1 -
+                ]
+              end.flatten
+            end
+
+            def describe_parameter_extra_regexps(name)
+              [
+                "#{name}::",
+                "+#{name}+::",
+                "<tt>#{name}</tt>::"
+              ].map do |pattern|
+                r = pattern.is_a?(Regexp) ? pattern : Regexp.escape(pattern)
+                /#{r}\n\ {2,}.+/m
+              end
+            end
+
+            def describe_parameter_regexps(name)
+              same_line_regexps =
+                mention_parameter_patterns(name).map do |pattern|
+                  r = pattern.is_a?(Regexp) ? pattern : Regexp.escape(pattern)
+                  /^#{r}\s?\S+/
+                end
+              same_line_regexps + describe_parameter_extra_regexps(name)
+            end
+
+            def mention_parameter_regexps(name)
+              mention_parameter_patterns(name).map do |pattern|
+                if pattern.is_a?(Regexp)
+                  pattern
+                else
+                  r = Regexp.escape(pattern)
+                  /\W#{r}\W/
+                end
+              end
+            end
+
+            def tomdoc_modifiers
+              /((Public|Private|Internal)\:\ )*/
+            end
+          end
+        end
+      end
+    end
+  end
+end