inch 0.5.0.rc3 → 0.5.0.rc4

data/lib/inch/language/ruby/roles/missing.rb

@@ -0,0 +1,24 @@
+module Inch
+  module Language
+    module Ruby
+      module Evaluation
+        module Role
+          # Missing is the base class for things that can be improved in the doc
+          #
+          class Missing < Base
+            def score
+              nil
+            end
+
+            # @return [Fixnum]
+            #  a score that can be achieved by adding the missing thing mentioned
+            #  by the role
+            def potential_score
+              @value.to_i
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/inch/language/ruby/roles/namespace.rb

@@ -0,0 +1,89 @@
+module Inch
+  module Language
+    module Ruby
+      module Evaluation
+        module Role
+          # Roles assigned to namespaces (classes and modules)
+          module Namespace
+            # Role assigned to namespaces with children
+            #
+            # @see CodeObject::Ruby::NamespaceObject#has_children?
+            class WithChildren < Base
+              applicable_if :has_children?
+
+              # This role doesnot assign a score.
+              def score
+                0
+              end
+
+              # This role sets a max_score.
+              def max_score
+                # @value.to_f
+              end
+            end
+
+            # Role assigned to namespaces with many children
+            #
+            # @see CodeObject::Ruby::NamespaceObject#has_many_children?
+            class WithManyChildren < Base
+              applicable_if :has_many_children?
+
+              # +priority
+              def priority
+                +1
+              end
+            end
+
+            # Role assigned to namespaces with many attributes
+            #
+            # @see CodeObject::Ruby::NamespaceObject#has_many_attributes?
+            class WithManyAttributes < Base
+              applicable_if :has_many_attributes?
+
+              # +priority
+              def priority
+                +1
+              end
+            end
+
+            # Role assigned to namespaces without any children
+            class WithoutChildren < Base
+              applicable_unless :has_children?
+            end
+
+            # Role assigned to namespaces without any methods
+            class WithoutMethods < Base
+              applicable_unless :has_methods?
+
+              def priority
+                -2
+              end
+            end
+
+            # A 'pure' namespace has only namespaces as children
+            class Pure < Base
+              applicable_if :pure_namespace?
+
+              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.
+            # (the reasoning here is: just because we patch Hash does not mean
+            # we need to document the Hash class itself)
+            class Core < Base
+              applicable_if :core?
+
+              def priority
+                -7
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/inch/language/ruby/roles/object.rb

@@ -0,0 +1,120 @@
+module Inch
+  module Language
+    module Ruby
+      module Evaluation
+        module Role
+          # Roles assigned to all objects
+          module Object
+            # Role assigned to objects that are aliases.
+            #
+            class Alias < Base
+              applicable_if :alias?
+              # not sure about this yet,
+              # but aliases should not show up high in the reports
+              priority      -7
+            end
+
+            # Role assigned to objects with a describing comment (docstring)
+            class WithDoc < Base
+              applicable_if :has_doc?
+            end
+
+            # Role assigned to objects without a docstring
+            class WithoutDoc < Missing
+              applicable_unless :has_doc?
+
+              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
+              applicable_if :has_unconsidered_tags?
+              priority      -1
+            end
+
+            # Role assigned to objects explicitly or implicitly tagged not to be
+            # documented.
+            #
+            # @see CodeObject::NodocHelper
+            class TaggedAsNodoc < Base
+              applicable_if :nodoc?
+              priority      -7
+            end
+
+            # Role assigned to objects explicitly or implicitly tagged to be part
+            # of an API. If the API is 'private'/'internal' TaggedAsInternalAPI is
+            # assigned instead.
+            class TaggedAsAPI < Base
+              applicable_if :api_tag?
+            end
+
+            # Role assigned to objects explicitly or implicitly tagged to be part
+            # of a private API.
+            class TaggedAsInternalAPI < Base
+              applicable_if :tagged_as_internal_api?
+              priority      -5
+            end
+
+            # Role assigned to objects explicitly or implicitly tagged to be
+            # private.
+            #
+            # @see CodeObject::NodocHelper
+            class TaggedAsPrivate < Base
+              applicable_if :tagged_as_private?
+              priority      -5
+            end
+
+            # Role assigned to objects declared in the top-level namespace
+            class InRoot < Base
+              applicable_if :in_root?
+              priority      +3
+            end
+
+            # Role assigned to public objects
+            class Public < Base
+              applicable_if :public?
+              priority      +2
+            end
+
+            # Role assigned to protected objects
+            class Protected < Base
+              applicable_if :protected?
+              priority      +1
+            end
+
+            # Role assigned to private objects
+            class Private < Base
+              applicable_if :private?
+              priority      -2
+            end
+
+            # Role assigned to objects with a single code example
+            class WithCodeExample < Base
+              applicable_if do |o|
+                o.has_code_example? && !o.has_multiple_code_examples?
+              end
+            end
+
+            # Role assigned to objects with multiple code examples
+            class WithMultipleCodeExamples < Base
+              applicable_if :has_multiple_code_examples?
+            end
+
+            # Role assigned to objects without a code example
+            class WithoutCodeExample < Missing
+              applicable_unless :has_code_example?
+
+              def suggestion
+                "Add a code example (optional)"
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/inch/rake.rb

