inch 0.0.1 → 0.1.0

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

@@ -0,0 +1,58 @@
+module Inch
+  module Evaluation
+    module Role
+      module Namespace
+        class WithChildren < Base
+          # This role doesnot assign a score.
+          def score
+            0
+          end
+
+          # This role sets a max_score.
+          def max_score
+            # @value.to_f
+          end
+        end
+        class WithManyChildren < Base
+          # +priority
+          def priority
+            +1
+          end
+        end
+        class WithManyAttributes < Base
+          # +priority
+          def priority
+            +1
+          end
+        end
+
+        class WithoutChildren < Base
+        end
+        class WithoutMethods < Base
+          # --priority
+          def priority
+            -2
+          end
+        end
+        # A 'pure' namespace has only namespaces as children
+        class Pure < Base
+          # --priority
+          def priority
+            -2
+          end
+        end
+        # A 'core' namespace is a class or module that is part of the Ruby
+        # core. It might appear in the object tree when monkey-patching
+        # functionality.
+        # But just because we patch Hash does not mean we need to document
+        # the Hash class itself.
+        class Core < Base
+          # --priority
+          def priority
+            -7
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,64 @@
+module Inch
+  module Evaluation
+    module Role
+      module Object
+        class WithDoc < Base
+        end
+        class WithoutDoc < Missing
+          def suggestion
+            "Add a comment describing the #{object_type}"
+          end
+        end
+
+        # Tagged means tagged in an unconsidred way, i.e. YARD tags not
+        # considered by Inch. Since these tags are parsed from the docstring
+        # the object seems undocumented to Inch.
+        class Tagged < Base
+          def priority
+            -1
+          end
+        end
+        class TaggedAsNodoc < Base
+          def priority
+            -7
+          end
+        end
+        class InRoot < Base
+          def priority
+            +3
+          end
+        end
+
+        class Public < Base
+          def priority
+            if object.type == :constant
+              -1
+            else
+              +2
+            end
+          end
+        end
+        class Protected < Base
+          def priority
+            +1
+          end
+        end
+        class Private < Base
+          def priority
+            -2
+          end
+        end
+
+        class WithCodeExample < Base
+        end
+        class WithMultipleCodeExamples < Base
+        end
+        class WithoutCodeExample < Missing
+          def suggestion
+            "Add a code example (optional)"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/inch/evaluation/score_range.rb

@@ -0,0 +1,26 @@
+module Inch
+  module Evaluation
+    class ScoreRange < Struct.new(:range, :grade, :description, :color, :bg_color)
+      # Returns code_objects that received a score with the defined +range+
+      attr_reader :objects
+
+      def objects=(arr)
+        arr.each { |o| o.grade = grade }
+        @objects = arr
+      end
+    end
+
+    SCORE_RANGE_ARGS = [
+      [80..100, :A, "Seems really good", :green],
+      [50...80, :B, "Proper documentation present", :yellow],
+      [1...50,  :C, "Needs work", :red],
+      [0..0,    :U, "Undocumented", :color141, :color105],
+    ]
+
+    def self.new_score_ranges
+      SCORE_RANGE_ARGS.map do |args|
+        ScoreRange.new(*args)
+      end
+    end
+  end
+end

data/lib/inch/rake.rb

@@ -0,0 +1 @@
+require_relative 'rake/suggest'

data/lib/inch/rake/suggest.rb

@@ -0,0 +1,26 @@
+# encoding: utf-8
+
+require 'rake'
+require 'rake/tasklib'
+
+module Inch
+  module Rake
+    class Suggest < ::Rake::TaskLib
+      attr_accessor :name
+      attr_accessor :args
+
+      def initialize(name = "inch", *args, &block)
+        @name = name
+        @args = args
+        block.call(self) if block
+
+        desc "Suggest objects to add documention to"
+        task(@name) { suggest }
+      end
+
+      def suggest
+        CLI::Command::Suggest.run(*@args)
+      end
+    end
+  end
+end

data/lib/inch/source_parser.rb

@@ -0,0 +1,36 @@
+module Inch
+  # Parses the source tree
+  class SourceParser
+    def self.run(*args)
+      parser = self.new
+      parser.run(*args)
+      parser
+    end
+
+    def all_objects
+      @all_objects ||= all_parsed_objects.map do |o|
+        CodeObject::Proxy.for(o)
+      end.sort_by(&:path)
+    end
+
+    def find_object(path)
+      all_objects.detect { |o| o.path == path }
+    end
+    alias :[] :find_object
+
+    def find_objects(path)
+      all_objects.select { |o| o.path.start_with?(path) }
+    end
+
+    def run(paths, excluded = [])
+      YARD::Registry.clear
+      YARD.parse(paths, excluded)
+    end
+
+    private
+
+    def all_parsed_objects
+      YARD::Registry.all
+    end
+  end
+end

data/lib/inch/version.rb

@@ -1,3 +1,3 @@
 module Inch
-  VERSION = "0.0.1"
+  VERSION = "0.1.0"
 end

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

