inch 0.2.3 → 0.3.0.rc1

data/lib/inch/code_object/provider/yard/object/class_object.rb

@@ -0,0 +1,12 @@
+module Inch
+  module CodeObject
+    module Provider
+      module YARD
+        module Object
+          class ClassObject < NamespaceObject
+          end
+        end
+      end
+    end
+  end
+end

data/lib/inch/code_object/provider/yard/object/constant_object.rb

@@ -0,0 +1,12 @@
+module Inch
+  module CodeObject
+    module Provider
+      module YARD
+        module Object
+          class ConstantObject < Base
+          end
+        end
+      end
+    end
+  end
+end

data/lib/inch/code_object/provider/yard/object/method_object.rb

@@ -0,0 +1,126 @@
+module Inch
+  module CodeObject
+    module Provider
+      module YARD
+        module Object
+          # Proxy class for methods
+          class MethodObject < Base
+
+            def constructor?
+              name == :initialize
+            end
+
+            def bang_name?
+              name =~ /\!$/
+            end
+
+            def getter?
+              attr_info = object.attr_info || {}
+              read_info = attr_info[:read]
+              if read_info
+                read_info.path == fullname
+              else
+                parent.child(:"#{name}=")
+              end
+            end
+
+            def has_doc?
+              super && !implicit_docstring?
+            end
+
+            def has_alias?
+              !object.aliases.empty?
+            end
+
+            def method?
+              true
+            end
+
+            def parameters
+              @parameters ||= all_parameter_names.map do |name|
+                in_signature = signature_parameter_names.include?(name)
+                tag = parameter_tag(name)
+                MethodParameterObject.new(self, name, tag, in_signature)
+              end
+            end
+
+            def parameter(name)
+              parameters.detect { |p| p.name == name.to_s }
+            end
+
+            def overridden?
+              !!object.overridden_method
+            end
+
+            def overridden_method
+              return unless overridden?
+              @overridden_method ||= YARD::Object.for(object.overridden_method)
+            end
+
+            def overridden_method_fullname
+              return unless overridden?
+              overridden_method.fullname
+            end
+
+            def return_mentioned?
+              !!return_tag || docstring.mentions_return?
+            end
+
+            def return_described?
+              (return_tag && !return_tag.text.empty?) || docstring.describes_return?
+            end
+
+            def return_typed?
+              return_mentioned?
+            end
+
+            def setter?
+              name =~ /\=$/ && parameters.size == 1
+            end
+
+            def questioning_name?
+              name =~ /\?$/
+            end
+
+            private
+
+            def all_parameter_names
+              names = signature_parameter_names
+              names.concat parameter_tags.map(&:name)
+              names.compact.uniq
+            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
+
+            def parameter_tag(param_name)
+              parameter_tags.detect do |tag|
+                tag.name == param_name
+              end
+            end
+
+            def parameter_tags
+              object.tags(:param)
+            end
+
+            def return_tag
+              object.tags(:return).first
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/inch/code_object/provider/yard/object/method_parameter_object.rb

@@ -0,0 +1,88 @@
+module Inch
+  module CodeObject
+    module Provider
+      module YARD
+        module Object
+          # Proxy class for method parameters
+          class MethodParameterObject
+            attr_reader :name # @return [String]
+
+            # @param method [YARD::Object::MethodObject] the method the parameter belongs to
+            # @param name [String] the name of the parameter
+            # @param tag [YARD::Tags::Tag] the Tag object for the parameter
+            # @param in_signature [Boolean] +true+ if the method's signature contains the parameter
+            def initialize(method, name, tag, in_signature)
+              @method = method
+              @name = name
+              @tag = tag
+              @in_signature = in_signature
+            end
+
+            BAD_NAME_EXCEPTIONS = %w(id)
+            BAD_NAME_THRESHOLD = 3
+
+            # @return [Boolean] +true+ if the name of the parameter is uncommunicative
+            def bad_name?
+              return false if BAD_NAME_EXCEPTIONS.include?(name)
+              name.size < BAD_NAME_THRESHOLD || name =~ /[0-9]$/
+            end
+
+            # @return [Boolean] +true+ if the parameter is a block
+            def block?
+              name =~ /^\&/
+            end
+
+            # @return [Boolean] +true+ if an additional description given?
+            def described?
+              described_by_tag? || described_by_docstring?
+            end
+
+            # @return [Boolean] +true+ if the parameter is mentioned in the docs
+            def mentioned?
+              !!@tag || mentioned_by_docstring?
+            end
+
+            # @return [Boolean] +true+ if the parameter is a splat argument
+            def splat?
+              name =~ /^\*/
+            end
+
+            # @return [Boolean] +true+ if the type of the parameter is defined
+            def typed?
+              @tag && @tag.types && !@tag.types.empty?
+            end
+
+            # @return [Boolean] +true+ if the parameter is mentioned in the docs, but not present in the method's signature
+            def wrongly_mentioned?
+              mentioned? && !@in_signature
+            end
+
+            private
+
+            def described_by_tag?
+              @tag && @tag.text && !@tag.text.empty?
+            end
+
+            def described_by_docstring?
+              if @method.docstring.describes_parameter?(name)
+                true
+              else
+                unsplatted = name.gsub(/^[\&\*]/, '')
+                @method.docstring.describes_parameter?(unsplatted)
+              end
+            end
+
+            def mentioned_by_docstring?
+              if @method.docstring.mentions_parameter?(name)
+                true
+              else
+                unsplatted = name.gsub(/^[\&\*]/, '')
+                @method.docstring.mentions_parameter?(unsplatted)
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/inch/code_object/provider/yard/object/module_object.rb

