inch 0.5.0.rc3 → 0.5.0.rc4

data/lib/inch/language/nodejs/provider/jsdoc/parser.rb

@@ -0,0 +1,59 @@
+require "json"
+require "inch/language/nodejs/provider/jsdoc/object"
+
+module Inch
+  module Language
+    module Nodejs
+      module Provider
+        module JSDoc
+          # Parses the source tree (using JSDoc)
+          class Parser
+            attr_reader :parsed_objects
+
+            # Helper method to parse an instance with the given +args+
+            #
+            # @see #parse
+            # @return [CodeObject::Provider::JSDoc::Parser] the instance that ran
+            def self.parse(*args)
+              parser = new
+              parser.parse(*args)
+              parser
+            end
+
+            # @param dir [String] directory
+            # @param config [Inch::Config::Codebase] configuration for codebase
+            # @return [void]
+            def parse(dir, config)
+              Dir.chdir(dir) do
+                parse_objects(config.included_files, config.excluded_files,
+                              config.read_dump_file)
+              end
+            end
+
+            # @return [Array<YARD::Object::Base>]
+            def objects
+              pp @parsed_objects[10]
+              @objects ||= parsed_objects.map do |o|
+                JSDoc::Object.for(o) # unless IGNORE_TYPES.include?(o.type)
+              end.compact
+              puts "#{@objects.size} objects found."
+              puts "Rest of implementation: coming soon -.-"
+              exit 1
+            end
+
+            private
+
+            def parse_objects(paths, excluded, read_dump_file = nil)
+              if read_dump_file.nil?
+                output = %x(jsdoc --explain #{paths.join(' ')})
+              else
+                output = File.read(read_dump_file)
+              end
+              @parsed_objects = JSON[output]
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,197 @@
+require "forwardable"
+
+module Inch
+  module Language
+    module Ruby
+      # This is the base class for code object proxies.
+      # Code object proxies are via an attributes Hash and provide all methods
+      # necessary for the evaluation of its documentation.
+      #
+      # @abstract
+      module CodeObject
+        class Base < Inch::CodeObject::Proxy
+          def language
+            :ruby
+          end
+
+          # @return [Boolean] if the current object is an alias for something else
+          def alias?
+            !aliased_object.nil?
+          end
+
+          # @return [CodeObject::Proxy] the object the current object is an
+          #   alias of
+          def aliased_object
+            object_lookup.find(self[:aliased_object_fullname])
+          end
+
+          # @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
+            @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[:core?]
+          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!
+          #
+          # @return [Fixnum] the depth of the object in terms of namespace
+          def depth
+            self[:depth]
+          end
+
+          # @return [Docstring]
+          def docstring
+            self[:docstring]
+          end
+
+          def files
+            self[:files]
+          end
+
+          # Returns the name of the file where the object is declared first
+          # @return [String] a filename
+          def filename
+            # just checking the first file (which is the file where an object
+            # is first declared)
+            files.first
+          end
+
+          # @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?
+            !self[:aliases_fullnames].empty?
+          end
+
+          def has_children?
+            self[:has_children?]
+          end
+
+          def has_code_example?
+            self[:has_code_example?]
+          end
+
+          def has_doc?
+            self[:has_doc?]
+          end
+
+          def has_multiple_code_examples?
+            self[:has_multiple_code_examples?]
+          end
+
+          def has_unconsidered_tags?
+            self[:has_unconsidered_tags?]
+          end
+
+          def in_root?
+            self[:in_root?]
+          end
+
+          # @return [Boolean] +true+ if the object represents a method
+          def method?
+            self[:method?]
+          end
+
+          # @return [Boolean] +true+ if the object represents a namespace
+          def namespace?
+            self[:namespace?]
+          end
+
+          def original_docstring
+            self[:original_docstring]
+          end
+
+          # @return [Boolean] +true+ if the object was tagged not to be documented
+          def nodoc?
+            self[:nodoc?]
+          end
+
+          # @return [CodeObject::Proxy,nil] the parent of the current object
+          #   or +nil+
+          def parent
+            object_lookup.find(self[:parent_fullname])
+          end
+
+          def private?
+            self[:private?]
+          end
+
+          # @return [Boolean]
+          #   +true+ if the object or its parent is tagged as @private
+          def tagged_as_private?
+            self[:tagged_as_private?]
+          end
+
+          # @return [Boolean]
+          #   +true+ if the object or its parent is tagged as part of an
+          #   internal api
+          def tagged_as_internal_api?
+            self[:tagged_as_internal_api?]
+          end
+
+          def protected?
+            self[:protected?]
+          end
+
+          def public?
+            self[:public?]
+          end
+
+          def source
+            self[:source]
+          end
+
+          def type
+            self.class.to_s.gsub(/Object$/, "")
+          end
+
+          # @return [Boolean] +true+ if the object has no documentation at all
+          def undocumented?
+            self[:undocumented?]
+          end
+
+          # @return [Fixnum] the amount of tags not considered for this object
+          def unconsidered_tag_count
+            self[:unconsidered_tag_count]
+          end
+
+          def visibility
+            self[:visibility]
+          end
+        end
+      end
+    end
+  end
+end

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

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

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

@@ -0,0 +1,10 @@
+module Inch
+  module Language
+    module Ruby
+      module CodeObject
+        class ClassVariableObject < Base
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,10 @@
+module Inch
+  module Language
+    module Ruby
+      module CodeObject
+        class ConstantObject < Base
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,85 @@
+module Inch
+  module Language
+    module Ruby
+      module CodeObject
+        # Proxy class for methods
+        class MethodObject < Base
+          def constructor?
+            self[:constructor?]
+          end
+
+          def bang_name?
+            self[:bang_name?]
+          end
+
+          def getter?
+            self[:getter?]
+          end
+
+          def has_parameters?
+            !parameters.empty?
+          end
+
+          MANY_PARAMETERS_THRESHOLD = 3
+          def has_many_parameters?
+            parameters.size > MANY_PARAMETERS_THRESHOLD
+          end
+
+          MANY_LINES_THRESHOLD = 20
+          def has_many_lines?
+            # for now, this includes the 'def' line and comments
+            if source
+              size = source.lines.count
+              size > MANY_LINES_THRESHOLD
+            else
+              false
+            end
+          end
+
+          def parameter(name)
+            parameters.find { |p| p.name == name.to_s }
+          end
+
+          def parameters
+            @parameters ||= self[:parameters].map do |param_attr|
+              MethodParameterObject.new(param_attr)
+            end
+          end
+
+          def overridden?
+            self[:overridden?]
+          end
+
+          def overridden_method
+            @overridden_method ||=
+              object_lookup.find(self[:overridden_method_fullname])
+          end
+
+          def return_mentioned?
+            self[:return_mentioned?]
+          end
+
+          def return_described?
+            self[:return_described?]
+          end
+
+          def return_typed?
+            self[:return_typed?]
+          end
+
+          def setter?
+            self[:setter?]
+          end
+
+          def source
+            self[:source?]
+          end
+
+          def questioning_name?
+            self[:questioning_name?]
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,64 @@
+module Inch
+  module Language
+    module Ruby
+      module CodeObject
+        # Proxy class for method parameters
+        class MethodParameterObject
+          def initialize(attributes)
+            @attributes = attributes
+          end
+
+          def [](key)
+            @attributes[key]
+          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?
+            self[:block?]
+          end
+
+          # @return [Boolean] +true+ if an additional description given?
+          def described?
+            self[:described?]
+          end
+
+          # @return [Boolean] +true+ if the parameter is mentioned in the docs
+          def mentioned?
+            self[:mentioned?]
+          end
+
+          def name
+            self[:name]
+          end
+          alias_method :fullname, :name
+
+          # @return [Boolean] +true+ if the parameter is a splat argument
+          def splat?
+            self[:splat?]
+          end
+
+          # @return [Boolean] +true+ if the type of the parameter is defined
+          def typed?
+            self[:typed?]
+          end
+
+          # @return [Boolean] +true+ if the parameter is mentioned in the docs,
+          #   but not present in the method's signature
+          def wrongly_mentioned?
+            self[:wrongly_mentioned?]
+          end
+        end
+      end
+    end
+  end
+end

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

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