<?xml version="1.0" encoding="UTF-8"?>

<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">

  <head>
    <title>Annotations</title>
    <script type="text/javascript"
            src="https://ajax.googleapis.com/ajax/libs/jquery/2.1.3/jquery.min.js"/>
    <script type="text/javascript" src="js/anchors.js"/>
    <script type="text/javascript" src="js/google-analytics.js"/>
    <link rel="icon" href="images/favicon.png" type="image/x-icon" />
    <link rel="shortcut icon" href="images/favicon.ico" type="image/ico" />
  </head>

  <body>
    <section name="Content">
      <macro name="toc">
        <param name="fromDepth" value="1"/>
        <param name="toDepth" value="1"/>
      </macro>
    </section>

    <section name="AnnotationLocation">
      <p>Since Checkstyle 6.0</p>
      <subsection name="Description" id="AnnotationLocation_Description">
        <p>
          Checks location of annotation on language elements.
          By default, Check enforce to locate annotations immediately after documentation block
          and before target element, annotation should be located on separate line from target
          element. This check also verifies that the annotations are on the same indenting level as
          the annotated element if they are not on the same line.
        </p>
        <p>
          Attention: Elements that cannot have JavaDoc comments like local variables are not in the
          scope of this check even though a token type like <code>VARIABLE_DEF</code> would match
          them.
        </p>
        <p>
          Attention: Annotations among modifiers are ignored (looks like false-negative)
          as there might be a problem with annotations for return types:
        </p>
        <source>public @Nullable Long getStartTimeOrNull() { ... }</source>
        <p>
          Such annotations are better to keep close to type.
          Due to limitations, Checkstyle can not examine the target of an annotation.
        </p>
        <p>
          Example:
        </p>
        <source>
@Override
@Nullable
public String getNameIfPresent() { ... }
        </source>
      </subsection>

      <subsection name="Properties" id="AnnotationLocation_Properties">
        <div class="wrapper">
          <table>
            <tr>
              <th>name</th>
              <th>description</th>
              <th>type</th>
              <th>default value</th>
              <th>since</th>
            </tr>
            <tr>
              <td>allowSamelineMultipleAnnotations</td>
              <td>Allow annotation(s) to be located on the same line as target element.</td>
              <td><a href="property_types.html#boolean">Boolean</a></td>
             <td><code>false</code></td>
              <td>6.0</td>
            </tr>
            <tr>
              <td>allowSamelineSingleParameterlessAnnotation</td>
              <td>Allow single parameterless annotation to be located on the same line as
                  target element.</td>
              <td><a href="property_types.html#boolean">Boolean</a></td>
              <td><code>true</code></td>
              <td>6.1</td>
            </tr>
            <tr>
              <td>allowSamelineParameterizedAnnotation</td>
              <td>Allow one and only parameterized annotation to be located on the same line as
                  target element.</td>
              <td><a href="property_types.html#boolean">Boolean</a></td>
              <td><code>false</code></td>
              <td>6.4</td>
            </tr>
            <tr>
              <td>tokens</td>
              <td>tokens to check</td>
              <td>subset of tokens
                <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#INTERFACE_DEF">
                    INTERFACE_DEF</a>,
                <a href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#PACKAGE_DEF">
                    PACKAGE_DEF</a>,
                <a href=
                    "apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#ENUM_CONSTANT_DEF">
                    ENUM_CONSTANT_DEF</a>,
                <a href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#ENUM_DEF">
                    ENUM_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>,
                <a href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#ANNOTATION_DEF">
                    ANNOTATION_DEF</a>,
                <a href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#ANNOTATION_FIELD_DEF">
                    ANNOTATION_FIELD_DEF</a>.
              </td>
              <td>
                <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#INTERFACE_DEF">
                    INTERFACE_DEF</a>,
                <a href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#PACKAGE_DEF">
                    PACKAGE_DEF</a>,
                <a href=
                    "apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#ENUM_CONSTANT_DEF">
                    ENUM_CONSTANT_DEF</a>,
                <a href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#ENUM_DEF">
                    ENUM_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>6.0</td>
            </tr>
          </table>
        </div>
      </subsection>

      <subsection name="Examples" id="AnnotationLocation_Examples">
        <p>
          Example to allow multiple annotations on the same line
        </p>
        <source>
@SuppressWarnings("deprecation") @Mock DataLoader loader; // no violations
        </source>
        <p>
          Use the following configuration:
        </p>
        <source>
&lt;module name=&quot;AnnotationLocation&quot;&gt;
  &lt;property name=&quot;allowSamelineMultipleAnnotations&quot; value=&quot;true&quot;/&gt;
  &lt;property name=&quot;allowSamelineSingleParameterlessAnnotation&quot;
    value=&quot;false&quot;/&gt;
  &lt;property name=&quot;allowSamelineParameterizedAnnotation&quot; value=&quot;false&quot;/&gt;
&lt;/module&gt;
        </source>
        <p>
          Example to allow one single parameterless annotation on the same line
        </p>
        <source>
