598 lines
20 KiB
HTML
598 lines
20 KiB
HTML
<?xml version="1.0" encoding="UTF-8"?>
|
|
<!DOCTYPE html
|
|
PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
|
|
"DTD/xhtml1-strict.dtd">
|
|
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
|
|
<head>
|
|
<title>Checks for Javadoc Comments</title>
|
|
<link rel="stylesheet" type="text/css" href="mystyle.css"/>
|
|
</head>
|
|
|
|
<body>
|
|
<!-- The header -->
|
|
<table border="0" width="100%" summary="header layout">
|
|
<tr>
|
|
<td><h1>Checks for Javadoc Comments</h1></td>
|
|
<td align="right"><img src="logo.png" alt="Checkstyle Logo"/></td>
|
|
</tr>
|
|
</table>
|
|
<!-- content -->
|
|
<table border="0" width="100%" cellpadding="5" summary="body layout">
|
|
<tr>
|
|
<!--Left menu-->
|
|
<td class="menu" valign="top">
|
|
<ul>
|
|
<li>
|
|
<a href="#PackageHtml">PackageHtml</a>
|
|
</li>
|
|
<li>
|
|
<a href="#JavadocType">JavadocType</a>
|
|
</li>
|
|
<li>
|
|
<a href="#JavadocMethod">JavadocMethod</a>
|
|
</li>
|
|
<li>
|
|
<a href="#JavadocVariable">JavadocVariable</a>
|
|
</li>
|
|
<li>
|
|
<a href="#JavadocStyle">JavadocStyle</a>
|
|
</li>
|
|
</ul>
|
|
</td>
|
|
<!--Content-->
|
|
<td class="content" valign="top" align="left">
|
|
|
|
<a name="PackageHtml"></a> <h2>PackageHtml</h2> <h4>Description</h4>
|
|
<p class="body">
|
|
Checks that a <span class="code">package.html</span> file exists for each
|
|
package. More specifically, checks that each java file has a package.html sibling.
|
|
</p>
|
|
|
|
<h4 class="body">Properties</h4>
|
|
<table width="100%" border="1" cellpadding="5" class="body">
|
|
<tr class="header">
|
|
<th>name</th>
|
|
<th>description</th>
|
|
<th>type</th>
|
|
<th>default value</th>
|
|
</tr>
|
|
<tr>
|
|
<td>fileExtensions</td>
|
|
<td>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
|
|
<span class="code">.java</span></td>
|
|
<td><a href="property_types.html#stringSet">String Set</a></td>
|
|
<td><span class="default">java</span></td>
|
|
</tr>
|
|
</table>
|
|
|
|
<h4>Example</h4>
|
|
<p class="body">
|
|
To configure the check:
|
|
</p>
|
|
<pre class="body">
|
|
<module name="PackageHtml"/>
|
|
</pre>
|
|
|
|
<h4>Package</h4>
|
|
<p class="body">
|
|
com.puppycrawl.tools.checkstyle.checks.javadoc
|
|
</p>
|
|
<h4>Parent Module</h4>
|
|
<p class="body">
|
|
<a href="config.html#checker">Checker</a>
|
|
</p>
|
|
|
|
<a name="JavadocType"></a> <h2>JavadocType</h2> <h4>Description</h4>
|
|
<p class="body">
|
|
Checks Javadoc comments for class and interface definitions.
|
|
</p>
|
|
|
|
<h4>Properties</h4>
|
|
|
|
<table width="100%" border="1" cellpadding="5" class="body">
|
|
<tr class="header">
|
|
<th>name</th>
|
|
<th>description</th>
|
|
<th>type</th>
|
|
<th>default value</th>
|
|
</tr>
|
|
<tr>
|
|
<td>scope</td>
|
|
<td>visibility scope where Javadoc comments are checked</td>
|
|
<td><a href="property_types.html#scope">scope</a></td>
|
|
<td><span class="default">private</span></td>
|
|
</tr>
|
|
<tr>
|
|
<td>excludeScope</td>
|
|
<td>visibility scope where Javadoc comments are not checked</td>
|
|
<td><a href="property_types.html#scope">scope</a></td>
|
|
<td><span class="default">null</span></td>
|
|
</tr>
|
|
<tr>
|
|
<td>authorFormat</td>
|
|
<td>pattern for @author tag</td>
|
|
<td><a href="property_types.html#regexp">regular expression</a></td>
|
|
<td><span class="default">null</span> (tag not required)</td>
|
|
</tr>
|
|
<tr>
|
|
<td>versionFormat</td>
|
|
<td>pattern for @version tag</td>
|
|
<td><a href="property_types.html#regexp">regular expression</a></td>
|
|
<td><span class="default">null</span> (tag not required)</td>
|
|
</tr>
|
|
<tr>
|
|
<td>tokens</td>
|
|
<td>definitions to check</td>
|
|
|
|
<td>subset of tokens <a
|
|
href="api/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#INTERFACE_DEF">INTERFACE_DEF</a>,
|
|
<a
|
|
href="api/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#CLASS_DEF">CLASS_DEF</a></td>
|
|
|
|
<td><a
|
|
href="api/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#INTERFACE_DEF">INTERFACE_DEF</a>,
|
|
<a
|
|
href="api/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#CLASS_DEF">CLASS_DEF</a>,</td>
|
|
|
|
</tr>
|
|
</table>
|
|
|
|
<h4>Examples</h4>
|
|
<p class="body">
|
|
To configure the default check:
|
|
</p>
|
|
<pre class="body">
|
|
<module name="JavadocType"/>
|
|
</pre>
|
|
<p class="body">
|
|
To configure the check for <span class="default">public</span> scope:
|
|
</p>
|
|
<pre class="body">
|
|
<module name="JavadocType">
|
|
<property name="scope" value="public"/>
|
|
</module>
|
|
</pre>
|
|
<p class="body">
|
|
To configure the check for an @author tag:
|
|
</p>
|
|
<pre class="body">
|
|
<module name="JavadocType">
|
|
<property name="authorFormat" value="\S"/>
|
|
</module>
|
|
</pre>
|
|
<p class="body">
|
|
To configure the check for a CVS revision version tag:
|
|
</p>
|
|
<pre class="body">
|
|
<module name="JavadocType">
|
|
<property name="versionFormat" value="\$Revision.*\$"/>
|
|
</module>
|
|
</pre>
|
|
<p class="body">
|
|
To configure the check for <span
|
|
class="default">private</span> classes only:
|
|
</p>
|
|
<pre class="body">
|
|
<module name="JavadocType">
|
|
<property name="scope" value="private"/>
|
|
<property name="excludescope" value="package"/>
|
|
</module>
|
|
</pre>
|
|
|
|
<h4>Package</h4>
|
|
<p class="body">
|
|
com.puppycrawl.tools.checkstyle.checks.javadoc
|
|
</p>
|
|
<h4>Parent Module</h4>
|
|
<p class="body">
|
|
<a href="config.html#treewalker">TreeWalker</a>
|
|
</p>
|
|
|
|
<a name="JavadocMethod"></a> <h2>JavadocMethod</h2> <h4>Description</h4>
|
|
<p class="body">
|
|
Checks to ensure that the following tags exist (if required):
|
|
</p>
|
|
<ul class="body">
|
|
<li>
|
|
<span class="code">@return</span>
|
|
</li>
|
|
<li>
|
|
<span class="code">@param</span>
|
|
</li>
|
|
<li>
|
|
<span class="code">@throws</span> or <span class="code">@exception</span>
|
|
</li>
|
|
<li>
|
|
<span class="code">@see</span> or <span class="code">{@inheritDoc}</span>
|
|
</li>
|
|
</ul>
|
|
|
|
<p class="body">
|
|
For example, the following is valid:
|
|
</p>
|
|
<a name="checkReturnTag"></a>
|
|
<pre class="body">
|
|
/**
|
|
* 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)
|
|
</pre>
|
|
|
|
<p class="body">
|
|
This supports the convention in the <a href="http://java.sun.com/j2se/javadoc/writingdoccomments/index.html#throwstag">Sun
|
|
Javadoc Guidelines</a> and the "Effective Java" book.
|
|
</p>
|
|
|
|
<h4>Properties</h4>
|
|
|
|
<table width="100%" border="1" cellpadding="5" class="body">
|
|
<tr class="header">
|
|
<th>name</th>
|
|
<th>description</th>
|
|
<th>type</th>
|
|
<th>default value</th>
|
|
</tr>
|
|
<tr>
|
|
<td>scope</td>
|
|
<td>visibility scope where Javadoc comments are checked</td>
|
|
<td><a href="property_types.html#scope">scope</a></td>
|
|
<td><span class="default">private</span></td>
|
|
</tr>
|
|
<tr>
|
|
<td>excludeScope</td>
|
|
<td>visibility scope where Javadoc comments are not checked</td>
|
|
<td><a href="property_types.html#scope">scope</a></td>
|
|
<td><span class="default">null</span></td>
|
|
</tr>
|
|
<tr>
|
|
<td>allowUndeclaredRTE</td>
|
|
<td>whether to allow documented exceptions that
|
|
are not declared if they are a subclass of <span
|
|
class="code">java.lang.RuntimeException</span></td>
|
|
<td><a href="property_types.html#boolean">boolean</a></td>
|
|
<td><span class="default">false</span></td>
|
|
</tr>
|
|
<tr>
|
|
<td>allowThrowsTagsForSubclasses</td>
|
|
<td>whether to allow documented exceptions that
|
|
are subclass of one of declared exception.</td>
|
|
<td><a href="property_types.html#boolean">boolean</a></td>
|
|
<td><span class="default">false</span></td>
|
|
</tr>
|
|
<tr>
|
|
<td>allowMissingParamTags</td>
|
|
<td>whether to ignore errors when a method has parameters
|
|
but does not have matching param tags in the javadoc.</td>
|
|
<td><a href="property_types.html#boolean">boolean</a></td>
|
|
<td><span class="default">false</span></td>
|
|
</tr>
|
|
<tr>
|
|
<td>allowMissingThrowsTags</td>
|
|
<td>whether to ignore errors when a method declares
|
|
that it throws exceptions but does have matching throws tags
|
|
in the javadoc.</td>
|
|
<td><a href="property_types.html#boolean">boolean</a></td>
|
|
<td><span class="default">false</span></td>
|
|
</tr>
|
|
<tr>
|
|
<td>allowMissingReturnTag</td>
|
|
<td>whether to ignore errors when a method returns
|
|
non-void type does have a return tag in the javadoc.</td>
|
|
<td><a href="property_types.html#boolean">boolean</a></td>
|
|
<td><span class="default">false</span></td>
|
|
</tr>
|
|
<tr>
|
|
<td>tokens</td>
|
|
<td>definitions to check</td>
|
|
|
|
<td>subset of tokens <a
|
|
href="api/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#METHOD_DEF">METHOD_DEF</a>,
|
|
<a
|
|
href="api/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#CTOR_DEF">CTOR_DEF</a></td>
|
|
|
|
<td><a
|
|
href="api/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#METHOD_DEF">METHOD_DEF</a>,
|
|
<a
|
|
href="api/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#CTOR_DEF">CTOR_DEF</a></td>
|
|
|
|
</tr>
|
|
</table>
|
|
|
|
<h4>Examples</h4>
|
|
<p class="body">
|
|
To configure the default check:
|
|
</p>
|
|
<pre class="body">
|
|
<module name="JavadocMethod"/>
|
|
</pre>
|
|
<p class="body">
|
|
To configure the check for <span class="default">public</span>
|
|
scope and to allow documentation of undeclared RuntimeExceptions:
|
|
</p>
|
|
<pre class="body">
|
|
<module name="JavadocMethod">
|
|
<property name="scope" value="public"/>
|
|
<property name="allowUndeclaredRTE" value="true"/>
|
|
</module>
|
|
</pre>
|
|
<p class="body">
|
|
To configure the check for methods which are in <span
|
|
class="default">private</span> , but not in <span
|
|
class="default">protected</span> scope:
|
|
</p>
|
|
<pre class="body">
|
|
<module name="JavadocMethod">
|
|
<property name="scope" value="private"/>
|
|
<property name="excludeScope" value="protected"/>
|
|
</module>
|
|
</pre>
|
|
<h4>Notes</h4>
|
|
|
|
<ul class="body">
|
|
<li>The classpath may need to be configured to locate the class information. The
|
|
classpath configuration is dependent on the mechanism used to invoke Checkstyle.
|
|
</li>
|
|
|
|
<li>
|
|
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 <span class="code">@see</span> or <span class="code">{@inheritDoc}</span> tag instead of all the other tags. For
|
|
example, if the <a href="#checkReturnTag">above method</a> was implementing a method required by the <span class="code">
|
|
com.puppycrawl.tools.checkstyle.Verifier</span> interface, then the Javadoc
|
|
could be done as:
|
|
|
|
<pre class="body">
|
|
/** @see com.puppycrawl.tools.checkstyle.Verifier **/
|
|
public int checkReturnTag(final int aTagIndex,
|
|
JavadocTag[] aTags,
|
|
int aLineNo)
|
|
</pre>
|
|
|
|
or:
|
|
<pre class="body">
|
|
/** {@inheritDoc} **/
|
|
public int checkReturnTag(final int aTagIndex,
|
|
JavadocTag[] aTags,
|
|
int aLineNo)
|
|
</pre>
|
|
|
|
</li>
|
|
</ul>
|
|
<h4>Package</h4>
|
|
<p class="body">
|
|
com.puppycrawl.tools.checkstyle.checks.javadoc
|
|
</p>
|
|
<h4>Parent Module</h4>
|
|
<p class="body">
|
|
<a href="config.html#treewalker">TreeWalker</a>
|
|
</p>
|
|
|
|
|
|
<a name="JavadocVariable"></a> <h2>JavadocVariable</h2> <h4>Description</h4>
|
|
<p class="body">
|
|
Checks that variables have Javadoc comments.
|
|
</p>
|
|
<h4>Properties</h4>
|
|
|
|
<table width="100%" border="1" cellpadding="5" class="body">
|
|
<tr class="header">
|
|
<th>name</th>
|
|
<th>description</th>
|
|
<th>type</th>
|
|
<th>default value</th>
|
|
</tr>
|
|
<tr>
|
|
<td>scope</td>
|
|
<td>visibility scope where Javadoc comments are checked</td>
|
|
<td><a href="property_types.html#scope">scope</a></td>
|
|
<td><span class="default">private</span></td>
|
|
</tr>
|
|
<tr>
|
|
<td>excludeScope</td>
|
|
<td>visibility scope where Javadoc comments are not checked</td>
|
|
<td><a href="property_types.html#scope">scope</a></td>
|
|
<td><span class="default">null</span></td>
|
|
</tr>
|
|
</table>
|
|
|
|
<h4>Examples</h4>
|
|
<p class="body">
|
|
To configure the default check:
|
|
</p>
|
|
<pre class="body">
|
|
<module name="JavadocVariable"/>
|
|
</pre>
|
|
<p class="body">
|
|
To configure the check for <span class="default">public</span> scope:
|
|
</p>
|
|
<pre class="body">
|
|
<module name="JavadocVariable">
|
|
<property name="scope" value="public"/>
|
|
</module>
|
|
</pre>
|
|
<p class="body">
|
|
To configure the check for members which are in <span
|
|
class="default">private</span>, but not in <span
|
|
class="default">protected</span> scope:
|
|
</p>
|
|
<pre class="body">
|
|
<module name="JavadocVariable">
|
|
<property name="scope" value="private"/>
|
|
<property name="excludeScope" value="protected"/>
|
|
</module>
|
|
</pre>
|
|
<h4>Package</h4>
|
|
<p class="body">
|
|
com.puppycrawl.tools.checkstyle.checks.javadoc
|
|
</p>
|
|
<h4>Parent Module</h4>
|
|
<p class="body">
|
|
<a href="config.html#treewalker">TreeWalker</a>
|
|
</p>
|
|
|
|
|
|
<a name="JavadocStyle"></a>
|
|
<h2>JavadocStyle</h2>
|
|
<h4>Description</h4>
|
|
|
|
<p class="body">
|
|
Validates Javadoc comments to help ensure they are well formed.
|
|
The following checks are performed:
|
|
</p>
|
|
|
|
<ul>
|
|
|
|
<li> 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.
|
|
</li>
|
|
|
|
<li> 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.</li>
|
|
|
|
<li> 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.</li>
|
|
|
|
</ul>
|
|
|
|
<p>These checks were patterned after the checks made by the <a
|
|
href="http://java.sun.com/j2se/javadoc/doccheck/index.html">DocCheck</a>
|
|
doclet available from Sun. </p>
|
|
|
|
<h4>Properties</h4>
|
|
|
|
<table width="100%" border="1" cellpadding="5" class="body">
|
|
<tr class="header">
|
|
<th>name</th>
|
|
<th>description</th>
|
|
<th>type</th>
|
|
<th>default value</th>
|
|
</tr>
|
|
<tr>
|
|
<td>scope</td>
|
|
<td>visibility scope where Javadoc comments are checked</td>
|
|
<td><a href="property_types.html#scope">scope</a></td>
|
|
<td><span class="default">private</span></td>
|
|
</tr>
|
|
<tr>
|
|
<td>excludeScope</td>
|
|
<td>visibility scope where Javadoc comments are not checked</td>
|
|
<td><a href="property_types.html#scope">scope</a></td>
|
|
<td><span class="default">null</span></td>
|
|
</tr>
|
|
<tr>
|
|
<td>checkFirstSentence</td>
|
|
<td>Whether to check the first sentence for proper end of sentence.</td>
|
|
<td><a href="property_types.html#boolean">boolean</a></td>
|
|
<td><span class="default">true</span></td>
|
|
</tr>
|
|
<tr>
|
|
<td>checkEmptyJavadoc</td>
|
|
<td>Whether to check if the Javadoc is missing a describing text.</td>
|
|
<td><a href="property_types.html#boolean">boolean</a></td>
|
|
<td><span class="default">false</span></td>
|
|
</tr>
|
|
<tr>
|
|
<td>checkHtml</td>
|
|
<td>Whether to check for incomplete html tags.</td>
|
|
<td><a href="property_types.html#boolean">boolean</a></td>
|
|
<td><span class="default">true</span></td>
|
|
</tr>
|
|
<tr>
|
|
<td>tokens</td>
|
|
<td>definitions to check</td>
|
|
|
|
<td>subset of tokens
|
|
<a href="api/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#INTERFACE_DEF">INTERFACE_DEF</a>,
|
|
<a href="api/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#CLASS_DEF">CLASS_DEF</a>,
|
|
<a href="api/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#METHOD_DEF">METHOD_DEF</a>,
|
|
<a href="api/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#CTOR_DEF">CTOR_DEF</a>,
|
|
<a href="api/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#VARIABLE_DEF">VARIABLE_DEF</a>
|
|
</td>
|
|
<td>
|
|
<a href="api/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#INTERFACE_DEF">INTERFACE_DEF</a>,
|
|
<a href="api/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#CLASS_DEF">CLASS_DEF</a>,
|
|
<a href="api/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#METHOD_DEF">METHOD_DEF</a>,
|
|
<a href="api/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#CTOR_DEF">CTOR_DEF</a>,
|
|
<a href="api/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#VARIABLE_DEF">VARIABLE_DEF</a>
|
|
</td>
|
|
|
|
</tr>
|
|
</table>
|
|
|
|
<h4>Examples</h4>
|
|
|
|
<p class="body">
|
|
To configure the default check:
|
|
</p>
|
|
|
|
<pre class="body">
|
|
<module name="JavadocStyle"/>
|
|
</pre>
|
|
|
|
<p class="body">
|
|
To configure the check for <span class="default">public</span> scope:
|
|
</p>
|
|
|
|
<pre class="body">
|
|
<module name="JavadocStyle">
|
|
<property name="scope" value="public"/>
|
|
</module>
|
|
</pre>
|
|
<p class="body">
|
|
To configure the check for javadoc which is in <span
|
|
class="default">private</span>, but not in <span
|
|
class="default">package</span> scope:
|
|
</p>
|
|
|
|
<pre class="body">
|
|
<module name="JavadocStyle">
|
|
<property name="scope" value="private"/>
|
|
<property name="excludeScope" value="package"/>
|
|
</module>
|
|
</pre>
|
|
<p class="body">
|
|
To configure the check to turn off first sentence checking:
|
|
</p>
|
|
<pre class="body">
|
|
<module name="JavadocStyle">
|
|
<property name="checkFirstSentence" value="false"/>
|
|
</module>
|
|
</pre>
|
|
|
|
<p class="body">
|
|
|
|
<h4>Package</h4>
|
|
<p class="body">
|
|
com.puppycrawl.tools.checkstyle.checks
|
|
</p>
|
|
<h4>Parent Module</h4>
|
|
<p class="body">
|
|
<a href="config.html#treewalker">TreeWalker</a>
|
|
</p>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
<hr />
|
|
<div><a href="index.html">Back to the Checkstyle Home Page</a></div>
|
|
<p class="copyright">
|
|
Copyright © 2002-2003 Oliver Burn. All rights Reserved.
|
|
</p>
|
|
|
|
</body>
|
|
</html>
|