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.
Yardstick may be used three ways:
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...
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
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
Every rule in Yardstick can be turned off globally and locally. All rules are enabled and threshold is set to maximum by default (100%). If your documentation coverage is below or above this threshold then yardstick will exit with a nonzero status and print that fact.
--- threshold: 100 rules: ApiTag::Presence: enabled: true exclude:  ApiTag::Inclusion: enabled: true exclude:  ApiTag::ProtectedMethod: enabled: true exclude:  ApiTag::PrivateMethod: enabled: true exclude:  ExampleTag: enabled: true exclude:  ReturnTag: enabled: true exclude:  Summary::Presence: enabled: true exclude:  Summary::Length: enabled: true exclude:  Summary::Delimiter: enabled: true exclude:  Summary::SingleLine: enabled: true exclude: 
To disable a rule for some part of the code use:
rules: ApiTag::Presence: enabled: true exclude: - Foo::Bar # class or module - Foo#bar # instance method - Foo.bar # class method
Rake tasks take these options as a second argument:
options = YAML.load_file('config/yardstick.yml') Yardstick::Rake::Verify.new(:verify_measurements, options)
See CONTRIBUTING.md for details.
Copyright (c) 2009-2013 Dan Kubb. See LICENSE for details.