inch 0.1.4 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 94f45218f025da4fe625a569967db6d85e9231a0
-  data.tar.gz: 481b2138c2c48c35e1ca884e078d8265e578e39b
+  metadata.gz: cf840afb1d2d50573095b6a0592280e814d4329b
+  data.tar.gz: 95f117197464c1d151531ec48a43a90d4260341b
 SHA512:
-  metadata.gz: 9d91370b78a36eb2a5fbd9541109a2b4bc5f97d6b67e3ce0de0cf9d8f22617821a9cd359dae170de49a6a80dde0e79e8437556e2a800c331d0bd0c45b96ab429
-  data.tar.gz: c47ca4717186e9ed78161c3db7baa2742c1aac96a8208f0cae4e08c2b81a75bafe42fd23f356680180165b2dbe94cf69855c59a1fdfa0d3683ec2d79bac37e2b
+  metadata.gz: c58bc5692ce925bb99f44c885562a4c648289ca9a8331e255cf40b6718d8707775bacb30c37df19f86d462abfa9bad420c34f1751d8b90778f7f699336ee5b06
+  data.tar.gz: ccbb7641f546e75111cd698187ad1ad79c50ac5dc843b68481815649e54ee32758ad57f4200fe25281ec9e270ae4410a8f94b93334ccc4a18c8209286cc0d58e

data/TODOS.md

@@ -7,10 +7,12 @@
   visibility options
 * Add support for multiple signatures for methods
   (realized via the @overload tag in YARD)
+
 * Think about implicit cases in terms of evaluation:
-  * constructors without docstring/return_type
-  * ?-methods with a return description
+  * constructors and ?-methods are automatically assigned a @return tag
+  * attr_* methods are automatically assigned a docstring and @param tag
+
 * Think about limiting the number of `B`-objects in `inch suggest`
   `inch suggest` shows too many `B`s even though there are still undocumented
   objects in the codebase. this becomes a problem, when one thinks of `B` as
-  "good enough", which Inch itself suggests.
+  "good enough", which Inch itself suggests.

data/bin/inch

@@ -6,11 +6,16 @@ Signal.trap("INT") do
   exit 1
 end
 
-path = __FILE__
-while File.symlink?(path)
-  path = File.expand_path(File.readlink(path), File.dirname(path))
+# @return [String] the path to the 'lib' directory of Inch
+def find_lib_path
+  path = __FILE__
+  while File.symlink?(path)
+    path = File.expand_path(File.readlink(path), File.dirname(path))
+  end
+  File.join(File.dirname(File.expand_path(path)), '..', 'lib')
 end
-$:.unshift(File.join(File.dirname(File.expand_path(path)), '..', 'lib'))
+
+$LOAD_PATH.unshift(find_lib_path)
 
 require 'inch'
 

data/inch.gemspec

@@ -13,16 +13,21 @@ Gem::Specification.new do |spec|
   spec.homepage      = "http://trivelop.de/inch/"
   spec.license       = "MIT"
 
-  spec.files         = `git ls-files -z`.split("\x0")
+  all_files = `git ls-files -z`.split("\x0")
+  files_without_dev_commands = all_files.select do |f|
+    f !~ /cli\/command\/.*(console|inspect)/
+  end
+
+  spec.files         = files_without_dev_commands
   spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
   spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
   spec.require_paths = ["lib"]
 
   spec.add_development_dependency "bundler", "~> 1.5"
   spec.add_development_dependency "rake"
+  spec.add_development_dependency "pry"
 
-  spec.add_dependency "yard", "~> 0.8.7"
+  spec.add_dependency 'sparkr', ">= 0.2.0"
   spec.add_dependency "term-ansicolor"
-  spec.add_dependency 'sparkr', "~> 0.2.0"
-  spec.add_dependency "pry"
+  spec.add_dependency "yard", "~> 0.8.7"
 end

data/lib/inch.rb

@@ -7,4 +7,5 @@ require_relative 'inch/core_ext'
 require_relative 'inch/source_parser'
 require_relative 'inch/code_object'
 require_relative 'inch/evaluation'
+require_relative 'inch/config'
 require_relative 'inch/cli'

data/lib/inch/cli.rb

@@ -22,3 +22,9 @@ require_relative 'cli/trace_helper'
 require_relative 'cli/yardopts_helper'
 require_relative 'cli/command'
 require_relative 'cli/command_parser'
+
+console_rb = File.join(File.dirname(__FILE__), 'cli', 'command', 'console.rb')
+if File.exists?(console_rb)
+  require_relative 'cli/command/console'
+  require_relative 'cli/command/inspect'
+end

data/lib/inch/cli/command.rb

@@ -2,8 +2,6 @@ require_relative 'command/base'
 require_relative 'command/base_list'
 require_relative 'command/base_object'
 
