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
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
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.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
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.javadoc
Parent Module
TreeWalker
JavadocVariable Description
Checks that variables have Javadoc comments.
Properties
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.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 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
scope |
visibility scope where Javadoc comments are checked |
scope |
private |
checkFirstSentence |
Whether to check the first sentence for proper end of sentence. |
boolean |
true |
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 to turn off first sentence checking:
<module name="JavadocStyle">
<property name="checkFirstSentence" value="false"/>
</module>
Package
com.puppycrawl.tools.checkstyle.checks
Parent Module
TreeWalker
|