@@ -1,2 +1,2 @@
-require 'inch'
-require 'inch/rake/suggest'
+require "inch"
+require "inch/rake/suggest"

data/lib/inch/rake/suggest.rb

@@ -1,13 +1,17 @@
 # encoding: utf-8
 
-require 'rake'
-require 'rake/tasklib'
+require "rake"
+require "rake/tasklib"
+require "inch/cli"
 
 module Inch
   # Holds all Rake tasks
   module Rake
+    # Provides Rake task integration
     class Suggest < ::Rake::TaskLib
+      # @return [String] name of the Rake task
       attr_accessor :name
+      # @return [Array] arguments to be passed to Suggest.run
       attr_accessor :args
 
       # @param name [String] name of the Rake task
@@ -22,6 +26,7 @@ module Inch
         task(@name) { suggest }
       end
 
+      # @return [void]
       def suggest
         ::Inch::CLI::Command::Suggest.run(*@args)
       end

data/lib/inch/utils/buffered_ui.rb

@@ -0,0 +1,16 @@
+module Inch
+  module Utils
+    class BufferedUI < UI
+      attr_reader :out, :err
+
+      def initialize(stdout = $stdout, stderr = $stderr)
+        @io = StringIO.new
+        super(@io, @io)
+      end
+
+      def buffer
+        @io.string
+      end
+    end
+  end
+end

data/lib/inch/utils/shell_helper.rb

@@ -3,7 +3,7 @@ module Inch
     module ShellHelper
       def git(dir, command)
         Dir.chdir(dir) do
-          out = sh("git #{command}")
+          sh("git #{command}")
         end
       end
 

data/lib/inch/utils/ui.rb

@@ -10,9 +10,9 @@ module Inch
       end
 
       def debug(msg)
-        return unless ENV['DEBUG']
+        return unless ENV["DEBUG"]
         msg.to_s.lines.each do |line|
-          trace edged :dark, line.gsub(/\n$/,'').dark
+          trace edged :dark, line.gsub(/\n$/, "").dark
         end
       end
 
@@ -45,12 +45,12 @@ module Inch
       def header(text, color, bg_color = nil)
         @current_header_color = color
         trace __header(text, color, bg_color)
-        trace if !use_color?
+        trace unless use_color?
       end
 
       # @return [Boolean] true if the UI uses coloring
       def use_color?
-        Term::ANSIColor::coloring?
+        Term::ANSIColor.coloring?
       end
 
       private
@@ -61,7 +61,7 @@ module Inch
 
       def __header(text, color, bg_color = nil)
         bg_color ||= "intense_#{color}"
-        bar = " #{text}".ljust(CLI::COLUMNS-1)
+        bar = " #{text}".ljust(CLI::COLUMNS - 1)
                 .on_color(bg_color).color(:color16)
         "#".color(color).on_color(color) + bar
       end

