Checks for Javadoc Comments

PackageHtml

Description

Checks that a package.html file exists for each package. More specifically, checks that each java file has a package.html sibling.

Properties

name	description	type	default value
fileExtensions	file type extension to identify java files. Setting this property is typically only required if your java source files are preprocessed and the original files do not have the extension .java	String Set	java

Example

To configure the check:

<module name="PackageHtml"/>

Package

com.puppycrawl.tools.checkstyle.checks

Parent Module

Checker

JavadocType

Description

Checks Javadoc comments for class and interface definitions.

Properties

name	description	type	default value
scope	visibility scope where Javadoc comments are checked	scope	private
authorFormat	pattern for @author tag	regular expression	null (tag not required)
versionFormat	pattern for @version tag	regular expression	null (tag not required)
tokens	definitions to check	subset of tokens INTERFACE_DEF, CLASS_DEF	INTERFACE_DEF, CLASS_DEF,

Examples

To configure the default check:

<module name="JavadocType"/>

To configure the check for public scope:

<module name="JavadocType">
   <property name="scope" value="public"/>
</module>

To configure the check for an @author tag:

<module name="JavadocType">
   <property name="authorFormat" value="\S"/>
</module>

To configure the check for a CVS revision version tag:

<module name="JavadocType">
   <property name="versionFormat" value="\$Revision.*\$"/>
</module>

Package

com.puppycrawl.tools.checkstyle.checks

Parent Module

TreeWalker

JavadocMethod

Description

Checks to ensure that the following tags exist (if required):

@return
@param
@throws or @exception
@see or {@inheritDoc}

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)

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

Properties

name	description	type	default value
scope	visibility scope where Javadoc comments are checked	scope	private
allowUndeclaredRTE	whether to allow documented exceptions that are not declared if they are a subclass of java.lang.RuntimeException	boolean	false
allowThrowsTagsForSubclasses	whether to allow documented exceptions that are subclass of one of declared exception.	boolean	false
allowMissingParamTags	whether to ignore errors when a method has parameters but does not have matching param tags in the javadoc.	boolean	false
allowMissingThrowsTags	whether to ignore errors when a method declares that it throws exceptions but does have matching throws tags in the javadoc.	boolean	false
allowMissingReturnTag	whether to ignore errors when a method returns non-void type does have a return tag in the javadoc.	boolean	false
tokens	definitions to check	subset of tokens METHOD_DEF, CTOR_DEF	METHOD_DEF, CTOR_DEF

Examples

To configure the default check:

<module name="JavadocMethod"/>

To configure the check for public scope and to allow documentation of undeclared RuntimeExceptions:

<module name="JavadocMethod">
   <property name="scope" value="public"/>
   <property name="allowUndeclaredRTE" value="true"/>
</module>

Notes

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

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 or {@inheritDoc} tag instead of all the other tags. For example, if the above 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)

or:

    /** {@inheritDoc} **/
    public int checkReturnTag(final int aTagIndex,
                              JavadocTag[] aTags,
                              int aLineNo)

Package

com.puppycrawl.tools.checkstyle.checks

Parent Module

TreeWalker

JavadocVariable

Description

Checks that variables have Javadoc comments.

Properties

name	description	type	default value
scope	visibility scope where Javadoc comments are checked	scope	private

Examples

To configure the default check:

<module name="JavadocVariable"/>

To configure the check for public scope:

<module name="JavadocVariable">
   <property name="scope" value="public"/>
</module>

Package

com.puppycrawl.tools.checkstyle.checks

Parent Module

TreeWalker