@@ -0,0 +1,87 @@
+# The module 'Foo' has a doc string (this), but the class
+# 'Foo::Bar' does not.
+module Foo
+  class Bar
+    # This is an example:
+    #
+    #   method_with_code_example() # => some value
+    #
+    # @param p1 [String] mandatory param
+    # @param p2 [String, nil] optionally param
+    # @return [void]
+    def method_with_code_example(p1, p2 = nil)
+    end
+
+    # This is an example:
+    #
+    # @example
+    #   method_with_code_example() # => some value
+    #
+    # @param p1 [String] mandatory param
+    # @param p2 [String, nil] optionally param
+    # @return [void]
+    def method_with_code_example2(p1, p2 = nil)
+    end
+
+    #
+    # Options: noop verbose force
+    #
+    # Changes owner and group on the named files (in +list+)
+    # to the user +user+ and the group +group+ recursively.
+    # +user+ and +group+ may be an ID (Integer/String) or
+    # a name (String).  If +user+ or +group+ is nil, this
+    # method does not change the attribute.
+    #
+    #   object.method_with_examples 1, 'www', 'www', '/var/www/htdocs'
+    #   object.method_with_examples 2, 'cvs', 'cvs', :verbose => true
+    #
+    def method_with_examples(user, group, list, options = {})
+    end
+
+    #
+    # Options: noop verbose force
+    #
+    # Changes owner and group on the named files (in +list+)
+    # to the user +user+ and the group +group+ recursively.
+    # +user+ and +group+ may be an ID (Integer/String) or
+    # a name (String).  If +user+ or +group+ is nil, this
+    # method does not change the attribute.
+    #
+    # @example
+    #   object.method_with_tagged_example 1, 'www', 'www', '/var/www/htdocs'
+    #   object.method_with_tagged_example 2, 'cvs', 'cvs', :verbose => true
+    #
+    def method_with_tagged_example(user, group, list, options = {})
+    end
+
+    #
+    # Options: noop verbose force
+    #
+    # Changes owner and group on the named files (in +list+)
+    # to the user +user+ and the group +group+ recursively.
+    # +user+ and +group+ may be an ID (Integer/String) or
+    #
+    # @example
+    #   object.method_with_examples 1, 'www', 'www', '/var/www/htdocs'
+    #
+    # a name (String).  If +user+ or +group+ is nil, this
+    # method does not change the attribute.
+    #
+    # @example
+    #   object.method_with_examples 2, 'cvs', 'cvs', :verbose => true
+    #
+    def method_with_2tagged_examples(user, group, list, options = {})
+    end
+
+    # Changes owner and group on the named files (in +list+)
+    #
+    #   object.method_with_one_example_other :similar
+    #   object.method_with_one_example 'www', 'www', '/var/www/htdocs'
+    #   # => 'cvs'
+    #
+    # No code.
+    #
+    def method_with_one_example
+    end
+  end
+end

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

@@ -0,0 +1,17 @@
+class Foo
+  # A complicated method
+  def complicated(o, i, *args, &block)
+    # ... snip ...
+  end
+
+  # An example of a method that takes a parameter (+param1+)
+  # and does nothing.
+  #
+  # Returns nil
+  def nothing(param1)
+  end
+
+  def filename
+    "#{self.class}_#{id}.foo"
+  end
+end

data/test/fixtures/simple/README

