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    

Example

To configure the check:

<module name="PackageHtml"/>

Package

com.puppycrawl.tools.checkstyle.checks.javadoc

Parent Module

Checker

JavadocType

Description

Checks Javadoc comments for class and interface definitions. By default, does not check for author or version tags. The scope to verify is specified using the Scope class and defaults to Scope.PRIVATE. To verify another scope, set property scope to one of the Scope constants. To define the format for an author tag or a version tag, set property authorFormat or versionFormat respectively to a regular expression.

Error messages about type parameters for which no param tags are present can be suppressed by defining property allowMissingParamTags.

Properties

name description type default value
scope visibility scope where Javadoc comments are checked    
excludeScope visibility scope where Javadoc comments are not checked    
authorFormat pattern for @author tag   null (tag not required)
versionFormat pattern for @version tag   null (tag not required)
allowMissingParamTags whether to ignore errors when a class has type parameters but does not have matching param tags in the javadoc.    
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>

To configure the check for private classes only:

<module name="JavadocType">
   <property name="scope" value="private"/>
   <property name="excludescope" value="package"/>
</module>

Package

com.puppycrawl.tools.checkstyle.checks.javadoc

Parent Module

TreeWalker

JavadocMethod

Description

Checks the Javadoc of a method or constructor. By default, does not check for unused throws. To allow documented java.lang.RuntimeExceptions that are not declared, set property allowUndeclaredRTE to true. The scope to verify is specified using the Scope class and defaults to Scope.PRIVATE. To verify another scope, set property scope to one of the Scope constants.

Error messages about parameters and type parameters for which no param tags are present can be suppressed by defining property allowMissingParamTags. Error messages about exceptions which are declared to be thrown, but for which no throws tag is present can be suppressed by defining property allowMissingThrowsTags. Error messages about methods which return non-void but for which no return tag is present can be suppressed by defining property allowMissingReturnTag.

An example of how to configure the check is:

<module name="JavadocMethod"/>

An example of how to configure the check to check to allow documentation of undeclared RuntimeExceptions and for the Scope.PUBLIC scope, while ignoring any missing param tags is:

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

Properties

name description type default value
scope visibility scope where Javadoc comments are checked    
excludeScope visibility scope where Javadoc comments are not checked    
allowUndeclaredRTE whether to allow documented exceptions that are not declared if they are a subclass of java.lang.RuntimeException    
allowThrowsTagsForSubclasses whether to allow documented exceptions that are subclass of one of declared exception.    
allowMissingParamTags whether to ignore errors when a method has parameters but does not have matching param tags in the javadoc.    
allowMissingThrowsTags whether to ignore errors when a method declares that it throws exceptions but does have matching throws tags in the javadoc.    
allowMissingReturnTag whether to ignore errors when a method returns non-void type does have a return tag in the javadoc.    
allowMissingJavadoc whether to ignore errors when a method javadoc is missed.    
allowMissingPropertyJavadoc Whether to allow missing Javadoc on accessor methods for properties (setters and getters). The setter and getter methods must match exactly the structures below.
public void setNumber(final int number)
{
    mNumber = number;
}

public int getNumber()
{
    return mNumber;
}

public boolean isSomething()
{
    return 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>

To configure the check for methods which are in private , but not in protected scope:

<module name="JavadocMethod">
   <property name="scope" value="private"/>
   <property name="excludeScope" value="protected"/>
</module>

Notes

Package

com.puppycrawl.tools.checkstyle.checks.javadoc

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    
excludeScope visibility scope where Javadoc comments are not checked    

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>

To configure the check for members which are in private, but not in protected scope:

<module name="JavadocVariable">
   <property name="scope" value="private"/>
   <property name="excludeScope" value="protected"/>
</module>

Package

com.puppycrawl.tools.checkstyle.checks.javadoc

Parent Module

TreeWalker

JavadocStyle

Description

Validates Javadoc comments to help ensure they are well formed. The following checks are performed:

These checks were patterned after the checks made by the DocCheck doclet available from Sun.

Properties

name description type default value
scope visibility scope where Javadoc comments are checked    
excludeScope visibility scope where Javadoc comments are not checked    
checkFirstSentence Whether to check the first sentence for proper end of sentence.    
checkEmptyJavadoc Whether to check if the Javadoc is missing a describing text.    
checkHtml Whether to check for incomplete html tags.    
tokens definitions to check subset of tokens INTERFACE_DEF, CLASS_DEF, METHOD_DEF, CTOR_DEF, VARIABLE_DEF INTERFACE_DEF, CLASS_DEF, METHOD_DEF, CTOR_DEF, VARIABLE_DEF

Examples

To configure the default check:

<module name="JavadocStyle"/>

To configure the check for public scope:

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

To configure the check for javadoc which is in private, but not in package scope:

<module name="JavadocStyle">
   <property name="scope" value="private"/>
   <property name="excludeScope" value="package"/>
</module>

To configure the check to turn off first sentence checking:

<module name="JavadocStyle">
   <property name="checkFirstSentence" value="false"/>
</module>

Package

com.puppycrawl.tools.checkstyle.checks

Parent Module

TreeWalker

Copyright © 2001-2005, Oliver Burn