yardstick 0.1.0

data/.document

@@ -0,0 +1,5 @@
+README.markdown
+lib/**/*.rb
+bin/*
+features/**/*.feature
+LICENSE

data/.gitignore

@@ -0,0 +1,10 @@
+*.sw?
+.DS_Store
+.yardoc
+coverage
+profiling
+measurements
+rdoc
+doc
+pkg
+tmp

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 Dan Kubb
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.markdown

@@ -0,0 +1,117 @@
+Yardstick 0.1.0
+===============
+
+* [Homepage](http://yardstick.rubyforge.org/)
+* [Git](http://github.com/dkubb/yardstick)
+* [Bug Tracker](http://github.com/dkubb/yardstick/issues)
+* [Mailing List](http://groups.google.com/group/yardstick)
+* [IRC](irc://irc.freenode.net/yardstick)
+
+Synopsis
+--------
+
+Yardstick is a tool that verifies YARD coverage of ruby code.
+
+It will measure the source and provide feedback on what is missing from
+the documentation and what can be improved.
+
+Installation
+------------
+
+With Rubygems:
+
+    $ sudo gem install dkubb-yardstick --source http://gems.github.com/
+    $ irb -rubygems
+    >> require 'yardstick'
+    => true
+
+With the [Rip package manager](http://hellorip.com/):
+
+    $ rip install git://github.com/dkubb/yardstick.git
+    $ irb -rrip
+    >> require 'yardstick'
+    => true
+
+With git and local working copy:
+
+    $ git clone git://github.com/dkubb/yardstick.git
+    $ cd yardstick
+    $ rake build && sudo rake install
+    $ irb -rubygems
+    >> require 'yardstick'
+    => true
+
+Usage
+-----
+
+Yardstick may be used three ways:
+
+**1. Command-line Tool**
+
+This is the simplest way to run yardstick.  Provide it a list of files
+and it will measure all of them and output suggestions for improvement,
+eg:
+
+    $ yardstick 'lib/**/*.rb' 'app/**/*.rb' ...etc...
+
+**2. Rake task**
+
+Yardstick may be integrated with existing Rakefile and build processes,
+and is especially useful when used with a continuous integration system.
+You can set thresholds, as well as check that the threshold matches the
+actual coverage, forcing you to bump it up if the actual coverage has
+increased.  It uses a simple DSL to configure the task eg:
+
+    # measure coverage
+
+    require 'yardstick/rake/measurement'
+
+    Yardstick::Rake::Measurement.new(:yardstick_measure) do |measurement|
+      measurement.output = 'measurement/report.txt'
+    end
+
+
+    # verify coverage
+
+    require 'yardstick/rake/verify'
+
+    Yardstick::Rake::Verify.new do |verify|
+      verify.threshold = 100
+    end
+
+
+**3. Libraries**
+
+Yardstick comes with several libraries that will allow you to process
+lists of files, or String code fragments, eg:
+
+    require 'yardstick'
+
+    # measure a list of file paths
+    measurements = Yardstick.measure(paths)
+
+    # measure a code fragment
+    measurements = Yardstick.measure_string <<-RUBY
+      # Displays the message provided to stdout
+      #
+      # @param [#to_str] message
+      #   the message to display
+      #
+      # @return [undefined]
+      #
+      # @api public
+      def display(message)
+        puts message.to_str
+      end
+    RUBY
+
+TODO
+----
+
+- Add more measurements, especially for @param, @yield and type
+  validation
+- Update yardstick_measure task to use the Yardstick::CLI library
+  underneath.
+- Output results as HTML from command line tool and Rake task
+
+Copyright (c) 2009 Dan Kubb. See LICENSE for details.

data/Rakefile

@@ -0,0 +1,24 @@
+require 'rubygems'
+require 'rake'
+require 'pathname'
+
+Pathname.glob('tasks/**/*.rake').each { |task| load task.expand_path }
+
+begin
+  require 'jeweler'
+
+  Jeweler::Tasks.new do |gem|
+    gem.name              = 'yardstick'
+    gem.summary           = 'A tool for verifying YARD documentation coverage'
+    gem.email             = 'dan.kubb@gmail.com'
+    gem.homepage          = 'http://github.com/dkubb/yardstick'
+    gem.authors           = [ 'Dan Kubb' ]
+    gem.rubyforge_project = 'yardstick'
+
+    gem.add_dependency('yard', '~>0.2')
+  end
+
+  Jeweler::RubyforgeTasks.new
+rescue LoadError
+  puts 'Jeweler (or a dependency) not available. Install it with: sudo gem install jeweler'
+end

data/VERSION

@@ -0,0 +1 @@
+0.1.0

data/bin/yardstick

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby -KU
+
+require 'rubygems'
+require 'pathname'
+require Pathname(__FILE__).dirname.expand_path.parent.join('lib', 'yardstick')
+
+Yardstick::CLI.run(*ARGV)

data/deps.rip

@@ -0,0 +1 @@
+git://github.com/lsegal/yard.git 0.2.3.3

data/lib/yardstick/autoload.rb

@@ -0,0 +1,16 @@
+module Yardstick
+  autoload :CLI,            'yardstick/cli'
+  autoload :Measurable,     'yardstick/measurable'
+  autoload :Measurement,    'yardstick/measurement'
+  autoload :MeasurementSet, 'yardstick/measurement_set'
+  autoload :Method,         'yardstick/method'
+  autoload :OrderedSet,     'yardstick/ordered_set'
+  autoload :Processor,      'yardstick/processor'
+  autoload :Rule,           'yardstick/rule'
+  autoload :RuleSet,        'yardstick/rule_set'
+
+  module Rake
+    autoload :Measurement, 'yardstick/rake/measurement'
+    autoload :Verify,      'yardstick/rake/verify'
+  end # module Rake
+end # module Yardstick

data/lib/yardstick/cli.rb

@@ -0,0 +1,76 @@
+require 'optparse'
+
+module Yardstick
+  class CLI
+
+    # Parse the command line options, and run the command
+    #
+    # @example
+    #   Yardstick::CLI.run(%w[ article.rb ])  # => [ Measurement ]
+    #
+    # @param [Array] *args
+    #   arguments passed in from the command line
+    #
+    # @return [MeasurementSet]
+    #   the measurement for each file
+    #
+    # @api public
+    def self.run(*args)
+      measurements = Yardstick.measure(*parse_options(args))
+      measurements.puts
+      measurements
+    end
+
+    # Parse the options provided from the command-line
+    #
+    # @param [Array<String>] args
+    #   the command-line options
+    #
+    # @return [Array(Array<String>, Hash)]
+    #   the list of files, and options parsed from the command-line
+    #
+    # @api private
+    def self.parse_options(args)
+      args << '--help' if args.empty?
+      options = {}
+      option_parser(options).parse!(args)
+      [ args, options ]
+    rescue OptionParser::InvalidOption => error
+      display_exit(error.message)
+    end
+
+    # Return an OptionParser instance for the command-line app
+    #
+    # @param [Hash] options
+    #   the options to set when parsing the command-line arguments
+    #
+    # @return [OptionParser]
+    #   the option parser instance
+    #
+    # @api private
+    def self.option_parser(options)
+      opts = OptionParser.new
+      opts.on_tail('-v', '--version', 'print version information and exit') { display_exit("#{opts.program_name} #{Yardstick::VERSION}") }
+      opts.on_tail('-h', '--help',    'display this help and exit')         { display_exit(opts.to_s) }
+      opts
+    end
+
+    # Display a message and exit
+    #
+    # @param [#to_str] message
+    #   the message to display
+    #
+    # @return [undefined]
+    #
+    # @api private
+    def self.display_exit(message)
+      puts message.to_str
+      exit
+    end
+
+    class << self
+      private :option_parser, :parse_options, :display_exit
+    end
+
+  end # module CLI
+end # module Yardstick

data/lib/yardstick/core_ext/object.rb

@@ -0,0 +1,13 @@
+class Object  #:nodoc:
+
+  # Return the meta class for this instance
+  #
+  # @return [Class]
+  #   the meta class
+  #
+  # @api private
+  def meta_class
+    class << self; self end
+  end
+
+end # class Object

data/lib/yardstick/measurable.rb

@@ -0,0 +1,78 @@
+module Yardstick
+  module Measurable
+    include Measurement::UtilityMethods
+
+    module ClassMethods
+
+      # List of rules for this class
+      #
+      # @return [RuleSet<Rule>]
+      #   the rules for this class
+      #
+      # @api private
+      def rules
+        @rules ||= RuleSet.new
+      end
+
+      # Set the description for the rule
+      #
+      # @param [#to_str] description
+      #   the rule description
+      #
+      # @yield []
+      #   the rule to perform
+      #
+      # @yieldreturn [Boolean]
+      #   return true if successful, false if not
+      #
+      # @return [undefined]
+      #
+      # @api private
+      def rule(description, &block)
+        rules << Rule.new(description, &block)
+      end
+
+    private
+
+      # Include the class or module with measurable class methods
+      #
+      # @param [Module] mod
+      #   the module to include within
+      #
+      # @return [undefined]
+      #
+      # @api private
+      def included(mod)
+        mod.extend(ClassMethods).rules.merge(rules)
+      end
+
+      # Extend the docstring meta class with measurable class methods
+      #
+      # @param [YARD::Docstring] docstring
+      #   the docstring to extend
+      #
+      # @return [undefined]
+      #
+      # @api private
+      def extended(docstring)
+        included(docstring.meta_class)
+      end
+    end # module ClassMethods
+
+    extend ClassMethods
+
+    # Return a list of measurements for this docstring instance
+    #
+    # @example
+    #   docstring.measure  # => [ Measurement ]
+    #
+    # @return [MeasurementSet]
+    #   a collection of measurements
+    #
+    # @api public
+    def measure
+      meta_class.rules.measure(self)
+    end
+
+  end # module Measurable
+end # module Yardstick

data/lib/yardstick/measurement.rb

@@ -0,0 +1,217 @@
+module Yardstick
+  class Measurement
+
+    # Return the Measurement description
+    #
+    # @example
+    #   measurement.description  # => "The description"
+    #
+    # @return [String]
+    #   the description
+    #
+    # @api public
+    attr_reader :description
+
+    # Return a Measurement instance
+    #
+    # @example
+    #   measurement = Measurement.new('The description', docstring, :successful_method)
+    #
+    # @param [#to_str] description
+    #   the measurement description
+    # @param [YARD::Docstring] docstring
+    #   the docstring to measure
+    #
+    # @yield []
+    #   the measurement to perform
+    #
+    # @return [Yardstick::Measurement]
+    #   the measurement instance
+    #
+    # @api public
+    def initialize(description, docstring, &block)
+      @description = description.to_str
+      @docstring   = docstring
+      @block       = block
+      @result      = measure
+    end
+
+    # Return true if the measurement was successful
+    #
+    # @example Measurement successful
+    #   measurement.ok?  # => true
+    #
+    # @example Measurement unsuccessful
+    #   measurement.ok?  # => false
+    #
+    # @return [Boolean]
+    #   true if the measurement was successful, false if not
+    #
+    # @api public
+    def ok?
+      @result == true || skip?
+    end
+
+    # Return true if the measurement was skipped
+    #
+    # @example Measurement skipped
+    #   measurement.skip?  # => true
+    #
+    # @example Measurement not skipped
+    #   measurement.skip?  # => false
+    #
+    # @return [Boolean]
+    #   true if the measurement was skipped, false if not
+    #
+    # @api public
+    def skip?
+      @result == :skip
+    end
+
+    # Return true if the measurement is not implemented
+    #
+    # @example Measurement not implemented
+    #   measurement.todo?  # => true
+    #
+    # @example Measurement implemented
+    #   measurement.todo?  # => false
+    #
+    # @return [Boolean]
+    #   true if the measurement is not implemented, false if not
+    #
+    # @api public
+    def todo?
+      @result == :todo
+    end
+
+    # Warns the results the measurement if it was not successful
+    #
+    # @example
+    #   measurement.puts  # (outputs results if not successful)
+    #
+    # @param [#puts] io
+    #   optional object to puts the summary
+    #
+    # @return [undefined]
+    #
+    # @api public
+    def puts(io = $stdout)
+      unless ok?
+        io.puts("#{file}:#{line}: #{path}: #{@description}")
+      end
+    end
+
+    # Test if Measurement is equal to another measurement
+    #
+    # @example
+    #   measurement == equal_measurement  # => true
+    #
+    # @param [Measurement] other
+    #   the other Measurement
+    #
+    # @return [Boolean]
+    #   true if the Measurement is equal to the other, false if not
+    #
+    # @api semipublic
+    def eql?(other)
+      @description.eql?(other.instance_variable_get(:@description)) &&
+      @docstring.eql?(other.instance_variable_get(:@docstring))
+    end
+
+    # Return hash identifier for the Measurement
+    #
+    # @return [Integer]
+    #   the hash identifier
+    #
+    # @api private
+    def hash
+      [ @description, @docstring ].hash
+    end
+
+  private
+
+    # Measure the docstring using the method provided to the constructor
+    #
+    # @return [Boolean, Symbol]
+    #   true if the test is successful, false if not
+    #   :todo if the test is not implemented
+    #   :skip if the test does not apply
+    #
+    # @api private
+    def measure
+      catch :measurement do
+        @docstring.instance_eval(&@block)
+      end
+    end
+
+    # The code object for the docstring
+    #
+    # @return [YARD::CodeObjects::Base]
+    #   the code object
+    #
+    # @api private
+    def object
+      @docstring.object
+    end
+
+    # The filename for the code
+    #
+    # @return [Pathname]
+    #   the filename
+    #
+    # @api private
+    def file
+      Pathname(object.file)
+    end
+
+    # The line number for the code
+    #
+    # @return [Integer]
+    #   the line number
+    #
+    # @api private
+    def line
+      object.line
+    end
+
+    # The class and method name for the code
+    #
+    # @return [String]
+    #   the class and method name
+    #
+    # @api private
+    def path
+      object.path
+    end
+
+    module UtilityMethods  #:nodoc:
+      private
+
+      # Throw a :skip measurement message to the caller
+      #
+      # This method allows you to short-circuit measurement methods when
+      # the measurement does not apply due to specific object states.
+      #
+      # @return [undefined]
+      #
+      # @api private
+      def skip
+        throw :measurement, :skip
+      end
+
+      # Throw a :todo measurement message to the caller
+      #
+      # This method allows you to short-circuit measurement methods when
+      # the measurement is not implemented.
+      #
+      # @return [undefined]
+      #
+      # @api private
+      def todo
+        throw :measurement, :todo
+      end
+
+    end # module UtilityMethods
+
+  end # class Measurement
+end # module Yardstick