@Override public int hashCode() { ... } // no violations
@SuppressWarnings("deprecation") public int foo() { ... } // violation
        </source>
        <p>
          Use the following configuration:
        </p>
        <source>
&lt;module name=&quot;AnnotationLocation&quot;&gt;
  &lt;property name=&quot;allowSamelineMultipleAnnotations&quot; value=&quot;false&quot;/&gt;
  &lt;property name=&quot;allowSamelineSingleParameterlessAnnotation&quot;
    value=&quot;true&quot;/&gt;
  &lt;property name=&quot;allowSamelineParameterizedAnnotation&quot; value=&quot;false&quot;/&gt;
&lt;/module&gt;
        </source>
        <p>
          Example to allow only one and only parameterized annotation on the same line
        </p>
        <source>
@SuppressWarnings("deprecation") DataLoader loader; // no violations
@Mock DataLoader loader; // violation
        </source>
        <p>
          Use the following configuration:
        </p>
        <source>
&lt;module name=&quot;AnnotationLocation&quot;&gt;
  &lt;property name=&quot;allowSamelineMultipleAnnotations&quot; value=&quot;false&quot;/&gt;
  &lt;property name=&quot;allowSamelineSingleParameterlessAnnotation&quot;
    value=&quot;false&quot;/&gt;
  &lt;property name=&quot;allowSamelineParameterizedAnnotation&quot; value=&quot;true&quot;/&gt;
&lt;/module&gt;
        </source>
      </subsection>

      <subsection name="Example of Usage" id="AnnotationLocation_Example_of_Usage">
        <ul>
          <li>
            <a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fresources+filename%3Agoogle_checks.xml+repo%3Acheckstyle%2Fcheckstyle+AnnotationLocation">
            Google Style</a>
          </li>
          <li>
            <a href="https://github.com/search?q=path%3Aconfig+filename%3Acheckstyle_checks.xml+repo%3Acheckstyle%2Fcheckstyle+AnnotationLocation">
            Checkstyle Style</a>
          </li>
        </ul>
      </subsection>

      <subsection name="Violation Messages" id="AnnotationLocation_Violation_Messages">
        <ul>
          <li>
            <a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fresources%2Fcom%2Fpuppycrawl%2Ftools%2Fcheckstyle%2Fchecks%2Fannotation+filename%3Amessages*.properties+repo%3Acheckstyle%2Fcheckstyle+%22annotation.location%22">
            annotation.location</a>
          </li>
          <li>
            <a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fresources%2Fcom%2Fpuppycrawl%2Ftools%2Fcheckstyle%2Fchecks%2Fannotation+filename%3Amessages*.properties+repo%3Acheckstyle%2Fcheckstyle+%22annotation.location.alone%22">
            annotation.location.alone</a>
          </li>
        </ul>
        <p>
          All messages can be customized if the default message doesn't suit you.
          Please <a href="config.html#Custom_messages">see the documentation</a> to learn how to.
        </p>
      </subsection>

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

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

    <section name="AnnotationOnSameLine">
      <p>Since Checkstyle 8.2</p>
      <subsection name="Description" id="AnnotationOnSameLine_Description">
        <p>
          Checks that annotations are located on the same line with their targets.
          Verifying with this check is not good practice, but it is using by some style guides.
        </p>
      </subsection>

      <subsection name="Properties" id="AnnotationOnSameLine_Properties">
        <div class="wrapper">
          <table>
            <tr>
              <th>name</th>
              <th>description</th>
              <th>type</th>
              <th>default value</th>
              <th>since</th>
            </tr>
            <tr>
              <td>tokens</td>
              <td>tokens to check</td>
              <td>subset of tokens
                <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#INTERFACE_DEF">
                    INTERFACE_DEF</a>,
                <a href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#ENUM_DEF">
                    ENUM_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>,
                <a href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#PARAMETER_DEF">
                    PARAMETER_DEF</a>,
                <a href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#ANNOTATION_DEF">
                    ANNOTATION_DEF</a>,
                <a href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#TYPECAST">
                    TYPECAST</a>,
                <a href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#LITERAL_THROWS">
                    LITERAL_THROWS</a>,
                <a href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#IMPLEMENTS_CLAUSE">
                    IMPLEMENTS_CLAUSE</a>,
                <a href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#TYPE_ARGUMENT">
                    TYPE_ARGUMENT</a>,
                <a href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#LITERAL_NEW">
                    LITERAL_NEW</a>,
                <a href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#DOT">DOT</a>,
                <a href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#ANNOTATION_FIELD_DEF">
                    ANNOTATION_FIELD_DEF</a>.
              </td>
              <td>
                <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#INTERFACE_DEF">
                    INTERFACE_DEF</a>,
                <a href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#ENUM_DEF">
                    ENUM_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>8.2</td>
            </tr>
          </table>
        </div>
      </subsection>

      <subsection name="Examples" id="AnnotationOnSameLine_Examples">
        <p>
          To configure the check:
        </p>
        <source>
