inch 0.5.0.rc3 → 0.5.0.rc4

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

@@ -0,0 +1,14 @@
+module Inch
+  module Language
+    module Ruby
+      module Provider
+        module YARD
+          module Object
+            class ClassObject < NamespaceObject
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,14 @@
+module Inch
+  module Language
+    module Ruby
+      module Provider
+        module YARD
+          module Object
+            class ClassVariableObject < Base
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,14 @@
+module Inch
+  module Language
+    module Ruby
+      module Provider
+        module YARD
+          module Object
+            class ConstantObject < Base
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,170 @@
+require "inch/language/ruby/provider/yard/object/method_signature"
+
+module Inch
+  module Language
+    module Ruby
+      module Provider
+        module YARD
+          module Object
+            # Proxy class for methods
+            class MethodObject < Base
+              UNUSABLE_RETURN_VALUES = %w(nil nothing undefined void)
+
+              def aliases_fullnames
+                object.aliases.map(&:path)
+              end
+
+              def bang_name?
+                name =~ /\!$/
+              end
+
+              def constructor?
+                name == :initialize
+              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_code_example?
+                signatures.any? { |s| s.has_code_example? }
+              end
+
+              def has_doc?
+                signatures.any? { |s| s.has_doc? }
+              end
+
+              def method?
+                true
+              end
+
+              def parameters
+                @parameters ||= signatures.map(&:parameters).flatten
+              end
+
+              def parameter(name)
+                parameters.find { |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
+
+              # Returns +true+ if a return value is described by it's type or
+              # mentioned in the docstring (e.g. "Returns a String").
+              def return_mentioned?
+                return_tags.any? do |t|
+                  !t.types.nil? && !t.types.empty? && !YARD.implicit_tag?(t, self)
+                end || docstring.mentions_return? && !implicit_docstring?
+              end
+
+              # Returns +true+ if a return value is described by words.
+              def return_described?
+                return_described_via_tag? ||
+                  docstring.describes_return? && !implicit_docstring?
+              end
+
+              def return_typed?
+                return_mentioned?
+              end
+
+              def setter?
+                name =~ /\=$/ && parameters.size == 1
+              end
+
+              def signatures
+                base = MethodSignature.new(self, nil)
+                overloaded = overload_tags.map do |tag|
+                  MethodSignature.new(self, tag)
+                end
+                if overloaded.any? { |s| s.same?(base) }
+                  overloaded
+                else
+                  [base] + overloaded
+                end
+              end
+
+              def questioning_name?
+                name =~ /\?$/
+              end
+
+              private
+
+              # Returns @return tags that are assigned to the getter
+              # corresponding to this setter.
+              #
+              # @return [Array<::YARD::Tag>]
+              def attributed_return_tags
+                if setter? && object.tags(:return).empty?
+                  method = corresponding_getter
+                  return method.object.tags(:return) if method
+                end
+                []
+              end
+
+              # @return [MethodObject,nil]
+              def corresponding_getter
+                clean_name = name.to_s.gsub(/(\=)$/, "")
+                parent.child(clean_name.to_sym)
+              end
+
+              # Returns +true+ if the docstring was generated by YARD.
+              def implicit_docstring?
+                YARD.implicit_docstring?(docstring, self)
+              end
+
+              # @return [Array<::YARD::Tag>]
+              def overload_tags
+                object.tags(:overload)
+              end
+
+              # @return [Array<::YARD::Tag>]
+              def overloaded_return_tags
+                overload_tags.map do |overload_tag|
+                  overload_tag.tag(:return)
+                end.compact
+              end
+
+              # @return [Array<::YARD::Tag>]
+              def return_tags
+                object.tags(:return) +
+                  overloaded_return_tags +
+                    attributed_return_tags
+              end
+
+              # Returns +true+ if a return value is described by words.
+              def return_described_via_tag?
+                return_tags.any? do |t|
+                  return_tag_describes_unusable_value?(t) ||
+                    !t.text.empty? && !YARD.implicit_tag?(t, self)
+                end
+              end
+
+              def return_tag_describes_unusable_value?(t)
+                return false if t.types.nil?
+                t.types.size == 1 &&
+                  UNUSABLE_RETURN_VALUES.include?(t.types.first)
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,94 @@
+module Inch
+  module Language
+    module Ruby
+      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 in_signature [String] how the parameter is noted in the
+              #   method's signature
+              # @param tag [YARD::Tags::Tag] the Tag object for the parameter
+              def initialize(method, name, in_signature, tag)
+                @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?
+                @in_signature.to_s =~ /^\&/
+              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?
+                @in_signature.to_s =~ /^\*/
+              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
+end

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

@@ -0,0 +1,120 @@
+module Inch
+  module Language
+    module Ruby
+      module Provider
+        module YARD
+          module Object
+            # Utility class to describe (overloaded) method signatures
+            class MethodSignature < Struct.new(:method, :yard_tag)
+              attr_reader :method, :docstring
+
+              # @param method [Provider::YARD::Object::MethodObject]
+              # @param yard_tag [::YARD::Tags::Tag,nil] if nil, the method's
+              #   normal signature is used
+              def initialize(method, yard_tag = nil)
+                @method = method
+                @yard_tag = yard_tag
+                @docstring =
+                  Provider::YARD::Docstring.new(relevant_object.docstring)
+              end
+
+              def all_signature_parameter_names
+                relevant_object.parameters.map(&:first)
+              end
+
+              def has_code_example?
+                if docstring.contains_code_example?
+                  true
+                else
+                  !relevant_object.tags(:example).empty?
+                end
+              end
+
+              def has_doc?
+                !docstring.empty? && !implicit_docstring?
+              end
+
+              def parameters
+                @parameters ||= all_parameter_names.map do |name|
+                  signature_name = in_signature(name)
+                  tag = parameter_tag(name) || parameter_tag(signature_name)
+                  MethodParameterObject.new(method, name, signature_name, tag)
+                end
+              end
+
+              # Returns the parameter with the given +name+.
+              # @param name [String,Symbol]
+              # @return [MethodParameterObject]
+              def parameter(name)
+                parameters.find { |p| p.name == name.to_s }
+              end
+
+              # Returns +true+ if the other signature is identical to self
+              # @param other [MethodSignature]
+              # @return [Boolean]
+              def same?(other)
+                all_signature_parameter_names ==
+                  other.all_signature_parameter_names
+              end
+
+              # Returns the actual signature of the method.
+              # @return [String]
+              def signature
+                relevant_object.signature.gsub(/^(def\ )/, "")
+              end
+
+              private
+
+              def all_parameter_names
+                all_names = all_signature_parameter_names +
+                  parameter_tags.map(&:name)
+                all_names.map do |name|
+                  normalize_parameter_name(name) if name
+                end.compact.uniq
+              end
+
+              # Returns +true+ if the docstring was generated by YARD
+              def implicit_docstring?
+                YARD.implicit_docstring?(docstring, method)
+              end
+
+              # Returns how the given parameter is noted in the method's
+              # signature.
+              #
+              # @param name [String] parameter name
+              # @return [String]
+              def in_signature(name)
+                possible_names = [name, "*#{name}", "&#{name}"]
+                (all_signature_parameter_names & possible_names).first
+              end
+
+              # Removes block, splat symbols, dollar sign,
+              # leading and trailing brackets from a given +name+
+              # (sometimes used to indicate optional parameters in overload
+              # signatures).
+              # @param name [String] parameter name
+              # @return [String]
+              def normalize_parameter_name(name)
+                name.gsub(/[\&\*\$\[\]]/, "")
+              end
+
+              def parameter_tag(param_name)
+                parameter_tags.find do |tag|
+                  tag.name == param_name
+                end
+              end
+
+              def parameter_tags
+                relevant_object.tags(:param)
+              end
+
+              def relevant_object
+                @yard_tag || method.object
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,14 @@
+module Inch
+  module Language
+    module Ruby
+      module Provider
+        module YARD
+          module Object
+            class ModuleObject < NamespaceObject
+            end
+          end
+        end
+      end
+    end
+  end
+end