This post originated from an RSS feed registered with Ruby Buzz by Eric Hodel. Original Post: RDoc Coverage Report Feed Title: Segment7 Feed URL: http://blog.segment7.net/articles.rss Feed Description: Posts about and around Ruby, MetaRuby, ruby2c, ZenTest and work at The Robot Co-op. Latest Ruby Buzz Posts Latest Ruby Buzz Posts by Eric Hodel Latest Posts From Segment7

My favorite new feature in RDoc 3 is the documentation coverage report. When you run RDoc with --coverage-report (or --dcov or -C) RDoc will print out a report showing which classes, modules, methods and attributes are missing documentation.

$ rdoc -C lib/rubygems.rb
Parsing sources...
100% [ 1/ 1]  lib/rubygems.rb                                                   

The following items are not documented:

module Gem # is documented

  # in file lib/rubygems.rb
  RubyGemsVersion = nil
  # in file lib/rubygems.rb
  RbConfigPriorities = nil
  # in file lib/rubygems.rb
  RubyGemsPackageVersion = nil


end

class Gem::LoadError # is documented


  # in file lib/rubygems.rb
  def version_requirement(); end

  # in file lib/rubygems.rb
  def version_requirement=(requirement); end

end

# module Kernel is referenced but empty.
#
# It probably came from another project.  I'm sorry I'm holding it against you.

# in files:
#   lib/rubygems.rb

module RbConfig

end

In vim you can load the report in your editor and use tags to jump to the appropriate definition. In emacs you can use the file names to jump to the appropriate file to add documentation.

The report isn't 100% perfect, though. You can see a false positive where RubyGems references Kernel but doesn't have any documentation for it. I'm thinking about changing the report to omit such classes. Please convince me as it will take a bit of work to make the report behave properly.

You also get a nice summary of your project:

Files:          1

Classes:        1 (    0 undocumented)
Modules:        3 (    2 undocumented)
Constants:      8 (    3 undocumented)
Attributes:     7 (    0 undocumented)
Methods:       55 (    2 undocumented)

Total:         74 (    7 undocumented)
 90.54% documented

Elapsed: 0.6s

When you've documented to 100% you get a reward:

$ rdoc -C
Parsing sources...
100% [75/75]  lib/rdoc.rb

100% documentation!

Great Job!

[...]