BT

Google SoC Series: dcov - Ruby documentation coverage analyzer

by Werner Schuster on Jun 21, 2007 |
Static analysis tools are very useful to keep an eye on code quality, particularly if they're integrated in an automatic build process.  rcov, for example, determines test coverage for Ruby code. A new Google SoC sponsored project called dcov now allows to determine the documentation coverage of Ruby code.

The developer of the project, Jeremy McAnally, explains:
Dcov analyzes the documentation in your project and provides you with a coverage rating (similar to rcov) and (eventually) coverage quality ratings.
[Analysis is] done per functional unit: class, method, and module.
Coverage Quality analysis will make dcov even more interesting:
Right now it's just "Is there a comment?" When the quality analysis comes into play, then things will get more interesting.
Just checking if a functional unit has a comment is useful, but could lead to developers adding useless comments just to get good ratings from dcov. Determining whether a comment is useful or not is a difficult task, so Jeremy made this part of dcov pluggable: 
I actually just refactored the code today to make analyzers separate, hot pluggable classes, so the user can add/remove at will. I'm hoping we'll get some seriously smart linguistic programming guys and gals on the project to help us gauge quality.
The output of dcov will be based on existing Ruby tools too:
I'm in the process of adding Ruby Reports (Ruport) support to the code base, which means we'll output reports in a wide variety of formats as they become available from the Ruport team.
Ruport is an extensible reporting system which allows to take data from a number of input source types (CSV, ActiveRecord models, etc.) and generate reports in various formats (PDF, HTML, etc.).

Since dcov analyses Ruby code, it's interesting to see what tools Jeremy used for this:
All code is parsed by the RDoc "parse_files" method and then we take the parsed structure and analyze it. I started to try to find a way to do it manually that was cleaner (or to use something like parse_tree), but I found that RDoc made sense because (a) it's simpler and (b) it's part of the standard Ruby distribution, so everyone should have it.
RDoc provides access to Ruby code via Code Objects, which represent classes, methods, etc. and their comments. 

The project is hosted at RubyForge, Jeremy will be maintaining a blog too. Jeremy also has a book "Mr. Neighborly's Humble Little Ruby Book" available here at InfoQ.

Hello stranger!

You need to Register an InfoQ account or or login to post comments. But there's so much more behind being registered.

Get the most out of the InfoQ experience.

Tell us what you think

Allowed html: a,b,br,blockquote,i,li,pre,u,ul,p

Email me replies to any of my messages in this thread
Community comments

Allowed html: a,b,br,blockquote,i,li,pre,u,ul,p

Email me replies to any of my messages in this thread

Allowed html: a,b,br,blockquote,i,li,pre,u,ul,p

Email me replies to any of my messages in this thread

Discuss

Educational Content

General Feedback
Bugs
Advertising
Editorial
InfoQ.com and all content copyright © 2006-2014 C4Media Inc. InfoQ.com hosted at Contegix, the best ISP we've ever worked with.
Privacy policy
BT