inch 0.1.3 → 0.1.4

data/lib/inch/evaluation/role/base.rb

@@ -1,6 +1,9 @@
 module Inch
   module Evaluation
+    # Role objects are assigned to evaluations of code objects. They describe
+    # the object they are attached to.
     module Role
+      # @abstract
       class Base
         attr_reader :object
 
@@ -9,33 +12,54 @@ module Inch
           @value = value
         end
 
-        # Override this method to that a max_score for the evaluation.
+        # Returns a maximal score for the object.
+        # The final score can not be higher than this.
+        # @note Override this method to that a max_score for the evaluation.
+        # @return [Float]
         def max_score
         end
 
-        # Override this method to that a min_score for the evaluation.
+        # Returns a minimal score for the object.
+        # The final score can not be lower than this.
+        # @note Override this method to that a min_score for the evaluation.
+        # @return [Float]
         def min_score
         end
 
         # Returns a score that will be added to the associated object's
         # overall score.
         #
-        # Override this method to that a score for the role.
+        # @note Override this method to assign a score for the role
+        # @return [Float]
         def score
           @value.to_f
         end
 
+        # Returns a potential score that would be added to the overall score
+        # if the object had implemented the Role's subject.
+        #
+        # @see Role::Missing
+        # @note Override this method to assign a potential score for the role
         # @return [Float]
-        #  a score that can be achieved by adding the missing thing mentioned
-        #  by the role
         def potential_score
           nil
         end
 
+        # Returns a priority that will be added to the associated object's
+        # overall priority.
+        #
+        # @note Override this method to assign a priority for the role
+        # @return [Fixnum]
         def priority
           0
         end
 
+        # Returns a suggestion to achieve the potential score that would be
+        # added to the overall score if the object had implemented the Role's
+        # subject.
+        #
+        # @see Role::Missing
+        # @return [Float]
         def suggestion
           nil
         end

data/lib/inch/evaluation/role/constant.rb

@@ -17,11 +17,6 @@ module Inch
             -1
           end
         end
-        class Protected < Object::Protected
-          def priority
-            -2
-          end
-        end
         class Private < Object::Private
           def priority
             -3

data/lib/inch/evaluation/role/object.rb

@@ -31,11 +31,7 @@ module Inch
 
         class Public < Base
           def priority
-            if object.type == :constant
-              -1
-            else
-              +2
-            end
+            +2
           end
         end
         class Protected < Base

data/lib/inch/evaluation/score_range.rb

@@ -1,9 +1,17 @@
 module Inch
   module Evaluation
+    # ScoreRange objects associate a range of scores with a grade,
+    # description, color etc.
+    #
+    # @see .new_score_ranges
     class ScoreRange < Struct.new(:range, :grade, :description, :color, :bg_color)
       # Returns code_objects that received a score with the defined +range+
       attr_reader :objects
 
+      # Assigns code_objects that received a score with the defined +range+
+      #
+      # @param arr [Array<CodeObject::Proxy::Base>]
+      # @return [Array<CodeObject::Proxy::Base>]
       def objects=(arr)
         arr.each { |o| o.grade = grade }
         @objects = arr
@@ -17,6 +25,10 @@ module Inch
       [0..0,    :U, "Undocumented", :color141, :color105],
     ]
 
+    # Returns newly instanciated score range objects based on 
+    # {SCORE_RANGE_ARGS}
+    #
+    # @return [Array<ScoreRange>]
     def self.new_score_ranges
       SCORE_RANGE_ARGS.map do |args|
         ScoreRange.new(*args)

data/lib/inch/rake/suggest.rb

@@ -9,6 +9,9 @@ module Inch
       attr_accessor :name
       attr_accessor :args
 
+      # @param name [String] name of the Rake task
+      # @param *args [Array] arguments to be passed to Suggest.run
+      # @param &block [Proc] optional, evaluated inside the task definition
       def initialize(name = "inch", *args, &block)
         @name = name
         @args = args

data/lib/inch/source_parser.rb

@@ -1,23 +1,49 @@
 module Inch
-  # Parses the source tree
+  # Parses the source tree (using YARD)
   class SourceParser
+    # Helper method to run an instance with the given +args+
+    #
+    # @see #run
+    # @return [SourceParser] the instance that ran
     def self.run(*args)
       parser = self.new
       parser.run(*args)
       parser
     end
 
+    # Returns all parsed objects as code object proxies
+    #
+    # @see CodeObject::Proxy.for
+    # @return [Array<CodeObject::Proxy::Base>]
     def all_objects
       @all_objects ||= all_parsed_objects.map do |o|
         CodeObject::Proxy.for(o)
       end.sort_by(&:path)
     end
 
+    # Returns the object with the given +path+
+    #
+    # @example
+    #
+    #   SourceParser.find_objects("Foo#bar")
+    #   # => returns code object proxy for Foo#bar
+    #
+    # @param path [String] partial path/name of an object
+    # @return [CodeObject::Proxy::Base]
     def find_object(path)
       all_objects.detect { |o| o.path == path }
     end
     alias :[] :find_object
 
