yardstick 0.9.6 → 0.9.7

data/lib/yardstick/rake/verify.rb

@@ -11,34 +11,6 @@ module Yardstick
     # A rake task for verifying the doc thresholds
     class Verify < ::Rake::TaskLib
 
-      # Set the threshold
-      #
-      # @return [undefined]
-      #
-      # @api public
-      attr_writer :threshold
-
-      # Specify if the threshold should match the coverage
-      #
-      # @return [undefined]
-      #
-      # @api public
-      attr_writer :require_exact_threshold
-
-      # List of paths to measure
-      #
-      # @return [undefined]
-      #
-      # @api public
-      attr_writer :path
-
-      # Specify if the coverage summary should be displayed
-      #
-      # @return [undefined]
-      #
-      # @api public
-      attr_writer :verbose
-
       # Initialize a Verify task
       #
       # @example
@@ -46,26 +18,22 @@ module Yardstick
       #     task.threshold = 100
       #   end
       #
+      # @param [Hash] options
+      #   optional configuration
       # @param [Symbol] name
       #   optional task name
       #
-      # @yield [task]
-      #   yield to self
-      #
-      # @yieldparam [Yardstick::Rake::Verify] task
-      #   the verification task
+      # @yieldparam [Yardstick::Config] config
+      #   the config object
       #
       # @return [Yardstick::Rake::Verify] task
       #   the verification task instance
       #
       # @api public
-      def initialize(name = :verify_measurements)
-        @name                    = name
-        @require_exact_threshold = true
-        @path                    = 'lib/**/*.rb'
-        @verbose                 = true
-
-        yield self
+      def initialize(name = :verify_measurements, options = {}, &block)
+        @name      = name
+        @config    = Config.coerce(options, &block)
+        @threshold = @config.threshold
 
         assert_threshold
         define
@@ -85,7 +53,7 @@ module Yardstick
       #
       # @api public
       def verify_measurements
-        puts "YARD-Coverage: #{total_coverage}% (threshold: #{@threshold}%)" if verbose
+        puts "YARD-Coverage: #{total_coverage}% (threshold: #{@threshold}%)" if @config.verbose?
         assert_meets_threshold
         assert_matches_threshold
       end
@@ -99,8 +67,8 @@ module Yardstick
       #
       # @api private
       def total_coverage
-        measurements = Yardstick.measure(@path)
-        self.class.round_percentage(measurements.coverage * 100)
+        measurements = Yardstick.measure(@config)
+        Yardstick.round_percentage(measurements.coverage * 100)
       end
 
     private
@@ -124,7 +92,7 @@ module Yardstick
       #
       # @api private
       def assert_threshold
-        if @threshold.nil?
+        unless @threshold
           raise 'threshold must be set'
         end
       end
@@ -138,8 +106,7 @@ module Yardstick
       #
       # @api private
       def assert_meets_threshold
-        total_coverage = self.total_coverage
-        if total_coverage < @threshold
+        if lower_coverage?
           raise "YARD-Coverage must be at least #{@threshold}% but was #{total_coverage}%"
         end
       end
@@ -153,23 +120,29 @@ module Yardstick
       #
       # @api private
       def assert_matches_threshold
-        total_coverage = self.total_coverage
-        if @require_exact_threshold && total_coverage > @threshold
+        if @config.require_exact_threshold? && higher_coverage?
           raise "YARD-Coverage has increased above the threshold of #{@threshold}% to #{total_coverage}%. You should update your threshold value."
         end
       end
 
-      # Round percentage to 1/10th of a percent
+      # Checks if total coverage is lower than the threshold
       #
-      # @param [Float] percentage
-      #   the percentage to round
+      # @return [Boolean]
+      #   true if current coverage is lower
       #
-      # @return [Float]
-      #   the rounded percentage
+      # @api private
+      def lower_coverage?
+        total_coverage < @threshold
+      end
+
+      # Checks if total coverage is higher than the threshold
+      #
+      # @return [Boolean]
+      #   true if current coverage is higher
       #
       # @api private
