<?xml version="1.0" encoding="ISO-8859-1"?>

<document xmlns="http://maven.apache.org/XDOC/2.0"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/XDOC/2.0 http://maven.apache.org/xsd/xdoc-2.0.xsd">

  <properties>
    <title>Javadoc Comments</title>
    <author>Checkstyle Development Team</author>
  </properties>

  <body>
    <section name="JavadocPackage">
      <subsection name="Description">
        <p>
          Checks that each Java package has a Javadoc file used for
          commenting.  By default it only allows a <code>package-info.java</code> file, but can be
          configured to allow a <code>package.html</code>
          file.
        </p>
        <p>
          An error will be reported if both files exist as this is not
          allowed by the Javadoc tool.
        </p>
      </subsection>

      <subsection name="Properties">
        <table>
          <tr>
            <th>name</th>
            <th>description</th>
            <th>type</th>
            <th>default value</th>
          </tr>
          <tr>
            <td>allowLegacy</td>
            <td>
              If set then allow the use of a
              <code>package.html</code> file.
            </td>
            <td><a href="property_types.html#boolean">boolean</a></td>
            <td><code>false</code></td>
          </tr>
        </table>
      </subsection>

      <subsection name="Example">
        <p>
          To configure the check:
        </p>
        <source>
&lt;module name="JavadocPackage"/&gt;
        </source>
      </subsection>

      <subsection name="Package">
        <p>
          com.puppycrawl.tools.checkstyle.checks.javadoc
        </p>
      </subsection>

      <subsection name="Parent Module">
        <p>
          <a href="config.html#Checker">Checker</a>
        </p>
      </subsection>
    </section>

    <section name="JavadocType">
      <subsection name="Description">
        <p>
          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 <code>Scope</code>
          class and defaults to <code>Scope.PRIVATE</code>. To verify
          another scope, set property scope to one of the
          <code>Scope</code> constants.  To define the format for an
          author tag or a version tag, set property authorFormat or
          versionFormat respectively to a
          <a href="http://java.sun.com/j2se/1.4.2/docs/api/java/util/regex/Pattern.html">
            regular expression</a>.
        </p>
        <p>
          Error messages about type parameters for which no param tags are
          present can be suppressed by defining property
          <code>allowMissingParamTags</code>.
        </p>
      </subsection>

      <subsection name="Properties">
        <table>
          <tr>
            <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><code>private</code></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><code>null</code></td>
          </tr>
          <tr>
            <td>authorFormat</td>
            <td>pattern for @author tag</td>
            <td><a href="property_types.html#regexp">regular expression</a></td>
            <td><code>null</code> (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><code>null</code> (tag not required)</td>
          </tr>
          <tr>
            <td>allowMissingParamTags</td>
            <td>whether to ignore errors when a class has type parameters
                but does not have matching param tags in the javadoc.</td>
            <td><a href="property_types.html#boolean">boolean</a></td>
            <td><code>false</code></td>
          </tr>
          <tr>
            <td>allowUnknownTags</td>
            <td>whether to ignore errors when a Javadoc tag is not recognised.</td>
            <td><a href="property_types.html#boolean">boolean</a></td>
            <td><code>false</code></td>
          </tr>
          <tr>
            <td>tokens</td>
            <td>definitions to check</td>
            <td>
              subset of tokens <a
              href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#INTERFACE_DEF">INTERFACE_DEF</a>,
              <a
            href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#CLASS_DEF">CLASS_DEF</a>
            </td>
            <td>
              <a
               href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#INTERFACE_DEF">INTERFACE_DEF</a>,
               <a
            href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#CLASS_DEF">CLASS_DEF</a>,
            </td>
          </tr>
        </table>
      </subsection>

      <subsection name="Examples">
        <p>
          To configure the default check:
        </p>
        <source>
&lt;module name="JavadocType"/&gt;
        </source>

        <p>
          To configure the check for <code>public</code> scope:
        </p>
        <source>
&lt;module name="JavadocType"&gt;
   &lt;property name="scope" value="public"/&gt;
&lt;/module&gt;
        </source>

        <p>
          To configure the check for an @author tag:
        </p>
        <source>
&lt;module name="JavadocType"&gt;
   &lt;property name="authorFormat" value="\S"/&gt;
&lt;/module&gt;
        </source>

        <p>
          To configure the check for a CVS revision version tag:
        </p>
        <source>
&lt;module name="JavadocType"&gt;
   &lt;property name="versionFormat" value="\$Revision.*\$"/&gt;
&lt;/module&gt;
        </source>

        <p>
          To configure the check for <code>private</code> classes only:
        </p>
        <source>
&lt;module name="JavadocType"&gt;
   &lt;property name="scope" value="private"/&gt;
   &lt;property name="excludescope" value="package"/&gt;
&lt;/module&gt;
        </source>
      </subsection>

      <subsection name="Package">
        <p>
          com.puppycrawl.tools.checkstyle.checks.javadoc
        </p>
      </subsection>

      <subsection name="Parent Module">
        <p>
          <a href="config.html#TreeWalker">TreeWalker</a>
        </p>
      </subsection>
    </section>

    <section name="JavadocMethod">
      <subsection name="Description">
        <p>
          Checks the Javadoc of a method or constructor. By default,
          does not check for unused throws. To allow documented
          <code>java.lang.RuntimeException</code>s that are not
          declared, set property allowUndeclaredRTE to true. The scope
          to verify is specified using the <code>Scope</code> class and
          defaults to <code>Scope.PRIVATE</code>. To verify another
          scope, set property scope to a different
          <a href="property_types.html#scope">scope</a>.
        </p>

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

        <p>
          Javadoc is not required on a method that is tagged with the
          <code>@Override</code> annotation. However under
          Java 5 it is not possible to mark a method required for an
          interface (this was <i>corrected</i> under Java 6). Hence
          Checkstyle supports using the convention of using a single
          <code>{@inheritDoc}</code> tag instead of all the
          other tags.
        </p>

        <p>
          Note that only inheritable items will allow the
          <code>{@inheritDoc}</code> tag to be used in place
          of comments.  Static methods at all visibilities, private non-static
          methods and constructors are not inheritable.
        </p>

        <p>
          For example, if the following method is
          implementing a method required by an interface, then the
          Javadoc could be done as:
        </p>

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

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

      <subsection name="Properties">
        <table>
          <tr>
            <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><code>private</code></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><code>null</code></td>
          </tr>
          <tr>
            <td>allowUndeclaredRTE</td>
            <td>whether to allow documented exceptions that
            are not declared if they are a subclass of <code>java.lang.RuntimeException</code></td>
            <td><a href="property_types.html#boolean">boolean</a></td>
            <td><code>false</code></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><code>false</code></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><code>false</code></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><code>false</code></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><code>false</code></td>
          </tr>

          <tr>
            <td>allowMissingJavadoc</td>
            <td>whether to ignore errors when a method javadoc is missed.</td>
            <td><a href="property_types.html#boolean">boolean</a></td>
            <td><code>false</code></td>
          </tr>

          <tr>
            <td>allowMissingPropertyJavadoc</td>
            <td>
              Whether to allow missing Javadoc on accessor methods for
              properties (setters and getters). The setter and getter
              methods must match exactly the structures below.

              <pre>
public void setNumber(final int number)
{
    mNumber = number;
}

public int getNumber()
{
    return mNumber;
}

public boolean isSomething()
{
    return false;
}
              </pre>
            </td>
            <td><a href="property_types.html#boolean">boolean</a></td>
            <td><code>false</code></td>
          </tr>
          <tr>
            <td>logLoadErrors</td>
            <td>This check may need to load exception classes mentioned in
            the @throws tag to check whether they are RuntimeExceptions.
            If loading the class fails, this property allows to control
            checkstyle's error handling. If set to <code>false</code> a
            classpath configuration problem is assumed and the TreeWalker
            stops operating on the class completely.
            If set to <code>true</code> (the default) , checkstyle assumes a
            typo or refactoring problem in the
            javadoc and logs the problem in the normal checkstyle report
            (potentially masking a configuration error).</td>
            <td><a href="property_types.html#boolean">boolean</a></td>
            <td><code>true</code></td>
          </tr>
          <tr>
            <td>suppressLoadErrors</td>
            <td>When logLoadErrors is set to true, the TreeWalker completely
            processes a class and displays any problems with loading exceptions
            as checkstyle violations.
            When this property is set to true, the violations generated when
            logLoadErrors is set true are suppressed from being reported as
            violations in the checkstyle report.
            </td>
            <td><a href="property_types.html#boolean">boolean</a></td>
            <td><code>false</code></td>
          </tr>
          <tr>
            <td>tokens</td>
            <td>definitions to check</td>

            <td>subset of tokens <a
            href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#METHOD_DEF">METHOD_DEF</a>,
            <a
            href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#CTOR_DEF">CTOR_DEF</a></td>

            <td><a
            href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#METHOD_DEF">METHOD_DEF</a>,
            <a
            href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#CTOR_DEF">CTOR_DEF</a></td>

          </tr>
        </table>
      </subsection>

      <subsection name="Examples">
        <p>
          To configure the default check:
        </p>
        <source>
&lt;module name="JavadocMethod"/&gt;
        </source>

        <p>
          To configure the check for <code>public</code>
          scope and to allow documentation of undeclared
          RuntimeExceptions:
        </p>
        <source>
&lt;module name="JavadocMethod"&gt;
   &lt;property name="scope" value="public"/&gt;
   &lt;property name="allowUndeclaredRTE" value="true"/&gt;
&lt;/module&gt;
        </source>

        <p>
          To configure the check for for <code>public</code>
          scope, to allow documentation of undeclared RuntimeExceptions,
          while ignoring any missing param tags is:
        </p>

        <source>
&lt;module name=&quot;JavadocMethod&quot;&gt;
  &lt;property name=&quot;scope&quot; value=&quot;public&quot;/&gt;
  &lt;property name=&quot;allowUndeclaredRTE&quot; value=&quot;true&quot;/&gt;
  &lt;property name=&quot;allowMissingParamTags&quot; value=&quot;true&quot;/&gt;
&lt;/module&gt;
        </source>

        <p>
          To configure the check for methods which are in <code>private</code> , but not in <code>protected</code> scope:
        </p>
        <source>
&lt;module name="JavadocMethod"&gt;
   &lt;property name="scope" value="private"/&gt;
   &lt;property name="excludeScope" value="protected"/&gt;
&lt;/module&gt;
        </source>
      </subsection>

      <subsection name="Package">
        <p>
          com.puppycrawl.tools.checkstyle.checks.javadoc
        </p>
      </subsection>

      <subsection name="Parent Module">
        <p>
          <a href="config.html#TreeWalker">TreeWalker</a>
        </p>
      </subsection>
    </section>

    <section name="JavadocVariable">
      <subsection name="Description">
        <p>
          Checks that variables have Javadoc comments.
        </p>
      </subsection>

      <subsection name="Properties">
        <table>
          <tr>
            <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><code>private</code></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><code>null</code></td>
          </tr>
        </table>
      </subsection>

      <subsection name="Examples">
        <p>
          To configure the default check:
        </p>
        <source>
&lt;module name="JavadocVariable"/&gt;
        </source>

        <p>
          To configure the check for <code>public</code>
          scope:
        </p>

        <source>
&lt;module name="JavadocVariable"&gt;
   &lt;property name="scope" value="public"/&gt;
&lt;/module&gt;
        </source>

        <p>
          To configure the check for members which are in <code>private</code>, but not in <code>protected</code> scope:
        </p>

        <source>
&lt;module name="JavadocVariable"&gt;
   &lt;property name="scope" value="private"/&gt;
   &lt;property name="excludeScope" value="protected"/&gt;
&lt;/module&gt;
        </source>
      </subsection>

      <subsection name="Package">
        <p>
          com.puppycrawl.tools.checkstyle.checks.javadoc
        </p>
      </subsection>

      <subsection name="Parent Module">
        <p>
          <a href="config.html#TreeWalker">TreeWalker</a>
        </p>
      </subsection>
    </section>

    <section name="JavadocStyle">
      <subsection name="Description">
        <p>
          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, by default).
            Javadoc automatically places the first sentence in the
            method summary table and index.  With out proper punctuation
            the Javadoc may be malformed.  All items eligible for the
            <code>{@inheritDoc}</code> tag are exempt from this
            requirement.
          </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>
          <li>
           Check that a package Javadoc comment is well-formed (as
           described above) and NOT missing from any package-info.java
           files.
          </li>
          <li>
            Check for allowed HTML tags. The list of allowed HTML tags
            is "a", "abbr", "acronym", "address", "area", "b", "bdo",
            "big", "blockquote", "br", "caption", "cite", "code",
            "colgroup", "del", "div", "dfn", "dl", "em", "fieldset",
            "h1" to "h6", "hr", "i", "img", "ins", "kbd", "li", "ol",
            "p", "pre", "q", "samp", "small", "span", "strong", "sub",
            "sup", "table", "tbody", "td", "tfoot", "th", "thread",
            "tr", "tt", "ul".
          </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>
      </subsection>

      <subsection name="Properties">
        <table>
          <tr>
            <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><code>private</code></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><code>null</code></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><code>true</code></td>
          </tr>
          <tr>
            <td>endOfSentenceFormat</td>
            <td>
              Format for matching the end of a sentence.
            </td>
            <td><a href="property_types.html#regexp">regular expression</a></td>
            <td><code>([.?!][ \t\n\r\f&lt;])|([.?!]$)</code></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><code>false</code></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><code>true</code></td>
          </tr>
          <tr>
            <td>tokens</td>
            <td>definitions to check</td>

            <td>
              subset of tokens <a
              href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#INTERFACE_DEF">INTERFACE_DEF</a>,
              <a
                  href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#CLASS_DEF">CLASS_DEF</a>,
              <a
                  href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#METHOD_DEF">METHOD_DEF</a>,
              <a
                  href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#CTOR_DEF">CTOR_DEF</a>,
              <a
                  href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#VARIABLE_DEF">VARIABLE_DEF</a>
            </td>

            <td>
              <a
                  href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#INTERFACE_DEF">INTERFACE_DEF</a>,
              <a
                  href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#CLASS_DEF">CLASS_DEF</a>,
              <a
                  href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#METHOD_DEF">METHOD_DEF</a>,
              <a
                  href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#CTOR_DEF">CTOR_DEF</a>,
              <a
                  href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#VARIABLE_DEF">VARIABLE_DEF</a>
            </td>
          </tr>
        </table>
      </subsection>

      <subsection name="Examples">
        <p>
          To configure the default check:
        </p>

        <source>