-require_relative 'command/console'
-require_relative 'command/inspect'
 require_relative 'command/list'
 require_relative 'command/show'
 require_relative 'command/stats'
@@ -13,16 +11,12 @@ require_relative 'command/options/base'
 require_relative 'command/options/base_list'
 require_relative 'command/options/base_object'
 
-require_relative 'command/options/console'
-require_relative 'command/options/inspect'
 require_relative 'command/options/list'
 require_relative 'command/options/show'
 require_relative 'command/options/stats'
 require_relative 'command/options/suggest'
 
 require_relative 'command/output/base'
-require_relative 'command/output/console'
-require_relative 'command/output/inspect'
 require_relative 'command/output/list'
 require_relative 'command/output/show'
 require_relative 'command/output/stats'

data/lib/inch/cli/command_parser.rb

@@ -44,8 +44,6 @@ module Inch
       end
 
       self.commands = {
-        :console => Command::Console,
-        :inspect => Command::Inspect,
         :list => Command::List,
         :show => Command::Show,
         :stats => Command::Stats,

data/lib/inch/code_object/nodoc_helper.rb

@@ -8,7 +8,7 @@ module Inch
       # @note Doesnot recognize ":startdoc:" and ":stopdoc:"
       #
       def nodoc?
-        object.tag(:private) || nodoc_comment?
+        private_tag? || nodoc_comment?
       end
 
       NO_DOC_REGEX = /#\s*\:nodoc\:/

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

@@ -8,7 +8,7 @@ module Inch
         extend Forwardable
         include NodocHelper
 
-        # the actual (YARD) code object
+        # @return [YARD::CodeObjects::Base] the actual (YARD) code object
         attr_accessor :object
 
         # @return [Symbol]
@@ -17,7 +17,7 @@ module Inch
         attr_writer :grade
 
         # Tags considered by wrapper methods like {#has_code_example?}
-        CONSIDERED_YARD_TAGS = %w(example param private return)
+        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
@@ -25,10 +25,15 @@ module Inch
         # convenient shortcuts to evalution object
         def_delegators :evaluation, :score, :roles, :priority
 
+        # @param object [YARD::CodeObjects::Base] the actual (YARD) code object
         def initialize(object)
           self.object = object
         end
 
+        def api_tag?
+          !object.tag(:api).nil? || (parent && parent.api_tag?)
+        end
+
         # To be overridden
         # @see Proxy::NamespaceObject
         # @return [Array,nil] the children of the current object or +nil+
@@ -36,10 +41,12 @@ module Inch
           nil
         end
 
+        # @return [Docstring]
         def docstring
           @docstring ||= Docstring.new(object.docstring)
         end
 
+        # @return [Evaluation::Base]
         def evaluation
           @evaluation ||= Evaluation.for(self)
         end
@@ -52,6 +59,7 @@ module Inch
           files.size > 0 ? files[0][0] : nil
         end
 
+        # @return [Symbol]
         def grade
           @grade ||= Evaluation.new_score_ranges.detect { |range|
                 range.range.include?(score)
@@ -133,8 +141,15 @@ module Inch
           visibility == :private
         end
 
+        # @return [Boolean]
+        #   +true+ if the object or its parent is tagged as @private
         def private_tag?
-          !!object.tag(:private)
+          !object.tag(:private).nil? || (parent && parent.private_tag?)
+        end
+
+        def private_api_tag?
+          tag = object.tag(:api)
+          tag.text == 'private'
         end
 
         def protected?

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

@@ -3,6 +3,11 @@ module Inch
     module Proxy
       # Proxy class for methods
       class MethodObject < Base
+
+        def constructor?
+          name == :initialize
+        end
+        
         def comment_and_abbrev_source
           comments.join('') + abbrev_source
         end

data/lib/inch/config.rb

@@ -0,0 +1,53 @@
+module Inch
+  module Evaluation
+
+    ConstantObject.criteria do
+      docstring           1.0
+
+      # optional:
+      unconsidered_tag    0.2
+    end
+
+    ClassObject.criteria do
+      docstring           1.0
+
+      # optional:
+      code_example_single 0.1
+      code_example_multi  0.2
+      unconsidered_tag    0.2
+    end
+
+    ModuleObject.criteria do
+      docstring           1.0
+
+      # optional:
+      code_example_single 0.1
+      code_example_multi  0.2
+      unconsidered_tag    0.2
+    end
+
+    MethodObject.criteria do
+      docstring           0.5
+      parameters          0.4
+      return_type         0.1
+      return_description  0.3
+
+      if object.constructor? || object.questioning_name?
+        parameters          parameters + return_type
+        return_type         0.0
+      end
+
+      unless object.has_parameters?
+        return_description  docstring + parameters
+        docstring           docstring + parameters
+        parameters          0.0
+      end
+
+      # optional:
+      code_example_single 0.1
+      code_example_multi  0.25
+      unconsidered_tag    0.2
+    end
+
+  end
+end

data/lib/inch/evaluation.rb

@@ -13,8 +13,8 @@ module Inch
   end
 end
 
+require_relative 'evaluation/criteria'
 require_relative 'evaluation/file'
-
 require_relative 'evaluation/score_range'
 
 require_relative 'evaluation/role/base'

data/lib/inch/evaluation/base.rb

@@ -9,29 +9,36 @@ module Inch
 
       TAGGED_SCORE = 20 # assigned per unconsidered tag
 
-
+      # @return [CodeObject::Proxy::Base]
       attr_accessor :object
+
       attr_reader :min_score, :max_score
 
+      # @param object [CodeObject::Proxy::Base]
       def initialize(object)
         self.object = object
         @roles = []
         evaluate
       end
 
+      # Evaluates the objects and assigns roles
+      # @abstract
       def evaluate
       end
 
+      # @return [Float]
       def max_score
         arr = @roles.map(&:max_score).compact
         [MAX_SCORE].concat(arr).min
       end
 
+      # @return [Float]
       def min_score
         arr = @roles.map(&:min_score).compact
         [MIN_SCORE].concat(arr).max
       end
 
+      # @return [Float]
       def score
         value = @roles.inject(0) { |sum,r| sum + r.score.to_f }
         if value < min_score
@@ -43,19 +50,56 @@ module Inch
         end
       end
 
+      # @return [Fixnum]
       def priority
         @roles.inject(0) { |sum,r| sum + r.priority.to_i }
       end
 
+      # @return [Array<Evaluation::Role::Base>]
       def roles
         @roles
       end
 
+      class << self
+        attr_reader :criteria_map
+
+        # Defines the weights during evaluation for different criteria
+        #
+        #   MethodObject.criteria do
+        #     docstring           0.5
+        #     parameters          0.4
+        #     return_type         0.1
+        #
+        #     if object.constructor?
+        #       parameters        0.5
+        #       return_type       0.0
+        #     end
+        #   end
+        #
+        # @return [void]
+        def criteria(&block)
+          @criteria_map ||= {}
+          @criteria_map[to_s] ||= Criteria.new(&block)
+        end
+      end
+
       protected
 
       def add_role(role)
         @roles << role
       end
+
+      def criteria
+        @criteria ||= begin
+          c = self.class.criteria_map[self.class.to_s]
+          c.evaluate(object)
+          c
+        end
+      end
+
+      def score_for(criteria_name)
+        criteria.send(criteria_name) * MAX_SCORE
+      end
     end
   end
 end

data/lib/inch/evaluation/constant_object.rb

@@ -1,20 +1,25 @@
 module Inch
   module Evaluation
     class ConstantObject < Base
-      DOC_SCORE = MAX_SCORE
-
       def evaluate
         if object.has_doc?
-          add_role Role::Constant::WithDoc.new(object, DOC_SCORE)
+          add_role Role::Constant::WithDoc.new(object, score_for(:docstring))
         else
-          add_role Role::Constant::WithoutDoc.new(object, DOC_SCORE)
+          add_role Role::Constant::WithoutDoc.new(object, score_for(:docstring))
         end
         if object.nodoc?
           add_role Role::Constant::TaggedAsNodoc.new(object)
         end
+        if object.api_tag?
+          if object.private_api_tag?
+            add_role Role::Object::TaggedAsPrivateAPI.new(object)
+          else
+            add_role Role::Object::TaggedAsAPI.new(object)
+          end
+        end
         if object.has_unconsidered_tags?
           count = object.unconsidered_tags.size
-          add_role Role::Object::Tagged.new(object, TAGGED_SCORE * count)
+          add_role Role::Object::Tagged.new(object, score_for(:unconsidered_tag) * count)
         end
         if object.in_root?
           add_role Role::Constant::InRoot.new(object)

data/lib/inch/evaluation/criteria.rb

@@ -0,0 +1,38 @@
+module Inch
+  module Evaluation
+    class Criteria
+      attr_reader :object
+
+      def initialize(&block)
+        @block = block
+      end
+
+      def evaluate(object)
+        @object = object
+        instance_eval(&@block)
+      end
+
+      NAMES = %w(
+        docstring
+        parameters
+        return_type
+        return_description
+        code_example_single
+        code_example_multi
+        unconsidered_tag
+        )
+
+      NAMES.each do |name|
+        class_eval """
+          def #{name}(value = nil)
+            if value.nil?
+              @#{name}.to_f
+            else
+              @#{name} = value
+            end
+          end
+        """
+      end
+    end
+  end
+end