&lt;module name=&quot;AnnotationOnSameLine&quot;/&gt;
        </source>
        <p>
          Example to allow annotations on the same line
        </p>
        <source>
@Override public int toString() { ... } // no violations
@Before @Override public void set() { ... } // no violation
        </source>
        <p>
          Example to disallow annotations on previous line
        </p>
        <source>
@SuppressWarnings("deprecation") // violation
@Override // violation
public int foo() { ... }
        </source>
      </subsection>

      <subsection name="Example of Usage" id="AnnotationOnSameLine_Example_of_Usage">
        <ul>
          <li>
            <a href="https://github.com/search?q=path%3Aconfig+filename%3Acheckstyle_checks.xml+repo%3Acheckstyle%2Fcheckstyle+AnnotationOnSameLine">
            Checkstyle Style</a>
          </li>
        </ul>
      </subsection>

      <subsection name="Violation Messages" id="AnnotationOnSameLine_Violation_Messages">
        <ul>
          <li>
            <a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fresources%2Fcom%2Fpuppycrawl%2Ftools%2Fcheckstyle%2Fchecks%2Fannotation+filename%3Amessages*.properties+repo%3Acheckstyle%2Fcheckstyle+%22annotation.same.line%22">
            annotation.same.line</a>
          </li>
        </ul>
        <p>
          All messages can be customized if the default message doesn't suit you.
          Please <a href="config.html#Custom_messages">see the documentation</a> to learn how to.
        </p>
      </subsection>

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

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

    <section name="AnnotationUseStyle">
      <p>Since Checkstyle 5.0</p>
      <subsection name="Description" id="AnnotationUseStyle_Description">
        <p>
          Checks the style of elements in annotations.
        </p>
        <p>
          Annotations have three element styles starting with the least verbose.
        </p>
        <ul>
          <li><code>ElementStyle.COMPACT_NO_ARRAY</code></li>
          <li><code>ElementStyle.COMPACT</code></li>
          <li><code>ElementStyle.EXPANDED</code></li>
        </ul>
        <p>
          To not enforce an element style a <code>ElementStyle.IGNORE</code> type is provided.
          The desired style can be set through the <code>elementStyle</code> property.
        </p>
        <p>
          Using the <code>ElementStyle.EXPANDED</code> style is more verbose.
          The expanded version is sometimes referred to as "named parameters" in other languages.
        </p>
        <p>
          Using the <code>ElementStyle.COMPACT</code> style is less verbose.
          This style can only be used when there is an element called 'value' which is either
          the sole element or all other elements have default values.
        </p>
        <p>
          Using the <code>ElementStyle.COMPACT_NO_ARRAY</code> style is less verbose.
          It is similar to the <code>ElementStyle.COMPACT</code> style but single value arrays
          are flagged.
          With annotations a single value array does not need to be placed in an array initializer.
        </p>
        <p>
          The ending parenthesis are optional when using annotations with no elements.
          To always require ending parenthesis use the <code>ClosingParens.ALWAYS</code> type.
          To never have ending parenthesis use the <code>ClosingParens.NEVER</code> type.
          To not enforce a closing parenthesis preference a <code>ClosingParens.IGNORE</code>
          type is provided. Set this through the <code>closingParens</code> property.
        </p>
        <p>
          Annotations also allow you to specify arrays of elements in a standard format.
          As with normal arrays, a trailing comma is optional.
          To always require a trailing comma use the <code>TrailingArrayComma.ALWAYS</code> type.
          To never have a trailing comma use the <code>TrailingArrayComma.NEVER</code> type.
          To not enforce a trailing array comma preference a <code>TrailingArrayComma.IGNORE</code>
          type is provided.
          Set this through the <code>trailingArrayComma</code> property.
        </p>
        <p>
          By default the <code>ElementStyle</code> is set to <code>COMPACT_NO_ARRAY</code>,
          the <code>TrailingArrayComma</code> is set to <code>NEVER</code>,
          and the <code>ClosingParens</code> is set to <code>NEVER</code>.
        </p>
        <p>
          According to the JLS, it is legal to include a trailing comma
          in arrays used in annotations but Sun's Java 5 &amp; 6 compilers will not
          compile with this syntax. This may in be a bug in Sun's compilers
          since eclipse 3.4's built-in compiler does allow this syntax as
          defined in the JLS. Note: this was tested with compilers included with
          JDK versions 1.5.0.17 and 1.6.0.11 and the compiler included with eclipse 3.4.1.
        </p>
        <p>
          See <a href="https://docs.oracle.com/javase/specs/jls/se11/html/jls-9.html#jls-9.7">
          Java Language specification, &#167;9.7</a>.
        </p>
      </subsection>
      <subsection name="Properties" id="AnnotationUseStyle_Properties">
        <div class="wrapper">
          <table>
            <tr>
              <th>name</th>
              <th>description</th>
              <th>type</th>
              <th>default value</th>
              <th>since</th>
            </tr>
            <tr>
              <td>elementStyle</td>
              <td>
                Define the annotation element styles.
              </td>
              <td>
                <a href="property_types.html#elementStyle">Element Style</a>
              </td>
              <td>
                <code>compact_no_array</code>
              </td>
              <td>5.0</td>
            </tr>
            <tr>
              <td>closingParens</td>
              <td>
                Define the policy for ending parenthesis.
              </td>
              <td>
                <a href="property_types.html#closingParens">Closing Parens</a>
              </td>
              <td>
                <code>never</code>
              </td>
              <td>5.0</td>
            </tr>
            <tr>
              <td>trailingArrayComma</td>
              <td>
                Define the policy for trailing comma in arrays.
              </td>
              <td>
                <a href="property_types.html#trailingArrayComma">Trailing Comma</a>
              </td>
              <td>
                <code>never</code>
              </td>
              <td>5.0</td>
            </tr>
          </table>
        </div>
      </subsection>
      <subsection name="Examples" id="AnnotationUseStyle_Examples">
        <p> To configure the check:</p>
        <source>
