Checks for Javadoc Comments

Checkstyle will check that the following constructs have a Javadoc comment:

class
interface
variable
method

The property checkstyle.javadoc.scope controls the visibility scope where Javadoc comments are checked. The property type is scope and defaults to private.

For example, you can check Javadoc comments only for public and protected definitions by setting the property to protected. Scoping rules apply, so a public method in a package visible class is not checked.

package.html check

The property checkstyle.require.packagehtml controls whether to require that a package.html file exists for each package. The property type is boolean and defaults to false.

Class/Interface Javadoc checks

The property checkstyle.require.version controls whether to require an @version tag to be defined for class and interface Javadoc comments. The property type is boolean and defaults to false.

The property checkstyle.allow.noauthor controls whether to allow no @author tag to be defined for class and interface Javadoc comments. The property type is boolean and defaults to false.

Method Javadoc checks

Javadoc comments for methods are checked to ensure that the following tags exist (if required):

@return
@param
@throws or @exception
@see

For example the following is valid:

    /**
     * Checks for a return tag.
     * @return the index of the next unchecked tag
     * @param aTagIndex the index to start in the tags
     * @param aTags the tags to check
     * @param aLineNo the line number of the expected tag
     **/
    public int checkReturnTag(final int aTagIndex,
                              JavadocTag[] aTags,
                              int aLineNo)

The property checkstyle.javadoc.checkUnusedThrows controls whether to check if an undocumented exception is a subclass of java.lang.RuntimeException. The property type is boolean and defaults to false.

This supports the convention in the Sun Javadoc Guidelines and the "Effective Java" book.

The classpath may need to be configured to locate the class information. The classpath configuration is dependent on the mechanism used to invoke Checkstyle.

Tip

It can be extremely painful writing or duplicating Javadoc for a method required for an interface. Hence checkstyle supports using the convention of using a single @see tag instead of all the other tags. For example, if the previous method was implementing a method required by the com.puppycrawl.tools.checkstyle.Verifier interface, then the Javadoc could be done as:

    /** @see com.puppycrawl.tools.checkstyle.Verifier **/
    public int checkReturnTag(final int aTagIndex,
                              JavadocTag[] aTags,
                              int aLineNo)