Yardstick 0.1.0¶ ↑

Yardstick is a tool that verifies documentation coverage of Ruby code. It will measure the source and provide feedback on what is missing from the documentation and what can be improved.

• Homepage

• Git

• Bug Tracker

• Mailing List

• IRC

Installation¶ ↑

With Rubygems:

$ sudo gem install yardstick
$ irb -rubygems
>> require 'yardstick'
=> true

With the Rip package manager:

$ rip install git://github.com/dkubb/yardstick.git 0.1.0
$ 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:

# Require necessary files

require 'yardstick'
require 'yardstick/rake/measurement'
require 'yardstick/rake/verify'

# Namespace the yardstick tasks

namespace :yardstick do

  # Measure documentation coverage
  # This works for a rails app that keeps most of the code in the app and lib dir
  # For a non-rails app: measurement.path = 'lib/**/*.rb' works just fine.
  # This stores the report in doc/yardstick-report.txt because that seems appropriate

  Yardstick::Rake::Measurement.new(:measure) do |measurement|
    measurement.path = ['lib/**/*.rb', 'app/**/*.rb']
    measurement.output = 'doc/yardstick-report.txt'
  end

  # Verify documentation coverage
  # This sets the threshold to 100%, so
  # this task will execute successfully if the code is 100% documented,
  # this task will fail if not

  Yardstick::Rake::Verify.new(:verify) do |verify|
    verify.threshold = 100
  end
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

• Specify method_missing to allow public, semipublic or private even if its visibility is private

• Allow initialize to be public, semipublic or private regardless of its visibility. A constructor may not necessarily be public, and may not be used externally.

• Allow @return type to be “self” to specify the return value is the object itself. Ask argv if it can be made a YARD convention.

Copyright © 2009 Dan Kubb. See LICENSE for details.