&lt;module name="JavadocStyle"/&gt;
        </source>

        <p>
          To configure the check for <code>public</code>
          scope:
        </p>

        <source>
&lt;module name="JavadocStyle"&gt;
   &lt;property name="scope" value="public"/&gt;
&lt;/module&gt;
        </source>

        <p>
          To configure the check for javadoc which is in <code>private</code>, but not in <code>package</code> scope:
        </p>

        <source>
&lt;module name="JavadocStyle"&gt;
   &lt;property name="scope" value="private"/&gt;
   &lt;property name="excludeScope" value="package"/&gt;
&lt;/module&gt;
        </source>

        <p>
          To configure the check to turn off first sentence checking:
        </p>

        <source>
&lt;module name="JavadocStyle"&gt;
   &lt;property name="checkFirstSentence" value="false"/&gt;
&lt;/module&gt;
        </source>
      </subsection>

      <subsection name="Package">
        <p>
          com.puppycrawl.tools.checkstyle.checks
        </p>
      </subsection>

      <subsection name="Parent Module">
        <p>
          <a href="config.html#TreeWalker">TreeWalker</a>
        </p>
      </subsection>
    </section>

    <section name="WriteTag">
      <subsection name="Description">
        <p>
         Outputs a JavaDoc tag as information. Can be used e.g. with the
         stylesheets that sort the report by author name.  To define the
         format for a tag, set property tagFormat to a regular
         expression.  This check uses two different severity levels. The
         normal one is used for reporting when the tag is missing. The
         additional one (tagSeverity) is used for the level of reporting
         when the tag exists.
        </p>
      </subsection>

      <subsection name="Properties">
        <table>
          <tr>
            <th>name</th>
            <th>description</th>
            <th>type</th>
            <th>default value</th>
          </tr>
          <tr>
            <td>tag</td>
            <td>Name of tag</td>
            <td><a href="property_types.html#string">String</a></td>
           <td><code>null</code></td>
          </tr>
          <tr>
            <td>tagFormat</td>
            <td>Format of tag</td>
            <td><a href="property_types.html#regexp">regular expression</a></td>
            <td><code>null</code></td>
          </tr>
          <tr>
            <td>tagSeverity</td>
            <td>Severity level when tag is found and printed</td>
            <td><a href="property_types.html#severity">severity</a></td>
            <td><code>info</code></td>
          </tr>
        </table>
      </subsection>

      <subsection name="Examples">
        <p>
        An example of how to configure the check for printing author name is:
        </p>

        <source>
&lt;module name="WriteTag"&gt;
   &lt;property name="tag" value="@author"/&gt;
   &lt;property name="tagFormat" value="\S"/&gt;
&lt;/module&gt;
        </source>

        <p>
         An example of how to configure the check to print warnings if an
         "@incomplete" tag is found, and not print anything if it is not found:
        </p>

        <source>
&lt;module name="WriteTag"&gt;
   &lt;property name="tag" value="@incomplete"/&gt;
   &lt;property name="tagFormat" value="\S"/&gt;
   &lt;property name="severity" value="ignore"/&gt;
   &lt;property name="tagSeverity" value="warning"/&gt;
&lt;/module&gt;
        </source>
      </subsection>

      <subsection name="Package">
        <p>
          com.puppycrawl.tools.checkstyle.checks
        </p>
      </subsection>

      <subsection name="Parent Module">
        <p>
          <a href="config.html#TreeWalker">TreeWalker</a>
        </p>
      </subsection>
    </section>
  </body>
</document>
