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
- The Tiny Internet Project, Part I
- Machine Learning with Python
- SUSECON 2016: Where Technology Reigns Supreme
- Download "Linux Management with Red Hat Satellite: Measuring Business Impact and ROI"
- Free Today: September Issue of Linux Journal (Retail value: $5.99)
- Bitcoin on Amazon! Sort of...
- Securing the Programmer
- Android Browser Security--What You Haven't Been Told
- Epiq Solutions' Sidekiq M.2
Pick up any e-commerce web or mobile app today, and you’ll be holding a mashup of interconnected applications and services from a variety of different providers. For instance, when you connect to Amazon’s e-commerce app, cookies, tags and pixels that are monitored by solutions like Exact Target, BazaarVoice, Bing, Shopzilla, Liveramp and Google Tag Manager track every action you take. You’re presented with special offers and coupons based on your viewing and buying patterns. If you find something you want for your birthday, a third party manages your wish list, which you can share through multiple social- media outlets or email to a friend. When you select something to buy, you find yourself presented with similar items as kind suggestions. And when you finally check out, you’re offered the ability to pay with promo codes, gifts cards, PayPal or a variety of credit cards.Get the Guide