inch 0.2.3 → 0.3.0.rc1

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

@@ -7,6 +7,25 @@ module Inch
       class Base
         attr_reader :object
 
+        class << self
+          def applicable_if(symbol = nil, &block)
+            @applicable_procs ||= {}
+            @applicable_procs[to_s] = block || symbol.to_proc
+          end
+
+          def applicable_unless(symbol = nil, &block)
+            @applicable_procs ||= {}
+            @applicable_procs[to_s] = proc do |object|
+              !(block || symbol.to_proc).call(object)
+            end
+          end
+
+          def applicable?(object)
+            @applicable_procs ||= {}
+            @applicable_procs[to_s].call(object)
+          end
+        end
+
         def initialize(object, value = nil)
           @object = object
           @value = value

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

@@ -4,31 +4,47 @@ module Inch
       # Roles assigned to constants
       module Constant
         class WithDoc < Object::WithDoc
+          applicable_if :has_doc?
         end
         class WithoutDoc < Object::WithoutDoc
+          applicable_unless :has_doc?
         end
 
         class TaggedAsNodoc < Object::TaggedAsNodoc
+          applicable_if :nodoc?
         end
         class InRoot < Object::InRoot
+          applicable_if :in_root?
         end
 
         class Public < Object::Public
+          applicable_if :public?
+
           def priority
             -1
           end
         end
         class Private < Object::Private
+          applicable_if :private?
+
           def priority
             -3
           end
         end
 
         class WithCodeExample < Object::WithCodeExample
+          applicable_if do |o|
+            o.has_code_example? && !o.has_multiple_code_examples?
+          end
         end
+
         class WithMultipleCodeExamples < Object::WithMultipleCodeExamples
+          applicable_if :has_multiple_code_examples?
         end
+
         class WithoutCodeExample < Object::WithoutCodeExample
+          applicable_unless :has_code_example?
+
           def suggestion
             nil
           end

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

@@ -4,12 +4,15 @@ module Inch
       module Method
         # Role assigned to methods without parameters
         class WithoutParameters < Base
+          applicable_unless :has_parameters?
         end
 
         # Role assigned to methods with many parameters
         #
         # @see CodeObject::Proxy::MethodObject#has_many_parameters?
         class WithManyParameters < Base
+          applicable_if :has_many_parameters?
+
           def priority
             +2
           end
@@ -17,10 +20,13 @@ module Inch
 
         # Role assigned to methods where the return value is typed in the docs
         class WithReturnType < Base
+          applicable_if :return_typed?
         end
 
         # Role assigned to methods where the return value is not typed
         class WithoutReturnType < Missing
+          applicable_unless :return_typed?
+
           def suggestion
             "Describe what '#{object.name}' returns"
           end
@@ -28,10 +34,13 @@ module Inch
 
         # Role assigned to methods where the return value is decribed in the docs
         class WithReturnDescription < Base
+          applicable_if :return_described?
         end
 
         # Role assigned to methods where the return value is not decribed
         class WithoutReturnDescription < Missing
+          applicable_unless :return_described?
+
           def suggestion
             "Describe what '#{object.name}' returns"
           end
@@ -42,6 +51,8 @@ module Inch
         #
         # @see CodeObject::Proxy::MethodObject#has_many_lines?
         class WithManyLines < Base
+          applicable_if :has_many_lines?
+
           def priority
             +2
           end
@@ -49,6 +60,8 @@ module Inch
 
         # Role assigned to methods whose name end in a '!'
         class WithBangName < Base
+          applicable_if :bang_name?
+
           def priority
             +3
           end
@@ -56,6 +69,8 @@ module Inch
 
         # Role assigned to methods whose name end in a '?'
         class WithQuestioningName < Base
+          applicable_if :questioning_name?
+
           def priority
             -4
           end
@@ -63,6 +78,8 @@ module Inch
 
         # Role assigned to methods which are aliased
         class HasAlias < Base
+          applicable_if :has_alias?
+
           def priority
             +2
           end
@@ -70,18 +87,23 @@ module Inch
 
         # Role assigned to methods that are constructors
         class Constructor < Base
+          applicable_if :constructor?
         end
 
         # Role assigned to methods that are getters
         class Getter < Base
+          applicable_if :getter?
         end
 
         # Role assigned to methods that are setters
         class Setter < Base
+          applicable_if :setter?
         end
 
         # Role assigned to methods that are overriding another method
         class Overridden < Base
+          applicable_if :overridden?
+
           # It seems more important to document the overridden method,
           # than the overriding one
           def priority

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

@@ -2,35 +2,58 @@ module Inch
   module Evaluation
     module Role
       # Roles assigned to method parameters
+      #
+      # @note The +object+ is a MethodParameterObject here!
       module MethodParameter
         # Role assigned to parameters that are mentioned in the docs
+        #
+        # @see CodeObject::Proxy::MethodParameterObject#mentioned?
         class WithMention < Base
+          applicable_if :mentioned?
         end
 
         # Role assigned to parameters that are not mentioned in the docs
+        #
+        # @see CodeObject::Proxy::MethodParameterObject#mentioned?
         class WithoutMention < Missing
+          applicable_unless :mentioned?
+
           def suggestion
             "Describe the parameter '#{object.name}'"
           end
         end
 
         # Role assigned to parameters that are typed in the docs
+        #
+        # @see CodeObject::Proxy::MethodParameterObject#typed?
         class WithType < Base
+          applicable_if :typed?
         end
 
         # Role assigned to parameters that are not typed in the docs
