Documentation Coverage Testing With dcov
August 28th, 2007 by Pat Eyler
How often have you thrown up your hands in disgust at the poor quality of documentation for an open source project? Wouldn’t it be nice if someone put together a documentation coverage tool that worked like test coverage too ls? Well, you’re in luck—dcov is here (at least for Ruby code).
dcov is still pretty immature (the current release is called ‘Young and Feeble’), but it’ showing a lot of promise. It’s already capable of verifying that each module, class, and method of your code is documented. The upcoming release adds coverage checking for each parameter to a method (and other goodies, see below).
One of the biggest problems with writing generic documentation coverage tools is that there is a real lack of standards for documentation. Jeremy MacAnally, the author of dcov, is trying to build some consensus on this. Take a look at his blog post on the topic. (Feel free to toss in your own two cents while you’re there.)
In the upcoming release, dcov provides a mechanism for writing your own analyzer—it’s still rough, but it looks a lot like an RSpec specification. Here’s the way Jeremy’s implemented parameter checking using the new mechanism:
documentation_for_methods do |the_documentation|
the_documentation.must "document all parameters." do
param_names_for(the_documentation.token).each do |param|
the_documentation.token.reporting_data[:parameters_without_coverage] <
;<
param[0] unless
the_documentation.token.comment.include?("#{param[0]}")
end if the_documentation.token.params
end
end
With this new feature, it should be easy to adapt dcov to whatever documentation standards exist within your own organization.
Jeremy has been working on dcov as part of the Google Summer of Code, he’s being mentored by Chad Fowler.
__________________________--
-pate
http://on-ruby.blogspot.com
Special Magazine Offer -- Free Gift with Subscription
Receive a free digital copy of Linux Journal's System Administration Special Edition as well as instant online access to current and past issues. CLICK HERE for offer
Linux Journal: delivering readers the advice and inspiration they need to get the most out of their Linux systems since 1994.
Subscribe now!
The Latest
Newsletter
Tech Tip Videos
- Jul-01-09
- Jun-29-09
Recently Popular
From the Magazine
July 2009, #183
News Flash: Linux Kernel 3.0 to include an on-the-go Expresso machine interface! Ok, maybe not, but Linux is definitely going mobile, from phones to e-readers. Find out more inside about Android, the Kindle 2, the Western Digital MyBook II, The Bug, and Indamixx (a portable recording studio). And if you've gone mobile and you been wanting more Emacs in your life then check out Conkeror.
To compliment the mobile we've got the stationary: parsing command line options with getopt, checking your Ruby code with metric_fu, and building a secure Squid proxy. How is this stationary you ask? What can we say? It's not. We just wanted to see if anybody actually read this part of the page :) .
All this and more, and all you have to do is get your hot sweaty hands on the latest copy of Linux Journal.
Delicious
Digg
StumbleUpon
Reddit
Facebook








Dcov is something we need
On August 30th, 2007 John Money (not verified) says:
Thanks, I've checked out his blog, and hope that dcov will continue to improve upon itself. Keep us all posted as to it's progress
John
Thank you for an analyzer
On August 29th, 2007 Stella (not verified) says:
Thank you for the article. It was very informing. A problem of document always was. I am above what to think.
Post new comment