&lt;module name=&quot;AnnotationUseStyle&quot;/&gt;
        </source>

        <p>
          To configure the check to enforce an <code>expanded</code> style,
          with a trailing array comma set to <code>never</code>
          and always including the closing parenthesis.
        </p>
        <source>
&lt;module name=&quot;AnnotationUseStyle&quot;&gt;
  &lt;property name=&quot;elementStyle&quot; value=&quot;expanded&quot;/&gt;
  &lt;property name=&quot;trailingArrayComma&quot; value=&quot;never&quot;/&gt;
  &lt;property name=&quot;closingParens&quot; value=&quot;always&quot;/&gt;
&lt;/module&gt;
        </source>
      </subsection>

      <subsection name="Example of Usage" id="AnnotationUseStyle_Example_of_Usage">
        <ul>
          <li>
            <a href="https://github.com/search?q=path%3Aconfig+filename%3Acheckstyle_checks.xml+repo%3Acheckstyle%2Fcheckstyle+AnnotationUseStyle">
            Checkstyle Style</a>
          </li>
        </ul>
      </subsection>

      <subsection name="Violation Messages" id="AnnotationUseStyle_Violation_Messages">
        <ul>
          <li>
            <a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fresources%2Fcom%2Fpuppycrawl%2Ftools%2Fcheckstyle%2Fchecks%2Fannotation+filename%3Amessages*.properties+repo%3Acheckstyle%2Fcheckstyle+%22annotation.incorrect.style%22">
            annotation.incorrect.style</a>
          </li>
          <li>
            <a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fresources%2Fcom%2Fpuppycrawl%2Ftools%2Fcheckstyle%2Fchecks%2Fannotation+filename%3Amessages*.properties+repo%3Acheckstyle%2Fcheckstyle+%22annotation.parens.missing%22">
            annotation.parens.missing</a>
          </li>
          <li>
            <a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fresources%2Fcom%2Fpuppycrawl%2Ftools%2Fcheckstyle%2Fchecks%2Fannotation+filename%3Amessages*.properties+repo%3Acheckstyle%2Fcheckstyle+%22annotation.parens.present%22">
            annotation.parens.present</a>
          </li>
          <li>
            <a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fresources%2Fcom%2Fpuppycrawl%2Ftools%2Fcheckstyle%2Fchecks%2Fannotation+filename%3Amessages*.properties+repo%3Acheckstyle%2Fcheckstyle+%22annotation.trailing.comma.missing%22">
            annotation.trailing.comma.missing</a>
          </li>
          <li>
            <a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fresources%2Fcom%2Fpuppycrawl%2Ftools%2Fcheckstyle%2Fchecks%2Fannotation+filename%3Amessages*.properties+repo%3Acheckstyle%2Fcheckstyle+%22annotation.trailing.comma.present%22">
            annotation.trailing.comma.present</a>
          </li>
        </ul>
        <p>
          All messages can be customized if the default message doesn't suit you.
          Please <a href="config.html#Custom_messages">see the documentation</a> to learn how to.
        </p>
      </subsection>

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

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

    <section name="MissingDeprecated">
      <p>Since Checkstyle 5.0</p>
      <subsection name="Description" id="MissingDeprecated_Description">
        <p>
          Verifies that the annotation <code>@Deprecated</code> and the Javadoc tag
          <code>@deprecated</code> are both present when either of them is present.
        </p>
        <p>
          Both ways of flagging deprecation serve their own purpose.
          The @Deprecated annotation is used for compilers and development tools.
          The @deprecated javadoc tag is used to document why something is deprecated
          and what, if any, alternatives exist.
        </p>
        <p>
          In order to properly mark something as deprecated both forms of
          deprecation should be present.
        </p>
        <p>
          Package deprecation is a exception to the rule of always using the
          javadoc tag and annotation to deprecate.  It is not clear if the
          javadoc tool will support it or not as newer versions keep flip flopping
          on if it is supported or will cause an error.
          See <a href="https://bugs.openjdk.java.net/browse/JDK-8160601">
          JDK-8160601</a>.
          The deprecated javadoc tag is currently the only way to say why the package
          is deprecated and what to use instead.  Until this is resolved, if you
          don't want to print violations on package-info, you can use a
          <a href="config_filters.html">filter</a> to ignore these files until
          the javadoc tool faithfully supports it. An example config using
          SuppressionSingleFilter is:
        </p>
        <source>