+        #
+        # @see CodeObject::Proxy::MethodParameterObject#typed?
         class WithoutType < Missing
+          applicable_unless :typed?
         end
 
         # Role assigned to parameters that are spalts, e.g. +*args+
+        #
+        # @see CodeObject::Proxy::MethodParameterObject#splat?
         class Splat < Base
+          applicable_if :splat?
+
           def priority
             +1
           end
         end
 
         # Role assigned to parameters that are blocks, e.g. +&block+
+        #
+        # @see CodeObject::Proxy::MethodParameterObject#block?
         class Block < Base
+          applicable_if :block?
+
           def priority
             +1
           end
@@ -38,10 +61,15 @@ module Inch
 
         # Role assigned to parameters that are documented, but not part of
         # the method signature
-        class WithWrongMention < Missing
+        #
+        # @see CodeObject::Proxy::MethodParameterObject#wrongly_mentioned?
+        class WithWrongMention < Base
+          applicable_if :wrongly_mentioned?
+
           def suggestion
             "The parameter '#{object.name}' seems not to be part of the signature."
           end
+
           def priority
             +1
           end
@@ -51,6 +79,8 @@ module Inch
         #
         # @see CodeObject::Proxy::MethodParameterObject#bad_name?
         class WithBadName < Base
+          applicable_if :bad_name?
+
           def priority
             +1
           end

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

@@ -4,7 +4,11 @@ module Inch
       # Roles assigned to namespaces (classes and modules)
       module Namespace
         # Role assigned to namespaces with children
+        #
+        # @see CodeObject::Proxy::NamespaceObject#has_children?
         class WithChildren < Base
+          applicable_if :has_children?
+
           # This role doesnot assign a score.
           def score
             0
@@ -20,6 +24,8 @@ module Inch
         #
         # @see CodeObject::Proxy::NamespaceObject#has_many_children?
         class WithManyChildren < Base
+          applicable_if :has_many_children?
+
           # +priority
           def priority
             +1
@@ -30,6 +36,8 @@ module Inch
         #
         # @see CodeObject::Proxy::NamespaceObject#has_many_attributes?
         class WithManyAttributes < Base
+          applicable_if :has_many_attributes?
+
           # +priority
           def priority
             +1
@@ -38,10 +46,13 @@ module Inch
 
         # 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
@@ -49,6 +60,8 @@ module Inch
 
         # A 'pure' namespace has only namespaces as children
         class Pure < Base
+          applicable_if :pure_namespace?
+
           def priority
             -2
           end
@@ -60,6 +73,8 @@ module Inch
         # (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

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

@@ -5,10 +5,13 @@ module Inch
       module Object
         # 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
@@ -18,6 +21,8 @@ module Inch
         # 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?
+
           def priority
             -1
           end
@@ -28,6 +33,8 @@ module Inch
         #
         # @see CodeObject::NodocHelper
         class TaggedAsNodoc < Base
+          applicable_if :nodoc?
+
           def priority
             -7
           end
@@ -37,11 +44,14 @@ module Inch
         # of an API. If the API is 'private' TaggedAsPrivateAPI 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 TaggedAsPrivateAPI < Base
+          applicable_if :private_api_tag?
+
           def priority
             -5
           end
@@ -49,6 +59,8 @@ module Inch
 
         # Role assigned to objects declared in the top-level namespace
         class InRoot < Base
+          applicable_if :in_root?
+
           def priority
             +3
           end
@@ -56,6 +68,8 @@ module Inch
 
         # Role assigned to public objects
         class Public < Base
+          applicable_if :public?
+
           def priority
             +2
           end
@@ -63,6 +77,8 @@ module Inch
 
         # Role assigned to protected objects
         class Protected < Base
+          applicable_if :protected?
+
           def priority
             +1
           end
@@ -70,6 +86,8 @@ module Inch
 
         # Role assigned to private objects
         class Private < Base
+          applicable_if :private?
+
           def priority
             -2
           end
@@ -77,14 +95,20 @@ module Inch
 
         # 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

data/lib/inch/rake/suggest.rb

@@ -4,6 +4,7 @@ require 'rake'
 require 'rake/tasklib'
 
 module Inch
+  # Holds all Rake tasks
   module Rake
     class Suggest < ::Rake::TaskLib
       attr_accessor :name

data/lib/inch/utils/read_write_methods.rb

@@ -0,0 +1,44 @@
+module Inch
+  module Utils
+    # Extend a class with ReadWriteMethods and you will gain the +rw_methods+
+    # macro.
+    #
+    #   class User
+    #     extend ReadWriteMethods
+    #     rw_methods :name, :admin
+    #   end
+    #
+    # This implements read methods that act as writer methods when called
+    # with a value parameter:
+    #
+    #   user = User.new
+    #   user.name # => nil
+    #   user.name "Adam"
+    #   user.name # => "Adam"
+    #
+    module ReadWriteMethods
+      # Implements a read method that acts as writer if called with a value
+      #
+      # @return [void]
+      def rw_method(name)
+        class_eval """
+          def #{name}(value = nil)
+            if value.nil?
+              @#{name}
+            else
+              @#{name} = value
+            end
+          end
+        """
+      end
+
+      # Implements multiple read(write) methods with the given +names+
+      #
+      # @param names [Array<String,Symbol>]
+      # @return [void]
+      def rw_methods(*names)
+        [names].flatten.each { |name| rw_method(name) }
+      end
+    end
+  end
+end