+    # Returns all objects where the +path+ starts_with the given +path+
+    #
+    # @example
+    #
+    #   SourceParser.find_objects("Foo#")
+    #   # => returns code object proxies for all instance methods of Foo
+    #
+    # @param path [String] partial path/name of an object
+    # @return [Array<CodeObject::Proxy::Base>]
     def find_objects(path)
       all_objects.select { |o| o.path.start_with?(path) }
     end

data/lib/inch/version.rb

@@ -1,3 +1,3 @@
 module Inch
-  VERSION = "0.1.3"
+  VERSION = "0.1.4"
 end

data/test/fixtures/simple/lib/foo.rb

@@ -27,6 +27,12 @@ module Foo
     # @param p2 [String, nil] optionally param
     # @return [void]
     def method_with_full_doc(p1, p2 = nil)
+      many_lines = true
+      if true
+        if many_lines
+          true
+        end
+      end
     end
 
     # @param p1 [String] mandatory param

data/test/fixtures/simple/lib/role_namespaces.rb

@@ -3,6 +3,9 @@
 # @see PureNamespace
 PUBLIC_ROOT_CONSTANT = :foo
 
+PRIVATE_ROOT_CONSTANT = :foo
+private_constant :PRIVATE_ROOT_CONSTANT
+
 class String
   def foobar
     self + 'foobar!'
@@ -12,20 +15,29 @@ end
 module InchTest
   # You would want to use it like this:
   #
-  #  CodeExample.new
+  #   CodeExample.new
   #
   class CodeExample
   end
 
   # You would want to use it like this:
   #
-  #  CodeExample.new
+  #   MultipleCodeExamples.new
   #
-  #  CodeExample.new # => something
+  #   MultipleCodeExamples.new # => something
   #
   class MultipleCodeExamples
   end
 
+  # You would want to use it like this:
+  #
+  # @example
+  #   MultipleCodeExamples2.new
+  #   MultipleCodeExamples2.new # => something
+  #
+  class MultipleCodeExamples2
+  end
+
   module PureNamespace
   end
 

data/test/inch/cli/command/base_test.rb

@@ -0,0 +1,15 @@
+require File.expand_path(File.dirname(__FILE__) + '/../../../test_helper')
+
+describe ::Inch::CLI::Command::Console do
+  before do
+    @command = ::Inch::CLI::Command::Base.new
+  end
+
+  it "should implement some defaults" do
+    assert @command.name
+    assert @command.usage
+    assert @command.description
+
+    assert_raises(NotImplementedError) { @command.run("something") }
+  end
+end

data/test/inch/cli/command/inspect_test.rb

@@ -33,6 +33,15 @@ describe ::Inch::CLI::Command::Inspect do
     assert err.empty?, "there should be no errors"
   end
 
+
+  it "should output some info when run with a definitive object name" do
+    out, err = capture_io do
+      @command.run("Foo::Qux")
+    end
+    refute out.empty?, "there should be some output"
+    assert err.empty?, "there should be no errors"
+  end
+
   it "should output all children info when run with a partial name" do
     out, err = capture_io do
       @command.run("Foo::Bar#", "--no-color")

data/test/inch/cli/command/list_test.rb

@@ -6,6 +6,8 @@ describe ::Inch::CLI::Command::List do
     @command = ::Inch::CLI::Command::List
   end
 
+  include BaseListTests
+
   it "should run without args" do
     out, err = capture_io do
       @command.run()
@@ -59,3 +61,4 @@ describe ::Inch::CLI::Command::List do
     assert err.empty?, "there should be no errors"
   end
 end
+

data/test/inch/cli/command/options/base_list_test.rb

@@ -0,0 +1,50 @@
+require File.expand_path(File.dirname(__FILE__) + '/../../../../test_helper')
+
+describe ::Inch::CLI::Command::Options::BaseList do
+  it "should run parse without errors" do
+    @options = ::Inch::CLI::Command::Options::BaseList.new
+    @options.parse(["--no-color"])
+    assert_equal false, @options.show_all?
+    assert_equal [:public, :protected], @options.visibility
+    assert @options.namespaces.nil?
+    assert @options.undocumented.nil?
+    assert @options.depth.nil?
+  end
+  
+  it "should run parse twice without affecting the second run" do
+    @options = ::Inch::CLI::Command::Options::BaseList.new
+    @options.parse(["--no-public", "--no-protected", "--private"])
+    assert_equal [:private], @options.visibility
+
+    @options = ::Inch::CLI::Command::Options::BaseList.new
+    @options.parse(["--no-color"])
+    assert_equal [:public, :protected], @options.visibility
+  end
+
+  it "should interpret --all options" do
+    @options = ::Inch::CLI::Command::Options::BaseList.new
+    @options.parse(["--all"])
+    assert_equal true, @options.show_all?
+  end
+
+  it "should interpret visibility options" do
+    @options = ::Inch::CLI::Command::Options::BaseList.new
+    @options.parse(["--no-public", "--no-protected", "--private"])
+    assert_equal [:private], @options.visibility
+  end
+
+  it "should interpret options" do
+    @options = ::Inch::CLI::Command::Options::BaseList.new
+    @options.parse(["--no-namespaces", "--no-undocumented", "--depth=2"])
+    assert_equal :none, @options.namespaces
+    assert_equal :none, @options.undocumented
+    assert_equal 2, @options.depth
+  end
+
+  it "should interpret other options" do
+    @options = ::Inch::CLI::Command::Options::BaseList.new
+    @options.parse(["--only-namespaces", "--only-undocumented"])
+    assert_equal :only, @options.namespaces
+    assert_equal :only, @options.undocumented
+  end
+end