&lt;!-- required till https://bugs.openjdk.java.net/browse/JDK-8160601 --&gt;
&lt;module name=&quot;SuppressionSingleFilter&quot;&gt;
    &lt;property name=&quot;checks&quot; value=&quot;MissingDeprecatedCheck&quot;/&gt;
    &lt;property name=&quot;files&quot; value=&quot;package-info\.java&quot;/&gt;
&lt;/module&gt;
        </source>
      </subsection>
      <subsection name="Properties" id="MissingDeprecated_Properties">
        <div class="wrapper">
          <table>
            <tr>
              <th>name</th>
              <th>description</th>
              <th>type</th>
              <th>default value</th>
              <th>since</th>
            </tr>
            <tr>
              <td>violateExecutionOnNonTightHtml</td>
              <td>
                Control when to print violations if the Javadoc being examined by this check
                violates the tight html rules defined at
                <a href="writingjavadocchecks.html#Tight-HTML_rules">Tight-HTML Rules</a>.</td>
              <td><a href="property_types.html#boolean">Boolean</a></td>
              <td><code>false</code></td>
              <td>8.24</td>
            </tr>
          </table>
        </div>
      </subsection>
      <subsection name="Examples" id="MissingDeprecated_Examples">
        <p> To configure the check:</p>
        <source>
&lt;module name=&quot;MissingDeprecated&quot;/&gt;
        </source>
        <p>Examples of validating source code:</p>
        <source>
@deprecated
public static final int MY_CONST = 123456; // no violation

/** This javadoc is missing deprecated tag. */
@deprecated
public static final int COUNTER = 10; // violation
        </source>
      </subsection>

      <subsection name="Example of Usage" id="MissingDeprecated_Example_of_Usage">
        <ul>
          <li>
            <a href="https://github.com/search?q=path%3Aconfig+filename%3Acheckstyle_checks.xml+repo%3Acheckstyle%2Fcheckstyle+MissingDeprecated">
            Checkstyle Style</a>
          </li>
        </ul>
      </subsection>

      <subsection name="Violation Messages" id="MissingDeprecated_Violation_Messages">
        <ul>
          <li>
            <a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fresources%2Fcom%2Fpuppycrawl%2Ftools%2Fcheckstyle%2Fchecks%2Fannotation+filename%3Amessages*.properties+repo%3Acheckstyle%2Fcheckstyle+%22annotation.missing.deprecated%22">
            annotation.missing.deprecated</a>
          </li>
          <li>
            <a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fresources%2Fcom%2Fpuppycrawl%2Ftools%2Fcheckstyle%2Fchecks%2Fannotation+filename%3Amessages*.properties+repo%3Acheckstyle%2Fcheckstyle+%22javadoc.duplicateTag%22">
            javadoc.duplicateTag</a>
          </li>
          <li>
            <a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fresources%2Fcom%2Fpuppycrawl%2Ftools%2Fcheckstyle%2Fchecks%2Fannotation+filename%3Amessages*.properties+repo%3Acheckstyle%2Fcheckstyle+%22javadoc.missed.html.close%22">
            javadoc.missed.html.close</a>
          </li>
          <li>
            <a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fresources%2Fcom%2Fpuppycrawl%2Ftools%2Fcheckstyle%2Fchecks%2Fannotation+filename%3Amessages*.properties+repo%3Acheckstyle%2Fcheckstyle+%22javadoc.parse.rule.error%22">
            javadoc.parse.rule.error</a>
          </li>
          <li>
            <a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fresources%2Fcom%2Fpuppycrawl%2Ftools%2Fcheckstyle%2Fchecks%2Fannotation+filename%3Amessages*.properties+repo%3Acheckstyle%2Fcheckstyle+%22javadoc.wrong.singleton.html.tag%22">
            javadoc.wrong.singleton.html.tag</a>
          </li>
        </ul>
        <p>
          All messages can be customized if the default message doesn't suit you.
          Please <a href="config.html#Custom_messages">see the documentation</a> to learn how to.
        </p>
      </subsection>

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

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

    <section name="MissingOverride">
      <p>Since Checkstyle 5.0</p>
      <subsection name="Description" id="MissingOverride_Description">
        <p>
          Verifies that the <code>@Override</code> annotation is present
          when the <code>@inheritDoc</code> javadoc tag is present.
        </p>
        <p>
          Rationale: The @Override annotation helps
          compiler tools ensure that an override is actually occurring.  It is
          quite easy to accidentally overload a method or hide a static method
          and using the @Override annotation points out these problems.
        </p>
        <p>
          This check will log a violation if using the @inheritDoc tag on a method that
          is not valid (ex: private, or static method).
        </p>
        <p>
          There is a slight difference between the @Override annotation in Java 5 versus
          Java 6 and above. In Java 5, any method overridden from an interface cannot
          be annotated with @Override. In Java 6 this behavior is allowed.
        </p>
        <p>
          As a result of the aforementioned difference between Java 5 and Java 6, a
          property called <code>javaFiveCompatibility</code> is available. This
          property will only check classes, interfaces, etc. that do not contain the
          extends or implements keyword or are not anonymous classes. This means it
          only checks methods overridden from <code>java.lang.Object</code>.
          <b>Java 5 Compatibility mode severely limits this check. It is recommended to
          only use it on Java 5 source.</b>
        </p>

      </subsection>
      <subsection name="Properties" id="MissingOverride_Properties">
        <div class="wrapper">
          <table>
            <tr>
              <th>name</th>
              <th>description</th>
              <th>type</th>
              <th>default value</th>
              <th>since</th>
            </tr>
            <tr>
              <td>javaFiveCompatibility</td>
              <td>
                Enable java 5 compatibility mode.
              </td>
              <td>
                <a href="property_types.html#boolean">Boolean</a>
              </td>
              <td>
                <code>false</code>
              </td>
              <td>5.0</td>
            </tr>
          </table>
        </div>
      </subsection>
      <subsection name="Examples" id="MissingOverride_Examples">
        <p> To configure the check:</p>
        <source>
