# 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.javadoc

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

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

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

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

#### 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:

- Ensures the first sentence ends with proper punctuation (That is a period, question mark, or exclamation mark). Javadoc automatically places the first sentence in the method summary table and index. With out proper punctuation the Javadoc may be malformed.
- Check text for Javadoc statements that do not have any description. This includes both completely empty Javadoc, and Javadoc with only tags such as @param and @return.
- Check text for incomplete HTML tags. Verifies that HTML tags have corresponding end tags and issues an "Unclosed HTML tag found:" error if not. An "Extra HTML tag found:" error is issued if an end tag is found without a previous open tag.

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 | scope | private
excludeScope | visibility scope where Javadoc comments are not checked | scope | null
checkFirstSentence | Whether to check the first sentence for proper end of sentence. | boolean | true
checkEmptyJavadoc | Whether to check if the Javadoc is missing a describing text. | boolean | false
checkHtml | Whether to check for incomplete html tags. | boolean | true
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

Back to the Checkstyle Home Page

Copyright © 2002-2003 Oliver Burn. All rights Reserved.