Measuring Documentation Coverage with Javadoc and Ant

Question

I am involved in a project in which public API documentation is a clear deliverable. In order to ensure that the release meets this requirement, I'd like to ensure that the the release target in my Ant build file fails if documentation coverage is too low.

As a minimum, each identifier with public or protected access should have appropriate Javadoc tags and a description. For example, public methods should have a @param tag for each parameter, a @return tag if the return type is not void, a @throws tag for each exception, and a single line description.

I currently have JUnit code coverage reports and failure conditions using Cobertura, so something similar to that for documentation would be perfect. However, if the detection of a failure condition is not available, a report be a reasonable substitute.

The documentation must be in Javadoc format. No other format -- including Doxygen -- is acceptable.

Answer 1

I don't know such a tool, but I think that Doxygen can generate XML files that describe the code structure together with the comments. You can write a script that will do some simple tests on it and find undocumented methods/params/return values/etc.

Answer 2

Checkstyle can do that.