&lt;module name=&quot;MissingOverride&quot;/&gt;
        </source>

        <p>
          To configure the check for the <code>javaFiveCompatibility</code>
          mode:
        </p>
        <source>
&lt;module name=&quot;MissingOverride&quot;&gt;
  &lt;property name=&quot;javaFiveCompatibility&quot;
      value=&quot;true&quot;/&gt;
&lt;/module&gt;
        </source>
      </subsection>

      <subsection name="Example of Usage" id="MissingOverride_Example_of_Usage">
        <ul>
          <li>
            <a href="https://github.com/search?q=path%3Aconfig+filename%3Acheckstyle_checks.xml+repo%3Acheckstyle%2Fcheckstyle+MissingOverride">
            Checkstyle Style</a>
          </li>
        </ul>
      </subsection>

      <subsection name="Violation Messages" id="MissingOverride_Violation_Messages">
        <ul>
          <li>
            <a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fresources%2Fcom%2Fpuppycrawl%2Ftools%2Fcheckstyle%2Fchecks%2Fannotation+filename%3Amessages*.properties+repo%3Acheckstyle%2Fcheckstyle+%22annotation.missing.override%22">
            annotation.missing.override</a>
          </li>
          <li>
            <a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fresources%2Fcom%2Fpuppycrawl%2Ftools%2Fcheckstyle%2Fchecks%2Fannotation+filename%3Amessages*.properties+repo%3Acheckstyle%2Fcheckstyle+%22tag.not.valid.on%22">
            tag.not.valid.on</a>
          </li>
        </ul>
        <p>
          All messages can be customized if the default message doesn't suit you.
          Please <a href="config.html#Custom_messages">see the documentation</a> to learn how to.
        </p>
      </subsection>

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

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

    <section name="PackageAnnotation">
      <p>Since Checkstyle 5.0</p>
      <subsection name="Description" id="PackageAnnotation_Description">
        <p>
          Checks that all package annotations are in the package-info.java file.
        </p>
        <p>
             According to the Java Language Specification.
        </p>

        <p>
            The JLS does not enforce the placement of package annotations.
            This placement may vary based on implementation. The JLS
            does highly recommend that all package annotations are
            placed in the package-info.java file.

            See <a
            href="https://docs.oracle.com/javase/specs/jls/se11/html/jls-7.html#jls-7.4.1">
            Java Language Specification, &#167;7.4.1</a>.
        </p>
      </subsection>

      <subsection name="Examples" id="PackageAnnotation_Examples">
        <p> To configure the check:</p>
        <source> &lt;module name=&quot;PackageAnnotation&quot;/&gt;
        </source>
      </subsection>

      <subsection name="Example of Usage" id="PackageAnnotation_Example_of_Usage">
        <ul>
          <li>
            <a href="https://github.com/search?q=path%3Aconfig+filename%3Acheckstyle_checks.xml+repo%3Acheckstyle%2Fcheckstyle+PackageAnnotation">
            Checkstyle Style</a>
          </li>
        </ul>
      </subsection>

      <subsection name="Violation Messages" id="PackageAnnotation_Violation_Messages">
        <ul>
          <li>
            <a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fresources%2Fcom%2Fpuppycrawl%2Ftools%2Fcheckstyle%2Fchecks%2Fannotation+filename%3Amessages*.properties+repo%3Acheckstyle%2Fcheckstyle+%22annotation.package.location%22">
            annotation.package.location</a>
          </li>
        </ul>
        <p>
          All messages can be customized if the default message doesn't suit you.
          Please <a href="config.html#Custom_messages">see the documentation</a> to learn how to.
        </p>
      </subsection>

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

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

    <section name="SuppressWarnings">
      <p>Since Checkstyle 5.0</p>
      <subsection name="Description" id="SuppressWarnings_Description">
        <p>Allows to specify what warnings that<code>@SuppressWarnings</code>
          is not allowed to suppress.
        You can also specify a list of TokenTypes that
        the configured warning(s) cannot be suppressed on.
        </p>
        <p>
        Limitations:  This check does not consider conditionals
        inside the @SuppressWarnings annotation.
        </p>
        <p>
        For example:
        <code>@SuppressWarnings((false) ? (true) ? "unchecked" : "foo" : "unused")</code>.
        According to the above example, the "unused" warning is being suppressed
        not the "unchecked" or "foo" warnings.  All of these warnings will be
        considered and matched against regardless of what the conditional
        evaluates to.
        The check also does not support code like <code>@SuppressWarnings("un" + "used")</code>,
        <code>@SuppressWarnings((String) "unused")</code> or
        <code>@SuppressWarnings({('u' + (char)'n') + (""+("used" + (String)"")),})</code>.
        </p>
        <p>
          By default, any warning specified will be disallowed on
          all legal TokenTypes unless otherwise specified via
          the tokens property.
        </p>
        <p>
          Also, by default warnings that are empty strings or all
          whitespace (regex: ^$|^\s+$) are flagged.  By specifying,
          the format property these defaults no longer apply.
        </p>
        <p>
          This check can be configured so that the "unchecked"
          and "unused" warnings cannot be suppressed on
          anything but variable and parameter declarations.
          See below of an example.
        </p>
      </subsection>
      <subsection name="Properties" id="SuppressWarnings_Properties">
        <div class="wrapper">
          <table>
            <tr>
              <th>name</th>
              <th>description</th>
              <th>type</th>
              <th>default value</th>
              <th>since</th>
            </tr>
            <tr>
              <td>format</td>
              <td>
                 Specify the RegExp to match against warnings. Any warning
                 being suppressed matching this pattern will be flagged.
              </td>
              <td>
                <a href="property_types.html#regexp">Regular Expression</a>
              </td>
              <td>
                <code>"^\s*+$"</code>
              </td>
              <td>5.0</td>
            </tr>

            <tr>
              <td>tokens</td>
              <td>tokens to check</td>

              <td>
                subset of tokens
                <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#INTERFACE_DEF">
                    INTERFACE_DEF</a>,
                <a href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#ENUM_DEF">
                    ENUM_DEF</a>,
                <a href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#ANNOTATION_DEF">
                    ANNOTATION_DEF</a>,
                <a href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#ANNOTATION_FIELD_DEF">
                    ANNOTATION_FIELD_DEF</a>,
                <a href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#ENUM_CONSTANT_DEF">
                    ENUM_CONSTANT_DEF</a>,
                <a href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#PARAMETER_DEF">
                    PARAMETER_DEF</a>,
                <a href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#VARIABLE_DEF">
                    VARIABLE_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>.
              </td>

              <td>
                <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#INTERFACE_DEF">
                    INTERFACE_DEF</a>,
                <a href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#ENUM_DEF">
                    ENUM_DEF</a>,
                <a href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#ANNOTATION_DEF">
                    ANNOTATION_DEF</a>,
                <a href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#ANNOTATION_FIELD_DEF">
                    ANNOTATION_FIELD_DEF</a>,
                <a href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#ENUM_CONSTANT_DEF">
                    ENUM_CONSTANT_DEF</a>,
                <a href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#PARAMETER_DEF">
                    PARAMETER_DEF</a>,
                <a href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#VARIABLE_DEF">
                    VARIABLE_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>.
              </td>
              <td>5.0</td>
            </tr>

          </table>
        </div>
      </subsection>
      <subsection name="Examples" id="SuppressWarnings_Examples">
        <p> To configure the check:</p>
        <source> &lt;module name=&quot;SuppressWarnings&quot;/&gt;
        </source>

        <p>
          To configure the check so that the "unchecked" and "unused"
          warnings cannot be suppressed on anything
          but variable and parameter declarations.
        </p>
        <source>