data/lib/inch/utils/weighted_list.rb

@@ -74,9 +74,8 @@ module Inch
           target_count = @max_counts[index]
           @list[index].concat sublist[0...target_count]
 
-          if sublist.size < target_count
-            missing += target_count - sublist.size
-          end
+          next unless sublist.size < target_count
+          missing += target_count - sublist.size
         end
         missing
       end

data/lib/inch/version.rb

@@ -1,3 +1,3 @@
 module Inch
-  VERSION = "0.5.0.rc3"
+  VERSION = "0.5.0.rc4"
 end

data/test/fixtures/{simple → ruby/simple}/lib/broken.rb

@@ -18,13 +18,6 @@ module Foo
   def method_with_empty_param_tag_text(e)
   end
 
-  # The problem here is that ...
-  #
-  # @param *names [Array]
-  # @return [String]
-  def method_with_splat_parameter(*names)
-  end
-
   # The problem here is that ...
   #
   # @param names [Array]
@@ -38,20 +31,19 @@ module Foo
   def method_with_wrong_return_tag
   end
 
-  # Redirect to the given URL
-  # @param url [String] the destination URL
-  # @param status [Fixnum] the http code
-  def method_with_named_parameter(url, status: 302)
+  # The problem here is that ...
+  #
+  # @param *names [Array]
+  # @return [String]
+  def method_with_splat_parameter(*names)
   end
-end
 
-# Representation of attributes of a user in the database
-#
-# @!attribute email
-#   @return [String] E-mail address (from Devise)
-class Attributes
-  # @return [String] Username (from Devise)
-  attr_accessor :username
+  # Initializes a new Connection instance
+  #   @param [Hash<Symbol, >] params One or more optional params
+  #     @option params [String] :body Default text to be sent over a socket. Only used if :body absent in Connection#request params
+  #     @option params [Hash<Symbol, String>] :headers The default headers to supply in a request. Only used if params[:headers] is not supplied to Connection#request
+  def method_with_indented_param_tag(params = {})
+  end
 end
 
 module Overloading

data/test/fixtures/ruby/simple/lib/broken_ruby_2_0_features.rb

@@ -0,0 +1,7 @@
+module Foo
+  # Redirect to the given URL
+  # @param url [String] the destination URL
+  # @param status [Fixnum] the http code
+  def method_with_named_parameter(url, status: 302)
+  end
+end

data/test/fixtures/ruby/simple/lib/directives.rb

@@ -0,0 +1,8 @@
+# Representation of attributes of a user in the database
+#
+# @!attribute email
+#   @return [String] E-mail address (from Devise)
+class Attributes
+  # @return [String] Username (from Devise)
+  attr_accessor :username
+end

data/test/fixtures/{simple → ruby/simple}/lib/foo.rb

@@ -41,10 +41,14 @@ module Foo
     def method_without_docstring(p1, p2 = nil)
     end
 
-    # @return [void]
+    # @return [String]
     def method_without_params_or_docstring
     end
 
+    # @return [void]
+    def method_without_usable_return_value
+    end
+
     # Provides an example of a method without parameters
     # missing the return type.
     #
@@ -72,6 +76,23 @@ module Foo
     def method_with_other_rdoc_doc(param1, param2, param3)
     end
 
+    # Injects text right after the class definition. Since it depends on
+    # insert_into_file, it's reversible.
+    #
+    # ==== Parameters
+    # param1<String>:: path of the file to be changed
+    # param2<String|Class>:: the class to be manipulated
+    #
+    # ==== Examples
+    #
+    #   inject_into_class "app/controllers/application_controller.rb", ApplicationController, "  filter_parameter :password\n"
+    #
+    #   inject_into_class "app/controllers/application_controller.rb", ApplicationController do
+    #     "  filter_parameter :password\n"
+    #   end
+    def method_with_yet_another_rdoc_doc(param1, param2)
+    end
+
     # An example of a method that takes a parameter (+param1+)
     # and does nothing. But the previous sentence mentions said
     # parameter.