@@ -0,0 +1,25 @@
+# Inch 'simple' fixture
+
+Here goes the fixture description
+
+## Installation
+
+Or install it yourself as:
+
+    $ gem install inch
+
+## Usage
+
+    $ cd test/fixtures/simple
+
+    $ be inch
+
+TODO: Write better usage instructions here
+
+## Contributing
+
+1. Fork it ( http://github.com/rrrene/inch/fork )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

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

@@ -0,0 +1,10 @@
+module Foo
+  # The problem here is that the @param tag is not given the name of the
+  # parameter it documents.
+  #
+  # @param [Encoding]
+  # @return [String]
+  def method_with_wrong_param_tag(e)
+
+  end
+end

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

@@ -0,0 +1,214 @@
+# The module 'Foo' has a doc string (this), but the class
+# 'Foo::Bar' does not.
+module Foo
+  class Bar
+    def method_without_doc
+    end
+
+    # Provides an example of a missing described parameter.
+    #
+    # @param param1 [String]
+    # @param param2 [String, nil]
+    # @return [void]
+    def method_with_missing_param_doc(param1, param2, param3)
+    end
+
+    # Provides an example of a wrongly described parameter.
+    #
+    # @param param1 [String]
+    # @param param4 [String, nil]
+    # @return [void]
+    def method_with_wrong_doc(param1, param2, param3)
+    end
+
+    # Provides an example of a fully described method.
+    #
+    # @param p1 [String] mandatory param
+    # @param p2 [String, nil] optionally param
+    # @return [void]
+    def method_with_full_doc(p1, p2 = nil)
+    end
+
+    # @param p1 [String] mandatory param
+    # @param p2 [String, nil] optionally param
+    # @return [void]
+    def method_without_docstring(p1, p2 = nil)
+    end
+
+    # @return [void]
+    def method_without_params_or_docstring
+    end
+
+    # Provides an example of a method without parameters
+    # missing the return type.
+    #
+    def method_without_params_or_return_type
+    end
+
+    # An example of a method using RDoc rather than YARD.
+    #
+    # == Parameters:
+    # param1::
+    #   A Symbol declaring some markup language like `:md` or `:html`.
+    #
+    # == Returns:
+    # A string in the specified format.
+    #
+    def method_with_rdoc_doc(param1 = :html)
+    end
+
+    # Another example of a method using RDoc rather than YARD.
+    #
+    # Params:
+    # +param1+:: param1 line string to be executed by the system
+    # +param2+:: +Proc+ object that takes a pipe object as first and only param (may be nil)
+    # +param3+:: +Proc+ object that takes a pipe object as first and only param (may be nil)
+    def method_with_other_rdoc_doc(param1, param2, param3)
+    end
+
+    # An example of a method that takes a parameter (+param1+)
+    # and does nothing. But the previous sentence mentions said
+    # parameter.
+    #
+    def method_with_unstructured_doc(param1)
+    end
+
+    # Just because format_html is mentioned here, does not mean
+    # the first parameter is mentioned.
+    #
+    def method_with_unstructured_doc_missing_params(format)
+    end
+
+    # This is an example:
+    #
+    #   method_with_code_example() # => some value
+    #
+    # @param p1 [String] mandatory param
+    # @param p2 [String, nil] optionally param
+    # @return [void]
+    def method_with_code_example(p1, p2 = nil)
+    end
+
+    # This is an example:
+    #
+    # @example
+    #   method_with_code_example() # => some value
+    #
+    # @param p1 [String] mandatory param
+    # @param p2 [String, nil] optionally param
+    # @return [void]
+    def method_with_code_example2(p1, p2 = nil)
+    end
+
+    class Baz
+      def initialize(param1, param2, param3)
+      end
+
+      #
+      # Options: noop verbose force
+      #
+      # Changes owner and group on the named files (in +list+)
+      # to the user +user+ and the group +group+ recursively.
+      # +user+ and +group+ may be an ID (Integer/String) or
+      # a name (String).  If +user+ or +group+ is nil, this
+      # method does not change the attribute.
+      #
+      #   object.method_with_examples 1, 'www', 'www', '/var/www/htdocs'
+      #   object.method_with_examples 2, 'cvs', 'cvs', :verbose => true
+      #
+      def method_with_examples(user, group, list, options = {})
+      end
+
+      #
+      # Options: noop verbose force
+      #
+      # Changes owner and group on the named files (in +list+)
+      # to the user +user+ and the group +group+ recursively.
+      # +user+ and +group+ may be an ID (Integer/String) or
+      # a name (String).  If +user+ or +group+ is nil, this
+      # method does not change the attribute.
+      #
+      # @example
+      #   object.method_with_tagged_example 1, 'www', 'www', '/var/www/htdocs'
+      #   object.method_with_tagged_example 2, 'cvs', 'cvs', :verbose => true
+      #
+      def method_with_tagged_example(user, group, list, options = {})
+      end
+
+      #
+      # Options: noop verbose force
+      #
+      # Changes owner and group on the named files (in +list+)
+      # to the user +user+ and the group +group+ recursively.
+      # +user+ and +group+ may be an ID (Integer/String) or
+      #
+      # @example
+      #   object.method_with_examples 1, 'www', 'www', '/var/www/htdocs'
+      #
+      # a name (String).  If +user+ or +group+ is nil, this
+      # method does not change the attribute.
+      #
+      # @example
+      #   object.method_with_examples 2, 'cvs', 'cvs', :verbose => true
+      #
+      def method_with_2tagged_examples(user, group, list, options = {})
+      end
+
+      # Changes owner and group on the named files (in +list+)
+      #
+      #   object.method_with_one_example_other :similar
+      #   object.method_with_one_example 'www', 'www', '/var/www/htdocs'
+      #   # => 'cvs'
+      #
+      # No code.
+      #
+      def method_with_one_example
+      end
+    end
+  end
+
+  class Baz < Bar
+    def method_with_missing_param_doc(param1, param2, param3)
+    end
+  end
+
+  class Qux # :nodoc:
+    def method_with_implicit_nodoc
+    end
+
+    DOCCED_VALUE = 42 # :doc:
+
+    class Quux
+      def method_without_nodoc
+      end
+
+      PUBLIC_VALUE = :foo
+      PRIVATE_VALUE = :bar # :nodoc:
+
+      # @private
+      def method_with_private_tag
+      end
+
+      def method_with_explicit_nodoc # :nodoc:
+      end
+    end
+  end
+
+  class HiddenClass #:nodoc: all
+    def some_value
+    end
+
+    class EvenMoreHiddenClass
+      def method_with_implicit_nodoc
+      end
+
+      class SuddenlyVisibleClass # :doc:
+        def method_with_implicit_doc
+        end
+      end
+    end
+  end
+end
+
+def top
+end