&lt;module name=&quot;SuppressWarnings&quot;&gt;
  &lt;property name=&quot;format&quot;
      value=&quot;^unchecked$|^unused$&quot;/&gt;
  &lt;property name=&quot;tokens&quot;
    value=&quot;
    CLASS_DEF,INTERFACE_DEF,ENUM_DEF,
    ANNOTATION_DEF,ANNOTATION_FIELD_DEF,
    ENUM_CONSTANT_DEF,METHOD_DEF,CTOR_DEF
    &quot;/&gt;
&lt;/module&gt;
        </source>
      </subsection>

      <subsection name="Example of Usage" id="SuppressWarnings_Example_of_Usage">
        <ul>
          <li>
            <a href="https://github.com/search?q=path%3Aconfig+filename%3Acheckstyle_checks.xml+repo%3Acheckstyle%2Fcheckstyle+SuppressWarnings">
            Checkstyle Style</a>
          </li>
        </ul>
      </subsection>

      <subsection name="Violation Messages" id="SuppressWarnings_Violation_Messages">
        <ul>
          <li>
            <a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fresources%2Fcom%2Fpuppycrawl%2Ftools%2Fcheckstyle%2Fchecks%2Fannotation+filename%3Amessages*.properties+repo%3Acheckstyle%2Fcheckstyle+%22suppressed.warning.not.allowed%22">
            suppressed.warning.not.allowed</a>
          </li>
        </ul>
        <p>
          All messages can be customized if the default message doesn't suit you.
          Please <a href="config.html#Custom_messages">see the documentation</a> to learn how to.
        </p>
      </subsection>

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

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

    <section name="SuppressWarningsHolder">
      <p>Since Checkstyle 5.7</p>
      <subsection name="Description" id="SuppressWarningsHolder_Description">
        <p>
          Maintains a set of check suppressions from
          <code>@SuppressWarnings</code> annotations. It allows to
          prevent Checkstyle from reporting violations from parts of code
          that were annotated with <code>@SuppressWarnings</code> and
          using name of the check to be excluded. You can also define
          aliases for check names that need to be suppressed.
         </p>
      </subsection>

      <subsection name="Properties" id="SuppressWarningsHolder_Properties">
        <div class="wrapper">
          <table>
            <tr>
              <th>name</th>
              <th>description</th>
              <th>type</th>
              <th>default value</th>
              <th>since</th>
            </tr>
            <tr>
              <td>aliasList</td>
              <td>Specify aliases for check names that can be used in code within
                  <code>SuppressWarnings</code>.</td>
              <td><a href="property_types.html#stringSet">String Set</a>
                  in a format of comma separated attribute=value entries.
              The attribute is the fully qualified name of the Check and value is its alias.</td>
              <td><code>null</code></td>
              <td>5.7</td>
            </tr>
          </table>
        </div>
      </subsection>

      <subsection name="Examples" id="SuppressWarningsHolder_Examples">
        <p>To prevent <code>FooCheck</code> violations from being reported write:</p>
        <source>