-      def self.round_percentage(percentage)
-        (percentage * 10).ceil / 10.0
+      def higher_coverage?
+        total_coverage > @threshold
       end
 
     end # class Verify

data/lib/yardstick/report_output.rb

@@ -0,0 +1,57 @@
+# encoding: utf-8
+
+module Yardstick
+
+  # Handles writing reports
+  class ReportOutput
+
+    # Coerces string path into proper output object
+    #
+    # @param [String, Pathname] target
+    #   path of the output
+    #
+    # @return [Yardstick::ReportOutput]
+    #
+    # @api private
+    def self.coerce(target)
+      new(Pathname(target))
+    end
+
+    # Initializes ReportOutput instance
+    #
+    # @param [Pathname] target
+    #
+    # @return [undefined]
+    #
+    # @api private
+    def initialize(target)
+      @target = target
+    end
+
+    # Open up a report for writing
+    #
+    # @yield [io]
+    #   yield to an object that responds to #puts
+    #
+    # @yieldparam [#puts] io
+    #   the object that responds to #puts
+    #
+    # @return [undefined]
+    #
+    # @api private
+    def write(&block)
+      @target.dirname.mkpath
+      @target.open('w', &block)
+    end
+
+    # @see [Pathname#to_s]
+    #
+    # @return [String]
+    #
+    # @api private
+    def to_s
+      @target.to_s
+    end
+
+  end
+end

data/lib/yardstick/rule.rb

@@ -1,65 +1,92 @@
 # encoding: utf-8
 
 module Yardstick
-
-  # A constraint on the docs
+  # Base class of every rule
+  #
+  # @abstract
   class Rule
+    extend Forwardable
 
-    # Return a Rule instance
-    #
-    # @param [#to_str] description
-    #   the description of the Rule
+    class << self
+      # Description of the rule
+      #
+      # This is shown when a rule is invalid
+      #
+      # @return [String]
+      #
+      # @api private
+      attr_accessor :description
+
+      private :description=
+    end
+
+    # Register rule in Document
     #
-    # @yield []
-    #   the measurement for the rule
+    # @param [Class] subclass
+    #   class that is inheriting from this class
     #
-    # @return [Rule]
-    #   the rule instance
+    # @return [undefined]
     #
     # @api private
-    def initialize(description, &block)
-      @description = description.to_str
-      @block       = block
+    def self.inherited(subclass)
+      Document.register_rule(subclass)
     end
+    private_class_method :inherited
 
-    # Return a Measurement for a docstring
+    # Makes a new instance of rule using given config
     #
-    # @param [YARD::Docstring] docstring
-    #   the docstring to measure
+    # @param [Yardstick::Document] document
+    #   document that will be measured
+    # @param [Yardstick::Config] config
+    #   a configuration
     #
-    # @return [Measurement]
-    #   the measurement
+    # @return [Yardstick::Rule]
     #
     # @api private
-    def measure(docstring)
-      Measurement.new(@description, docstring, &@block)
+    def self.coerce(document, config)
+      new(document, config.for_rule(self))
     end
 
-    # Test if Rule is equal to another rule
+    # Return document that current rule is using
     #
-    # @example
-    #   rule == equal_rule  # => true
+    # @return [Document]
     #
-    # @param [Rule] other
-    #   the other Rule
+    # @api private
+    attr_reader :document
+
+    # Initializes a rule
     #
-    # @return [Boolean]
-    #   true if the Rule is equal to the other, false if not
+    # @param [Yardstick::Document] document
+    # @param [Yardstick::RuleConfig] config
+    #   rule configuration
+    #
+    # @return [Yardstick::Rule]
     #
-    # @api semipublic
-    def eql?(other)
-      @description.eql?(other.instance_variable_get(:@description))
+    # @api private
+    def initialize(document, config = RuleConfig.new)
+      @document = document
+      @config   = config
     end
 
-    # Return hash identifier for the Rule
+    def_delegators :@document, :has_tag?, :api?, :tag_types, :tag_text, :summary_text, :visibility
+
+    # Checks if rule is enabled in current context
     #
