Google SoC Series: dcov - Ruby documentation coverage analyzer

Posted by Werner Schuster on Jun 21, 2007

Sections

Process & Practices,

Architecture & Design,

Development

Topics

Code Analysis ,

Ruby ,

Programming

Tags

Static Analysis ,

Google Summer of Code ,

Documentation ,

Code Coverage ,

Coding Standards ,

Reporting

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.

• Older >