• [ << ]
  • [ 0 ]
  • [ 1 ]
  • [ >> ]
Jul '09
26

NCSS JavaDoc Method Check

I've created a JavaDoc Method Check that only flags sufficiently complex methods as having missing JavaDoc. Methods on interfaces are always flagged if they don't have any. 'Sufficiently complex' is determined by the Non Commenting Source Statements (NCSS) algorithm and a configurable threshold value, which defaults to 5.

Downloading and building the check from source.

First download the source archive (LGPL License). In it you will find two versions of the check, one for Checkstyle 4.4 and one for 5.0. You can build them using Maven (mvn clean install). Inside the ./target directory you will find the jar file.

Configuring Checkstyle.

In order to use the check the jar file must be on the classpath of checkstyle and the check must be configured in the checkstyle configuration. There are many ways of accomplishing the first, depending on your environment setup. I will only discuss the configuration for the maven-checkstyle-plugin (a little further).

The other thing that needs to be done is tell Checkstyle to use this check instead of the old one. For this you'll need to edit your Checkstyle configuration file and replace the existing JavadocMethod check with the following:

              
<module name="nl.t42.checkstyle.javadoc.NCSSJavadocMethodCheck">
 <property name="allowMissingPropertyJavadoc" value="true"/>
 <property name="scope" value="public"/>
 <property name="maxNoJavadocNCSS" value="5"/>
</module>
              

Configuring the maven-checkstyle-plugin

Currently (07-2009) Mavens checkstyle plugin only supports Checkstyle 4.x so we'll be using 4.4 version. Normally you'll declare the usage of checkstyle in the reporting section of the pom.xml .

              
<reporting><plugins><plugin>
 <groupId>org.apache.maven.plugins</groupId>
 <artifactId>maven-checkstyle-plugin</artifactId> 
 <configuration> 
 <configLocation>checkstyle.xml</configLocation> 
 <failOnViolation>false</failOnViolation> 
 </configuration> 
</plugin></plugins></reporting>
              

Now we want to add the ncss javadoc method check as an dependency to this plugin. In more recent versions of Maven you can just add a <dependency> tag to the plugin inside the reporting section, like this:

              
<dependencies><dependency>
 <groupId>nl.t42.checkstyle</groupId>
 <artifactId>checkstyle-smartJavadoc</artifactId>
 <version>4.4</version>
</dependency></dependencies>
              

However if you're using Maven 2.0.9 for example, it doesn't support dependencies in the reporting section, so you need to make use of a feature: Declare the report plugin with its dependencies (but without its configuration) in the build section of the pom. And then declare it again without the dependencies but with its configuration in the reporting section.

And thus the Great JavaDoc War came to an end.

Conclusion

The NCSS Javadoc Method check provides a middle ground between the 'everything must have full JavaDoc' and 'the code we write is so good it does not need any' viewpoints. It is generally easily integrated into existing tools. I have submitted this check to the Checkstyle community in the hope they will include it in future releases.

Happy JavaDoccing!

  • [ << ]
  • [ 0 ]
  • [ 1 ]
  • [ >> ]