-    # @return [Integer]
-    #   the hash identifier
+    # @return [Boolean]
+    #   true if enabled
     #
     # @api private
-    def hash
-      @description.hash
+    def enabled?
+      @config.enabled_for_path?(@document.path)
     end
 
-  end # class Rule
-end # module Yardstick
+    # Checks if the rule is validatable for given document
+    #
+    # @return [Boolean]
+    #
+    # @api private
+    def validatable?
+      true
+    end
+  end
+end

data/lib/yardstick/rule_config.rb

@@ -0,0 +1,56 @@
+# encoding: utf-8
+
+module Yardstick
+  # Config class for rules
+  #
+  # It is used to check if document should be validated or not.
+  #
+  class RuleConfig
+    METHOD_SEPARATOR = /\#|\./.freeze
+
+    # Initializes new instance of rule config
+    #
+    # @param [Hash] options
+    #   optional configuration
+    #
+    # @return [Yardstick::RuleConfig]
+    #
+    # @api private
+    def initialize(options = {})
+      @enabled = options.fetch(:enabled, true)
+      @exclude = options.fetch(:exclude, [])
+    end
+
+    # Checks if given path should be checked using this rule
+    #
+    # @param [String] path
+    #   document path, e.g "Foo::Bar#baz"
+    #
+    # @return [Boolean]
+    #   true if path should be checked
+    #
+    # @api private
+    def enabled_for_path?(path)
+      @enabled && !exclude?(path)
+    end
+
+    private
+
+    # Checks if given path is in exclude list
+    #
+    # If exact match fails then checks if the method class is in the exclude
+    # list.
+    #
+    # @param [String] path
+    #   document path
+    #
+    # @return [Boolean]
+    #   true if path is in the exclude list
+    #
+    # @api private
+    def exclude?(path)
+      @exclude.include?(path) ||
+        @exclude.include?(path.split(METHOD_SEPARATOR).first)
+    end
+  end
+end

data/lib/yardstick/rules/api_tag.rb

@@ -0,0 +1,95 @@
+# encoding: utf-8
+
+module Yardstick
+  module Rules
+    # Rules related to @api tag
+    #
+    class ApiTag
+      # Checks if @api tag is present
+      #
+      class Presence < Rule
+        self.description = 'The @api tag should be specified'
+
+        # @see class description
+        #
+        # @return [Boolean]
+        #   true if valid
+        #
+        # @api private
+        def valid?
+          has_tag?('api')
+        end
+      end
+
+      # Checks if @api tag is a public, semipublic or private
+      #
+      class Inclusion < Rule
+        VALID_VALUES = %w[ public semipublic private ].freeze
+
+        self.description = 'The @api tag must be either public, semipublic or private'
+
+        # @see class description
+        #
+        # @return [Boolean]
+        #   true if valid
+        #
+        # @api private
+        def valid?
+          VALID_VALUES.include?(tag_text('api'))
+        end
+      end
+
+      # Checks if protected method has correct @api visibility
+      #
+      class ProtectedMethod < Rule
+        self.description = 'A method with protected visibility must have an @api tag of semipublic or private'
+
+        # @see Rule::validatable?
+        #
+        # @return [Boolean]
+        #   true if method visibility is protected
+        #
+        # @api private
+        def validatable?
+          visibility == :protected
+        end
+
+        # @see class description
+        #
+        # @return [Boolean]
+        #   true if api tag is semipublic or private
+        #
+        # @api private
+        def valid?
+          api?(%w[ semipublic private ])
+        end
+      end
+
+      # Checks if private method has correct @api visibility
+      #
+      class PrivateMethod < Rule
+        self.description = 'A method with private visibility must have an @api tag of private'
+
+        # @see Rule::validatable?
+        #
+        # @return [Boolean]
+        #   true method visibility is private
+        #
+        # @api private
+        def validatable?
+          visibility == :private
+        end
+
+        # @see class description
+        #
+        # @return [Boolean]
+        #   true if api tag is private
+        #
+        # @api private
+        def valid?
+          api?(%w[ private ])
+        end
+      end
+    end
+  end
+end