@@ -0,0 +1,12 @@
+module Inch
+  module CodeObject
+    module Provider
+      module YARD
+        module Object
+          class ModuleObject < NamespaceObject
+          end
+        end
+      end
+    end
+  end
+end

data/lib/inch/code_object/provider/yard/object/namespace_object.rb

@@ -0,0 +1,47 @@
+module Inch
+  module CodeObject
+    module Provider
+      module YARD
+        module Object
+          # a namespace object can have methods and other namespace objects
+          # inside itself (e.g. classes and modules)
+          class NamespaceObject < Base
+            def attributes
+              object.class_attributes.values + object.instance_attributes.values
+            end
+
+            def children_fullnames
+              children.map(&:fullname)
+            end
+
+            def namespace?
+              true
+            end
+
+            def has_methods?
+              children.any?(&:method?)
+            end
+
+            def pure_namespace?
+              children.all?(&:namespace?)
+            end
+
+            # called by MethodObject#getter?
+            def child(name)
+              if children
+                children.detect { |child| child.name == name }
+              end
+            end
+
+            def children
+              object.children.map do |o|
+                YARD::Object.for(o)
+              end
+            end
+
+          end
+        end
+      end
+    end
+  end
+end

data/lib/inch/code_object/provider/yard/parser.rb

@@ -0,0 +1,54 @@
+module Inch
+  module CodeObject
+    module Provider
+      module YARD
+        # Parses the source tree (using YARD)
+        class Parser
+          DEFAULT_PATHS     = ["app/**/*.rb", "lib/**/*.rb"]
+          DEFAULT_EXCLUDED  = []
+
+          # Helper method to parse an instance with the given +args+
+          #
+          # @see #parse
+          # @return [CodeObject::Provider::YARD] the instance that ran
+          def self.parse(*args)
+            parser = self.new
+            parser.parse(*args)
+            parser
+          end
+
+          def parse(dir, paths, excluded)
+            old_dir = Dir.pwd
+            Dir.chdir dir
+            parse_yard_objects(paths, excluded)
+            inject_base_dir(dir)
+            Dir.chdir old_dir
+          end
+
+          def objects
+            @objects ||= parsed_objects.map do |o|
+              YARD::Object.for(o)
+            end
+          end
+
+          private
+
+          def parse_yard_objects(paths, excluded)
+            ::YARD::Registry.clear
+            ::YARD.parse(paths || DEFAULT_PATHS, excluded || DEFAULT_EXCLUDED)
+          end
+
+          def inject_base_dir(dir)
+            objects.each do |object|
+              object.base_dir = dir
+            end
+          end
+
+          def parsed_objects
+            ::YARD::Registry.all
+          end
+        end
+      end
+    end
+  end
+end

data/lib/inch/code_object/proxy.rb

@@ -7,14 +7,16 @@ module Inch
       class << self
         # Returns a Proxy object for the given +code_object+
         #
-        # @param code_object [YARD::CodeObject]
+        # @param code_object [YARD::Object::Base]
         # @return [CodeObject::Proxy::Base]
         def for(code_object)
           @cache ||= {}
           if proxy_object = @cache[cache_key(code_object)]
             proxy_object
           else