@SuppressWarnings("foo") interface I { }
@SuppressWarnings("foo") enum E { }
@SuppressWarnings("foo") InputSuppressWarningsFilter() { }
        </source>
        <p>Some real check examples:</p>
        <p>This will prevent from invocation of the MemberNameCheck:</p>
        <source>
@SuppressWarnings({"membername"})
private int J;
        </source>
        <p>You can also use a <code>checkstyle</code> prefix to prevent compiler from
           processing this annotations.
           For example this will prevent ConstantNameCheck:
        </p>
        <source>
@SuppressWarnings("checkstyle:constantname")
private static final int m = 0;
        </source>

        <p>The general rule is that the argument of the <code>@SuppressWarnings</code> will be
          matched against class name of the checker in lower case and without <code>Check</code>
          suffix if present.
        </p>
        <p>If <code>aliasList</code> property was provided you can use your own names e.g below
             code will work if there was provided a <code>ParameterNumberCheck=paramnum</code> in
             the <code>aliasList</code>:
        </p>
        <source>
@SuppressWarnings("paramnum")
public void needsLotsOfParameters(@SuppressWarnings("unused") int a,
  int b, int c, int d, int e, int f, int g, int h) {
  ...
}
        </source>

        <p>It is possible to suppress all the checkstyle warnings with the argument
         <code>"all"</code>:
        </p>
        <source>
@SuppressWarnings("all")
public void someFunctionWithInvalidStyle() {
  //...
}
        </source>

      </subsection>

      <subsection name="Example of Usage" id="SuppressWarningsHolder_Example_of_Usage">
        <ul>
          <li>
            <a href="https://github.com/search?q=path%3Aconfig+filename%3Acheckstyle_checks.xml+repo%3Acheckstyle%2Fcheckstyle+SuppressWarningsHolder">
            Checkstyle Style</a>
          </li>
        </ul>
      </subsection>

      <subsection name="Violation Messages" id="SuppressWarningsHolder_Violation_Messages">
        <ul>
          <li>
            <a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fresources%2Fcom%2Fpuppycrawl%2Ftools%2Fcheckstyle%2Fchecks+filename%3Amessages*.properties+repo%3Acheckstyle%2Fcheckstyle+%22suppress.warnings.invalid.target%22">
            suppress.warnings.invalid.target</a>
          </li>
        </ul>
        <p>
          All messages can be customized if the default message doesn't suit you.
          Please <a href="config.html#Custom_messages">see the documentation</a> to learn how to.
        </p>
      </subsection>

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

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

    </section>
  </body>
</document>
