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[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

Comments

Comment viewing options

Select your preferred way to display the comments and click "Save settings" to activate your changes.

Dcov is something we need

John Money's picture

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

Stella's picture

Thank you for the article. It was very informing. A problem of document always was. I am above what to think.

White Paper
Fabric-Based Computing Enables Optimized Hyperscale Data Centers

Today’s modular x86 servers are compute-centric, designed as a least common denominator to support a wide range of IT workloads. Those generic, virtualized IT workloads have much different resource optimization requirements than hyperscale and cloud applications. They have resulted in a “one size fits all” enterprise IT architecture that is not optimized for a specific set of IT workloads, and especially not emerging hyperscale workloads, such as web applications, big data, and object storage. In this report, you will learn how shifting the focus from traditional compute-centric IT architectures to an innovative disaggregated fabric-based architecture can optimize and scale your data center.

Learn More

Sponsored by AMD

White Paper
Red Hat White Paper: Using an Open Source Framework to Catch the Bad Guy

Built-in forensics, incident response, and security with Red Hat Enterprise Linux 6

Every security policy provides guidance and requirements for ensuring adequate protection of information and data, as well as high-level technical and administrative security requirements for a system in a given environment. Traditionally, providing security for a system focuses on the confidentiality of the information on it. However, protecting the data integrity and system and data availability is just as important. For example, when processing United States intelligence information, there are three attributes that require protection: confidentiality, integrity, and availability.

Learn more about catching the bad guy in this free white paper.

Learn More

Sponsored by DLT Solutions