-            @cache[cache_key(code_object)] = class_for(code_object).new(code_object)
+            attributes = Converter.to_hash(code_object)
+            proxy_object = class_for(code_object).new(attributes)
+            @cache[cache_key(code_object)] = proxy_object
           end
         end
 
@@ -35,7 +37,7 @@ module Inch
         #
         # @return [String]
         def cache_key(code_object)
-          code_object.path
+          code_object.fullname
         end
       end
     end

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

@@ -6,60 +6,88 @@ module Inch
       # @abstract
       class Base
         extend Forwardable
-        include NodocHelper
-
-        # @return [YARD::CodeObjects::Base] the actual (YARD) code object
-        attr_reader :object
 
         # @return [Symbol]
         #   when objects are assigned to GradeLists, this grade is set to
         #   enable easier querying for objects of a certain grade
         attr_writer :grade
 
-        # Tags considered by wrapper methods like {#has_code_example?}
-        CONSIDERED_YARD_TAGS = %w(api example param private return)
-
-        # convenient shortcuts to (YARD) code object
-        def_delegators :object, :type, :path, :name, :namespace, :source, :source_type, :signature, :group, :dynamic, :visibility, :docstring
+        # @return [#find]
+        #  an object that responds to #find to look up objects by their
+        #  full name
+        attr_accessor :object_lookup
 
         # convenient shortcuts to evalution object
         def_delegators :evaluation, :score, :roles, :priority
 
-        # @param object [YARD::CodeObjects::Base] the actual (YARD) code object
-        def initialize(object)
-          @object = object
+        def initialize(attributes)
+          @attributes = attributes
         end
 
-        def api_tag?
-          !api_tag.nil?
+        # Returns the attribute for the given +key+
+        #
+        # @param key [Symbol]
+        def [](key)
+          @attributes[key]
         end
 
-        def api_tag
-          tag(:api) || (parent && parent.api_tag)
+        # @return [Evaluation::Base]
+        def evaluation
+          @evaluation ||= Evaluation::Proxy.for(self)
         end
 
-        # To be overridden
-        # @see Proxy::NamespaceObject
-        # @return [CodeObject::Proxy::Base,nil] the child inside the current object or +nil+
-        def child(name)
-          nil
+        # @return [Symbol]
+        def grade
+          @grade ||= Evaluation.new_grade_lists.detect { |range|
+                range.scores.include?(score)
+              }.grade
         end
 
-        # To be overridden
-        # @see Proxy::NamespaceObject
-        # @return [Array,nil] the children of the current object or +nil+
+        # @return [Boolean] +true+ if the object has an @api tag
+        def api_tag?
+          self[:api_tag?]
+        end
+
+        # @return [Array] the children of the current object
         def children
-          nil
+          @children ||= self[:children_fullnames].map do |fullname|
+            object_lookup.find(fullname)
+          end
+        end
+
+        # @return [Boolean] +true+ if the object represents a constant
+        def constant?
+          self[:constant?]
+        end
+
+        def core?
+          self[:api_tag?]
+        end
+
+        # The depth of the following is 4:
+        #
+        #   Foo::Bar::Baz#initialize
+        #    ^    ^    ^      ^
+        #    1 << 2 << 3  <<  4
+        #
+        # +depth+ answers the question "how many layers of code objects are
+        # above this one?"
+        #
+        # @note top-level counts, that's why Foo has depth 1!
+        #
+        # @param i [Fixnum] a counter for recursive method calls
+        # @return [Fixnum] the depth of the object in terms of namespace
+        def depth
+          self[:depth]
         end
 
         # @return [Docstring]
         def docstring
-          @docstring ||= Docstring.new(object.docstring)
+          self[:docstring]
         end
 
-        # @return [Evaluation::Base]
-        def evaluation
-          @evaluation ||= Evaluation.for(self)
+        def files
+          self[:files]
         end
 
         # Returns the name of the file where the object is declared first
@@ -67,146 +95,111 @@ module Inch
         def filename
           # just checking the first file (which is the file where an object
           # is first declared)
-          files.size > 0 ? files[0][0] : nil
+          files.first
         end
 