data/test/inch/cli/command/options/base_object_test.rb

@@ -0,0 +1,14 @@
+require File.expand_path(File.dirname(__FILE__) + '/../../../../test_helper')
+
+describe ::Inch::CLI::Command::Options::BaseObject do
+  it "should run parse without errors" do
+    @options = ::Inch::CLI::Command::Options::BaseObject.new
+    @options.parse(["--no-color"])
+  end
+
+  it "should interpret options" do
+    @options = ::Inch::CLI::Command::Options::BaseObject.new
+    @options.parse(["Foo", "Foo::Bar", "--no-color"])
+    assert_equal ["Foo", "Foo::Bar"], @options.object_names
+  end
+end

data/test/inch/cli/command/options/base_test.rb

@@ -0,0 +1,8 @@
+require File.expand_path(File.dirname(__FILE__) + '/../../../../test_helper')
+
+describe ::Inch::CLI::Command::Options::Base do
+  it "should run parse without errors" do
+    @options = ::Inch::CLI::Command::Options::Base.new
+    @options.parse(["--no-color"])
+  end
+end

data/test/inch/cli/command/suggest_test.rb

@@ -46,6 +46,17 @@ describe ::Inch::CLI::Command::Suggest do
     #assert err.empty?, "there should be no errors"
   end
   
+  it "should run with --objects switch" do
+    out, err = capture_io do
+      @command.run("lib/**/*.rb", "app/**/*.rb", "--objects=30")
+    end
+    refute out.empty?, "there should be some output"
+    assert err.empty?, "there should be no errors"
+    assert_match /\bFoo::Bar#method_with_wrong_doc\b/, out
+    assert_match /\bFoo::Bar#method_without_docstring\b/, out
+    assert_match /\bFoo::Bar#method_with_unstructured_doc\b/, out
+  end
+
   it "should give error when run with --unknown-switch" do
     out, err = capture_io do
       assert_raises(SystemExit) { @command.run("--unknown-switch") }

data/test/inch/cli/trace_helper_test.rb

@@ -0,0 +1,47 @@
+require File.expand_path(File.dirname(__FILE__) + '/../../test_helper')
+
+class Tracer
+  include ::Inch::CLI::TraceHelper
+end
+
+describe ::Inch::CLI::TraceHelper do
+  before do
+    @instance = Tracer.new
+  end
+
+  it "should trace" do
+    out, err = capture_io do
+      @instance.trace("Test")
+    end
+    refute out.empty?, "there should be no output"
+    assert err.empty?, "there should be no errors"
+  end
+
+  it "should trace header" do
+    out, err = capture_io do
+      @instance.trace_header("Test", :red)
+    end
+    refute out.empty?, "there should be no output"
+    assert err.empty?, "there should be no errors"
+  end
+
+  it "should trace debug if ENV variable is set" do
+    ENV['DEBUG'] = "1"
+    out, err = capture_io do
+      @instance.debug("Test")
+    end
+    ENV['DEBUG'] = nil
+    refute out.empty?, "there should be no output"
+    assert err.empty?, "there should be no errors"
+  end
+
+  it "should not trace debug if ENV variable is set" do
+    refute ENV['DEBUG']
+    out, err = capture_io do
+      @instance.debug("Test")
+    end
+    assert out.empty?, "there should be no output"
+    assert err.empty?, "there should be no errors"
+  end
+
+end

data/test/inch/code_object/proxy_test.rb

@@ -6,6 +6,16 @@ describe ::Inch::CodeObject::Proxy::Base do
     @source_parser = Inch::SourceParser.run(["lib/**/*.rb"])
   end
 
+  def test_inspect_gives_original_name
+    m = @source_parser.find_object("Foo::Bar#method_with_code_example")
+    assert_match /Foo::Bar#method_with_code_example/, m.inspect
+  end
+
+  def test_grade_is_not_nil
+    m = @source_parser.find_object("Foo::Bar#method_with_code_example")
+    assert m.grade
+  end
+
   def test_method_with_code_example
     m = @source_parser.find_object("Foo::Bar#method_with_code_example")
     assert m.has_code_example?