Documentation Coverage Testing With dcov
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 unless the_documentation.token.comment.include?("") 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.
-- -pate http://on-ruby.blogspot.com
- Two Pi R
- Readers' Choice Awards 2013
- AIDE—Developing for Android on Android
- Best. Cake. Ever.
- The Geek's Guide to the Coolest 2013 Holiday Gifts
- A Handy U-Boot Trick
- Sublime Text: One Editor to Rule Them All?
- Raspberry Pi: the Perfect Home Server
- RSS Feeds
- Tech Tip: Really Simple HTTP Server with Python
- Uber jealous
3 hours 20 min ago
- Reality is disapointing
13 hours 52 min ago
- Máy sấy quần áo
16 hours 39 min ago
- Services on GlusterFS
16 hours 48 min ago
- Reply to comment | Linux Journal
18 hours 28 min ago
- Definitely cool stuff here
19 hours 30 min ago
- thanks for the information
20 hours 41 min ago
- nice information thanks
21 hours 20 min ago
1 day 15 min ago
- The lost opportunity of security
1 day 12 hours ago