-        # @return [Symbol]
-        def grade
-          @grade ||= Evaluation.new_grade_lists.detect { |range|
-                range.scores.include?(score)
-              }.grade
+        # @return [String] the name of an object, e.g.
+        #   "Docstring"
+        def name
+          self[:name]
+        end
+
+        # @return [String] the fully qualified name of an object, e.g.
+        #   "Inch::CodeObject::Provider::YARD::Docstring"
+        def fullname
+          self[:fullname]
         end
 
         def has_alias?
-          !object.aliases.empty?
+          self[:has_alias?]
+        end
+
+        def has_children?
+          self[:has_children?]
         end
 
         def has_code_example?
-          !tags(:example).empty? ||
-            docstring.contains_code_example?
+          self[:has_code_example?]
         end
 
         def has_doc?
-          !docstring.empty?
+          self[:has_doc?]
         end
 
         def has_multiple_code_examples?
-          if tags(:example).size > 1 || docstring.code_examples.size > 1
-            true
-          else
-            if tag = tag(:example)
-              multi_code_examples?(tag.text)
-            elsif text = docstring.code_examples.first
-              multi_code_examples?(text)
-            else
-              false
-            end
-          end
+          self[:has_multiple_code_examples?]
         end
 
         def has_unconsidered_tags?
-          !unconsidered_tags.empty?
+          self[:has_unconsidered_tags?]
         end
 
         def in_root?
-          depth == 1
-        end
-
-        # The depth of the following is 4:
-        #
-        #   Foo::Bar::Baz#initialize
-        #    ^    ^    ^      ^
-        #    1 << 2 << 3  <<  4
-        #
-        # +depth+ answers the question "how many layers of code objects are
-        # above this one?"
-        #
-        # @note top-level counts, that's why Foo has depth 1!
-        #
-        # @param i [Fixnum] a counter for recursive method calls
-        # @return [Fixnum] the depth of the object in terms of namespace
-        def depth(i = 0)
-          if parent
-            parent.depth(i+1)
-          else
-            i
-          end
+          self[:in_root?]
         end
 
         # @return [Boolean] +true+ if the object represents a method
         def method?
-          false
+          self[:method?]
         end
 
         # @return [Boolean] +true+ if the object represents a namespace
         def namespace?
-          false
+          self[:namespace?]
+        end
+
+        # @return [Boolean] +true+ if the object was tagged not to be documented
+        def nodoc?
+          self[:nodoc?]
         end
 
         # @return [Array,nil] the parent of the current object or +nil+
         def parent
-          Proxy.for(object.parent) if object.parent
+          object_lookup.find( self[:parent_fullname] )
         end
 
         def private?
-          visibility == :private
+          self[:private?]
         end
 
         # @return [Boolean]
         #   +true+ if the object or its parent is tagged as @private
         def private_tag?
-          !private_tag.nil?
-        end
-
-        def private_tag
-          tag(:private) || (parent && parent.private_tag)
+          self[:private_tag?]
         end
 
         def private_api_tag?
-          api_tag && api_tag.text == 'private'
+          self[:private_api_tag?]
         end
 
         def protected?
-          visibility == :protected
+          self[:protected?]
         end
 
         def public?
-          visibility == :public
+          self[:public?]
         end
 
-        # @return [Boolean] +true+ if the object has no documentation at all
-        def undocumented?
-          docstring.empty? && tags.empty?
+        def source
+          self[:source]
         end
 
-        # @return [Array]
-        #   YARD tags that are not already covered by other wrapper methods
-        def unconsidered_tags
-          @unconsidered_tags ||= tags.reject do |tag|
-              CONSIDERED_YARD_TAGS.include?(tag.tag_name)
-            end
-        end
-
-        def inspect
-          "#<#{self.class.to_s}: #{path}>"
+        # @return [Boolean] +true+ if the object has no documentation at all
+        def undocumented?
+          self[:undocumented?]
         end
 
-        protected
-
-        def multi_code_examples?(text)
-          text.scan(/\b(#{Regexp.escape(name)})[^_0-9\!\?]/m).size > 1
+        # @return [Fixnum] the amount of tags not considered for this object
+        def unconsidered_tag_count
+          self[:unconsidered_tag_count]
         end
 
-        def tag(name)
-          tags(name).first
+        def visibility
+          self[:visibility]
         end
 
-        def tags(name = nil)
-          object.tags(name)
-        rescue YARD::CodeObjects::ProxyMethodError
-          # this error is raised by YARD
-          # see broken.rb in test fixtures
-          []
+        def inspect
+          "#<#{self.class.to_s}: #{fullname}>"
         end
       end
     end