| <?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>Javadoc Comments</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="AtclauseOrder"> |
| <subsection name="Description"> |
| <p>Since Checkstyle 6.0</p> |
| <p> |
| Checks the order of <a href="https://docs.oracle.com/javase/8/docs/technotes/tools/windows/javadoc.html#CHDBEFIF">javadoc block-tags or javadoc tags</a>. |
| <br/> |
| Note: Google used term "at-clauses" for block tags in his guide till 2017-02-28. |
| </p> |
| </subsection> |
| |
| <subsection name="Properties"> |
| <table> |
| <tr> |
| <th>name</th> |
| <th>description</th> |
| <th>type</th> |
| <th>default value</th> |
| <th>since</th> |
| </tr> |
| <tr> |
| <td>violateExecutionOnNonTightHtml</td> |
| <td> |
| If turned on, will 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.3</td> |
| </tr> |
| <tr> |
| <td>target</td> |
| <td>allows to specify targets to check at-clauses.</td> |
| <td>subset of tokens |
| <a href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html">TokenTypes</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>6.0</td> |
| </tr> |
| <tr> |
| <td>tagOrder</td> |
| <td>allows to specify the order by tags.</td> |
| <td><a href="property_types.html#stringSet">String Set</a></td> |
| <td><code>@author, @version, @param, |
| @return, @throws, @exception, @see, @since, @serial, |
| @serialField, @serialData, @deprecated</code></td> |
| <td>6.0</td> |
| </tr> |
| </table> |
| </subsection> |
| |
| <subsection name="Examples"> |
| <p> |
| Default configuration |
| </p> |
| <source> |
| <module name="AtclauseOrder"> |
| <property name="tagOrder" value="@author, @version, @param, |
| @return, @throws, @exception, @see, @since, @serial, |
| @serialField, @serialData, @deprecated"/> |
| <property name="target" value="CLASS_DEF, INTERFACE_DEF, ENUM_DEF, |
| METHOD_DEF, CTOR_DEF, VARIABLE_DEF"/> |
| </module> |
| </source> |
| </subsection> |
| |
| <subsection name="Example of Usage"> |
| <ul> |
| <li> |
| <a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fresources+filename%3Agoogle_checks.xml+repo%3Acheckstyle%2Fcheckstyle+AtclauseOrder"> |
| Google Style</a> |
| </li> |
| <li> |
| <a href="https://github.com/search?q=path%3Aconfig+filename%3Acheckstyle_checks.xml+repo%3Acheckstyle%2Fcheckstyle+AtclauseOrder"> |
| Checkstyle Style</a> |
| </li> |
| </ul> |
| </subsection> |
| |
| <subsection name="Error Messages"> |
| <ul> |
| <li> |
| <a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fresources%2Fcom%2Fpuppycrawl%2Ftools%2Fcheckstyle%2Fchecks%2Fjavadoc+filename%3Amessages*.properties+repo%3Acheckstyle%2Fcheckstyle+%22at.clause.order%22"> |
| at.clause.order</a> |
| </li> |
| <li> |
| <a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fresources%2Fcom%2Fpuppycrawl%2Ftools%2Fcheckstyle%2Fchecks%2Fjavadoc+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%2Fjavadoc+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%2Fjavadoc+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"> |
| <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>Since Checkstyle 3.0</p> |
| <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> |
| <th>since</th> |
| </tr> |
| <tr> |
| <td>minLineCount</td> |
| <td>Minimal amount of lines in method to allow no documentation.</td> |
| <td><a href="property_types.html#integer">Integer</a></td> |
| <td><code>-1</code></td> |
| <td>6.0</td> |
| </tr> |
| <tr> |
| <td>allowedAnnotations</td> |
| <td>List of annotations that could allow missed documentation.</td> |
| <td><a href="property_types.html#stringSet">String Set</a></td> |
| <td><code>Override</code></td> |
| <td>6.0</td> |
| </tr> |
| <tr> |
| <td>validateThrows</td> |
| <td>Allows validating throws tags.</td> |
| <td><a href="property_types.html#boolean">Boolean</a></td> |
| <td><code>false</code></td> |
| <td>6.0</td> |
| </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> |
| <td>3.0</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> |
| <td>3.4</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> |
| <td>3.0</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> |
| <td>3.1</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> |
| <td>3.1</td> |
| </tr> |
| <tr> |
| <td>allowMissingThrowsTags</td> |
| <td>whether to ignore errors when a method declares |
| that it throws exceptions but does not have matching throws tags |
| in the javadoc.</td> |
| <td><a href="property_types.html#boolean">Boolean</a></td> |
| <td><code>false</code></td> |
| <td>3.1</td> |
| </tr> |
| <tr> |
| <td>allowMissingReturnTag</td> |
| <td>whether to ignore errors when a method returns |
| non-void type and does not have a return tag in the javadoc.</td> |
| <td><a href="property_types.html#boolean">Boolean</a></td> |
| <td><code>false</code></td> |
| <td>3.1</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> |
| <td>4.0</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> |
| <td>4.0</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> |
| <td>4.2</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> |
| <td>4.2</td> |
| </tr> |
| <tr> |
| <td>ignoreMethodNamesRegex</td> |
| <td>ignore method whose names are matching specified regex</td> |
| <td><a href="property_types.html#regexp">Regular Expression</a></td> |
| <td><code>null</code></td> |
| <td>6.3</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#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#ANNOTATION_FIELD_DEF">ANNOTATION_FIELD_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>, |
| <a href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#ANNOTATION_FIELD_DEF">ANNOTATION_FIELD_DEF</a>. |
| </td> |
| <td>3.0</td> |
| </tr> |
| </table> |
| </subsection> |
| |
| <subsection name="Examples"> |
| <p> |
| To configure the default check: |
| </p> |
| <source> |
| <module name="JavadocMethod"/> |
| </source> |
| |
| <p> |
| To configure the check for <code>public</code> |
| scope and to allow documentation of undeclared |
| RuntimeExceptions: |
| </p> |
| <source> |
| <module name="JavadocMethod"> |
| <property name="scope" value="public"/> |
| <property name="allowUndeclaredRTE" value="true"/> |
| </module> |
| </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> |
| <module name="JavadocMethod"> |
| <property name="scope" value="public"/> |
| <property name="allowUndeclaredRTE" value="true"/> |
| <property name="allowMissingParamTags" value="true"/> |
| </module> |
| </source> |
| |
| <p> |
| To configure the check for methods which are in <code>private</code> , but not in <code>protected</code> scope: |
| </p> |
| <source> |
| <module name="JavadocMethod"> |
| <property name="scope" value="private"/> |
| <property name="excludeScope" value="protected"/> |
| </module> |
| </source> |
| <p> |
| To configure the check for ignoring methods named <code>foo(),foo1(),foo2()</code>, etc.: |
| </p> |
| <source> |
| <module name="JavadocMethod"> |
| <property name="ignoreMethodNamesRegex" value="^foo.*$"/> |
| </module> |
| </source> |
| </subsection> |
| |
| <subsection name="Example of Usage"> |
| <ul> |
| <li> |
| <a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fresources+filename%3Agoogle_checks.xml+repo%3Acheckstyle%2Fcheckstyle+JavadocMethod"> |
| Google Style</a> |
| </li> |
| <li> |
| <a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fresources+filename%3Asun_checks.xml+repo%3Acheckstyle%2Fcheckstyle+JavadocMethod"> |
| Sun Style</a> |
| </li> |
| <li> |
| <a href="https://github.com/search?q=path%3Aconfig+filename%3Acheckstyle_checks.xml+repo%3Acheckstyle%2Fcheckstyle+JavadocMethod"> |
| Checkstyle Style</a> |
| </li> |
| </ul> |
| </subsection> |
| |
| <subsection name="Error Messages"> |
| <ul> |
| <li> |
| <a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fresources%2Fcom%2Fpuppycrawl%2Ftools%2Fcheckstyle%2Fchecks%2Fjavadoc+filename%3Amessages*.properties+repo%3Acheckstyle%2Fcheckstyle+%22javadoc.classInfo%22"> |
| javadoc.classInfo</a> |
| </li> |
| <li> |
| <a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fresources%2Fcom%2Fpuppycrawl%2Ftools%2Fcheckstyle%2Fchecks%2Fjavadoc+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%2Fjavadoc+filename%3Amessages*.properties+repo%3Acheckstyle%2Fcheckstyle+%22javadoc.expectedTag%22"> |
| javadoc.expectedTag</a> |
| </li> |
| <li> |
| <a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fresources%2Fcom%2Fpuppycrawl%2Ftools%2Fcheckstyle%2Fchecks%2Fjavadoc+filename%3Amessages*.properties+repo%3Acheckstyle%2Fcheckstyle+%22javadoc.invalidInheritDoc%22"> |
| javadoc.invalidInheritDoc</a> |
| </li> |
| <li> |
| <a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fresources%2Fcom%2Fpuppycrawl%2Ftools%2Fcheckstyle%2Fchecks%2Fjavadoc+filename%3Amessages*.properties+repo%3Acheckstyle%2Fcheckstyle+%22javadoc.missing%22"> |
| javadoc.missing</a> |
| </li> |
| <li> |
| <a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fresources%2Fcom%2Fpuppycrawl%2Ftools%2Fcheckstyle%2Fchecks%2Fjavadoc+filename%3Amessages*.properties+repo%3Acheckstyle%2Fcheckstyle+%22javadoc.return.expected%22"> |
| javadoc.return.expected</a> |
| </li> |
| <li> |
| <a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fresources%2Fcom%2Fpuppycrawl%2Ftools%2Fcheckstyle%2Fchecks%2Fjavadoc+filename%3Amessages*.properties+repo%3Acheckstyle%2Fcheckstyle+%22javadoc.unusedTag%22"> |
| javadoc.unusedTag</a> |
| </li> |
| <li> |
| <a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fresources%2Fcom%2Fpuppycrawl%2Ftools%2Fcheckstyle%2Fchecks%2Fjavadoc+filename%3Amessages*.properties+repo%3Acheckstyle%2Fcheckstyle+%22javadoc.unusedTagGeneral%22"> |
| javadoc.unusedTagGeneral</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"> |
| <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="JavadocPackage"> |
| <subsection name="Description"> |
| <p>Since Checkstyle 5.0</p> |
| <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> |
| <th>since</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> |
| <td>5.0</td> |
| </tr> |
| <tr> |
| <td>fileExtensions</td> |
| <td>file type extension of files to process</td> |
| <td><a href="property_types.html#stringSet">String Set</a></td> |
| <td><code>{}</code></td> |
| <td>5.0</td> |
| </tr> |
| </table> |
| </subsection> |
| |
| <subsection name="Examples"> |
| <p> |
| To configure the check: |
| </p> |
| <source> |
| <module name="JavadocPackage"/> |
| </source> |
| </subsection> |
| |
| <subsection name="Example of Usage"> |
| <ul> |
| <li> |
| <a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fresources+filename%3Asun_checks.xml+repo%3Acheckstyle%2Fcheckstyle+JavadocPackage"> |
| Sun Style</a> |
| </li> |
| <li> |
| <a href="https://github.com/search?q=path%3Aconfig+filename%3Acheckstyle_checks.xml+repo%3Acheckstyle%2Fcheckstyle+JavadocPackage"> |
| Checkstyle Style</a> |
| </li> |
| </ul> |
| </subsection> |
| |
| <subsection name="Error Messages"> |
| <ul> |
| <li> |
| <a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fresources%2Fcom%2Fpuppycrawl%2Ftools%2Fcheckstyle%2Fchecks%2Fjavadoc+filename%3Amessages*.properties+repo%3Acheckstyle%2Fcheckstyle+%22javadoc.legacyPackageHtml%22"> |
| javadoc.legacyPackageHtml</a> |
| </li> |
| <li> |
| <a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fresources%2Fcom%2Fpuppycrawl%2Ftools%2Fcheckstyle%2Fchecks%2Fjavadoc+filename%3Amessages*.properties+repo%3Acheckstyle%2Fcheckstyle+%22javadoc.packageInfo%22"> |
| javadoc.packageInfo</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"> |
| <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="JavadocParagraph"> |
| <subsection name="Description"> |
| <p>Since Checkstyle 6.0</p> |
| <p> |
| Checks that: |
| </p> |
| <ul> |
| <li> |
| There is one blank line between each of two paragraphs and one blank line before the at-clauses block if it is present. |
| </li> |
| <li> |
| Each paragraph but the first has <p> immediately before the first word, with no space after. |
| </li> |
| </ul> |
| </subsection> |
| |
| <subsection name="Properties"> |
| <table> |
| <tr> |
| <th>name</th> |
| <th>description</th> |
| <th>type</th> |
| <th>default value</th> |
| <th>since</th> |
| </tr> |
| <tr> |
| <td>violateExecutionOnNonTightHtml</td> |
| <td> |
| If turned on, will 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.3</td> |
| </tr> |
| <tr> |
| <td>allowNewlineParagraph</td> |
| <td>whether the <p> tag should be placed immediately before the first word</td> |
| <td><a href="property_types.html#boolean">Boolean</a></td> |
| <td><code>true</code></td> |
| <td>6.9</td> |
| </tr> |
| </table> |
| </subsection> |
| |
| <subsection name="Examples"> |
| <p> |
| Default configuration: |
| </p> |
| <source> |
| <module name="JavadocParagraph"/> |
| </source> |
| <p> |
| To allows to place text of a paragraph not immediately after a <p> tag: |
| </p> |
| <source> |
| <module name="JavadocParagraph"> |
| <property name="allowNewlineParagraph" value="true"/> |
| </module> |
| </source> |
| <p> |
| In case of tagImmediatelyBeforeFirstWord set to false |
| the following example will not have any violations: |
| </p> |
| <source> |
| /** |
| * Some Javadoc. |
| * |
| * <p> |
| * Some Javadoc. |
| * |
| * <p> Some Javadoc. |
| * |
| * <p> |
| * <pre> |
| * Some preformatted Javadoc. |
| * </pre> |
| * |
| */ |
| </source> |
| </subsection> |
| |
| <subsection name="Example of Usage"> |
| <ul> |
| <li> |
| <a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fresources+filename%3Agoogle_checks.xml+repo%3Acheckstyle%2Fcheckstyle+JavadocParagraph"> |
| Google Style</a> |
| </li> |
| <li> |
| <a href="https://github.com/search?q=path%3Aconfig+filename%3Acheckstyle_checks.xml+repo%3Acheckstyle%2Fcheckstyle+JavadocParagraph"> |
| Checkstyle Style</a> |
| </li> |
| </ul> |
| </subsection> |
| |
| <subsection name="Error Messages"> |
| <ul> |
| <li> |
| <a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fresources%2Fcom%2Fpuppycrawl%2Ftools%2Fcheckstyle%2Fchecks%2Fjavadoc+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%2Fjavadoc+filename%3Amessages*.properties+repo%3Acheckstyle%2Fcheckstyle+%22javadoc.paragraph.line.before%22"> |
| javadoc.paragraph.line.before</a> |
| </li> |
| <li> |
| <a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fresources%2Fcom%2Fpuppycrawl%2Ftools%2Fcheckstyle%2Fchecks%2Fjavadoc+filename%3Amessages*.properties+repo%3Acheckstyle%2Fcheckstyle+%22javadoc.paragraph.misplaced.tag%22"> |
| javadoc.paragraph.misplaced.tag</a> |
| </li> |
| <li> |
| <a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fresources%2Fcom%2Fpuppycrawl%2Ftools%2Fcheckstyle%2Fchecks%2Fjavadoc+filename%3Amessages*.properties+repo%3Acheckstyle%2Fcheckstyle+%22javadoc.paragraph.redundant.paragraph%22"> |
| javadoc.paragraph.redundant.paragraph</a> |
| </li> |
| <li> |
| <a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fresources%2Fcom%2Fpuppycrawl%2Ftools%2Fcheckstyle%2Fchecks%2Fjavadoc+filename%3Amessages*.properties+repo%3Acheckstyle%2Fcheckstyle+%22javadoc.paragraph.tag.after%22"> |
| javadoc.paragraph.tag.after</a> |
| </li> |
| <li> |
| <a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fresources%2Fcom%2Fpuppycrawl%2Ftools%2Fcheckstyle%2Fchecks%2Fjavadoc+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%2Fjavadoc+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"> |
| <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>Since Checkstyle 3.2</p> |
| <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. Without 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", "dd", "del", "div", "dfn", "dl", "dt", "em", |
| "fieldset", "font", "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", "u", "ul". |
| </li> |
| </ul> |
| |
| <p> |
| These checks were patterned after the checks made by the <a |
| href="http://maven-doccheck.sourceforge.net/">DocCheck</a> |
| doclet available from Sun. Note: Original Sun's DocCheck tool does not exist anymore. |
| </p> |
| </subsection> |
| |
| <subsection name="Properties"> |
| <table> |
| <tr> |
| <th>name</th> |
| <th>description</th> |
| <th>type</th> |
| <th>default value</th> |
| <th>since</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> |
| <td>3.2</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> |
| <td>3.4</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> |
| <td>3.2</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<])|([.?!]$)"</code></td> |
| <td>5.0</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> |
| <td>3.4</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> |
| <td>3.2</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#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#CLASS_DEF">CLASS_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#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#INTERFACE_DEF">INTERFACE_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#PACKAGE_DEF">PACKAGE_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#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#CLASS_DEF">CLASS_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#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#INTERFACE_DEF">INTERFACE_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#PACKAGE_DEF">PACKAGE_DEF</a>, |
| <a href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#VARIABLE_DEF">VARIABLE_DEF</a>. |
| </td> |
| <td>3.2</td> |
| </tr> |
| </table> |
| </subsection> |
| |
| <subsection name="Examples"> |
| <p> |
| To configure the default check: |
| </p> |
| |
| <source> |
| <module name="JavadocStyle"/> |
| </source> |
| |
| <p> |
| To configure the check for <code>public</code> |
| scope: |
| </p> |
| |
| <source> |
| <module name="JavadocStyle"> |
| <property name="scope" value="public"/> |
| </module> |
| </source> |
| |
| <p> |
| To configure the check for javadoc which is in <code>private</code>, but not in <code>package</code> scope: |
| </p> |
| |
| <source> |
| <module name="JavadocStyle"> |
| <property name="scope" value="private"/> |
| <property name="excludeScope" value="package"/> |
| </module> |
| </source> |
| |
| <p> |
| To configure the check to turn off first sentence checking: |
| </p> |
| |
| <source> |
| <module name="JavadocStyle"> |
| <property name="checkFirstSentence" value="false"/> |
| </module> |
| </source> |
| </subsection> |
| |
| <subsection name="Example of Usage"> |
| <ul> |
| <li> |
| <a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fresources+filename%3Asun_checks.xml+repo%3Acheckstyle%2Fcheckstyle+JavadocStyle"> |
| Sun Style</a> |
| </li> |
| <li> |
| <a href="https://github.com/search?q=path%3Aconfig+filename%3Acheckstyle_checks.xml+repo%3Acheckstyle%2Fcheckstyle+JavadocStyle"> |
| Checkstyle Style</a> |
| </li> |
| </ul> |
| </subsection> |
| |
| <subsection name="Error Messages"> |
| <ul> |
| <li> |
| <a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fresources%2Fcom%2Fpuppycrawl%2Ftools%2Fcheckstyle%2Fchecks%2Fjavadoc+filename%3Amessages*.properties+repo%3Acheckstyle%2Fcheckstyle+%22javadoc.empty%22"> |
| javadoc.empty</a> |
| </li> |
| <li> |
| <a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fresources%2Fcom%2Fpuppycrawl%2Ftools%2Fcheckstyle%2Fchecks%2Fjavadoc+filename%3Amessages*.properties+repo%3Acheckstyle%2Fcheckstyle+%22javadoc.extraHtml%22"> |
| javadoc.extraHtml</a> |
| </li> |
| <li> |
| <a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fresources%2Fcom%2Fpuppycrawl%2Ftools%2Fcheckstyle%2Fchecks%2Fjavadoc+filename%3Amessages*.properties+repo%3Acheckstyle%2Fcheckstyle+%22javadoc.incompleteTag%22"> |
| javadoc.incompleteTag</a> |
| </li> |
| <li> |
| <a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fresources%2Fcom%2Fpuppycrawl%2Ftools%2Fcheckstyle%2Fchecks%2Fjavadoc+filename%3Amessages*.properties+repo%3Acheckstyle%2Fcheckstyle+%22javadoc.missing%22"> |
| javadoc.missing</a> |
| </li> |
| <li> |
| <a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fresources%2Fcom%2Fpuppycrawl%2Ftools%2Fcheckstyle%2Fchecks%2Fjavadoc+filename%3Amessages*.properties+repo%3Acheckstyle%2Fcheckstyle+%22javadoc.noPeriod%22"> |
| javadoc.noPeriod</a> |
| </li> |
| <li> |
| <a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fresources%2Fcom%2Fpuppycrawl%2Ftools%2Fcheckstyle%2Fchecks%2Fjavadoc+filename%3Amessages*.properties+repo%3Acheckstyle%2Fcheckstyle+%22javadoc.unclosedHtml%22"> |
| javadoc.unclosedHtml</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"> |
| <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="JavadocTagContinuationIndentation"> |
| <subsection name="Description"> |
| <p>Since Checkstyle 6.0</p> |
| <p> |
| Checks the indentation of the continuation lines in at-clauses. |
| </p> |
| </subsection> |
| |
| <subsection name="Properties"> |
| <table> |
| <tr> |
| <th>name</th> |
| <th>description</th> |
| <th>type</th> |
| <th>default value</th> |
| <th>since</th> |
| </tr> |
| <tr> |
| <td>violateExecutionOnNonTightHtml</td> |
| <td> |
| If turned on, will 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.3</td> |
| </tr> |
| <tr> |
| <td>offset</td> |
| <td>How many spaces to use for new indentation level.</td> |
| <td><a href="property_types.html#integer">Integer</a></td> |
| <td><span class="default">4</span></td> |
| <td>6.0</td> |
| </tr> |
| </table> |
| </subsection> |
| |
| <subsection name="Examples"> |
| <p> |
| Default configuration |
| </p> |
| <source> |
| <module name="JavadocTagContinuationIndentation"> |
| <property name="offset" value="4"/> |
| </module> |
| </source> |
| </subsection> |
| |
| <subsection name="Example of Usage"> |
| <ul> |
| <li> |
| <a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fresources+filename%3Agoogle_checks.xml+repo%3Acheckstyle%2Fcheckstyle+JavadocTagContinuationIndentation"> |
| Google Style</a> |
| </li> |
| <li> |
| <a href="https://github.com/search?q=path%3Aconfig+filename%3Acheckstyle_checks.xml+repo%3Acheckstyle%2Fcheckstyle+JavadocTagContinuationIndentation"> |
| Checkstyle Style</a> |
| </li> |
| </ul> |
| </subsection> |
| |
| <subsection name="Error Messages"> |
| <ul> |
| <li> |
| <a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fresources%2Fcom%2Fpuppycrawl%2Ftools%2Fcheckstyle%2Fchecks%2Fjavadoc+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%2Fjavadoc+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%2Fjavadoc+filename%3Amessages*.properties+repo%3Acheckstyle%2Fcheckstyle+%22javadoc.wrong.singleton.html.tag%22"> |
| javadoc.wrong.singleton.html.tag</a> |
| </li> |
| <li> |
| <a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fresources%2Fcom%2Fpuppycrawl%2Ftools%2Fcheckstyle%2Fchecks%2Fjavadoc+filename%3Amessages*.properties+repo%3Acheckstyle%2Fcheckstyle+%22tag.continuation.indent%22"> |
| tag.continuation.indent</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"> |
| <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="JavadocType"> |
| <subsection name="Description"> |
| <p>Since Checkstyle 3.0</p> |
| <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="https://docs.oracle.com/javase/7/docs/api/java/util/regex/Pattern.html"> |
| regular expression</a>. |
| </p> |
| <p> |
| Does not perform checks for author and version tags for inner |
| classes, as they should be redundant because of outer class. |
| </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> |
| <th>since</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> |
| <td>3.0</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> |
| <td>3.4</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></td> |
| <td>3.0</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></td> |
| <td>3.0</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> |
| <td>4.0</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> |
| <td>5.1</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#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#ENUM_DEF">ENUM_DEF</a>, |
| <a href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#ANNOTATION_DEF">ANNOTATION_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#ENUM_DEF">ENUM_DEF</a>, |
| <a href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#ANNOTATION_DEF">ANNOTATION_DEF</a>. |
| </td> |
| <td>3.0</td> |
| </tr> |
| </table> |
| </subsection> |
| |
| <subsection name="Examples"> |
| <p> |
| To configure the default check: |
| </p> |
| <source> |
| <module name="JavadocType"/> |
| </source> |
| |
| <p> |
| To configure the check for <code>public</code> scope: |
| </p> |
| <source> |
| <module name="JavadocType"> |
| <property name="scope" value="public"/> |
| </module> |
| </source> |
| |
| <p> |
| To configure the check for an @author tag: |
| </p> |
| <source> |
| <module name="JavadocType"> |
| <property name="authorFormat" value="\S"/> |
| </module> |
| </source> |
| |
| <p> |
| To configure the check for a CVS revision version tag: |
| </p> |
| <source> |
| <module name="JavadocType"> |
| <property name="versionFormat" value="\$Revision.*\$"/> |
| </module> |
| </source> |
| |
| <p> |
| To configure the check for <code>private</code> classes only: |
| </p> |
| <source> |
| <module name="JavadocType"> |
| <property name="scope" value="private"/> |
| <property name="excludeScope" value="package"/> |
| </module> |
| </source> |
| </subsection> |
| |
| <subsection name="Example of Usage"> |
| <ul> |
| <li> |
| <a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fresources+filename%3Asun_checks.xml+repo%3Acheckstyle%2Fcheckstyle+JavadocType"> |
| Sun Style</a> |
| </li> |
| <li> |
| <a href="https://github.com/search?q=path%3Aconfig+filename%3Acheckstyle_checks.xml+repo%3Acheckstyle%2Fcheckstyle+JavadocType"> |
| Checkstyle Style</a> |
| </li> |
| </ul> |
| </subsection> |
| |
| <subsection name="Error Messages"> |
| <ul> |
| <li> |
| <a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fresources%2Fcom%2Fpuppycrawl%2Ftools%2Fcheckstyle%2Fchecks%2Fjavadoc+filename%3Amessages*.properties+repo%3Acheckstyle%2Fcheckstyle+%22javadoc.missing%22"> |
| javadoc.missing</a> |
| </li> |
| <li> |
| <a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fresources%2Fcom%2Fpuppycrawl%2Ftools%2Fcheckstyle%2Fchecks%2Fjavadoc+filename%3Amessages*.properties+repo%3Acheckstyle%2Fcheckstyle+%22javadoc.unknownTag%22"> |
| javadoc.unknownTag</a> |
| </li> |
| <li> |
| <a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fresources%2Fcom%2Fpuppycrawl%2Ftools%2Fcheckstyle%2Fchecks%2Fjavadoc+filename%3Amessages*.properties+repo%3Acheckstyle%2Fcheckstyle+%22javadoc.unusedTag%22"> |
| javadoc.unusedTag</a> |
| </li> |
| <li> |
| <a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fresources%2Fcom%2Fpuppycrawl%2Ftools%2Fcheckstyle%2Fchecks%2Fjavadoc+filename%3Amessages*.properties+repo%3Acheckstyle%2Fcheckstyle+%22javadoc.unusedTagGeneral%22"> |
| javadoc.unusedTagGeneral</a> |
| </li> |
| <li> |
| <a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fresources%2Fcom%2Fpuppycrawl%2Ftools%2Fcheckstyle%2Fchecks%2Fjavadoc+filename%3Amessages*.properties+repo%3Acheckstyle%2Fcheckstyle+%22type.missingTag%22"> |
| type.missingTag</a> |
| </li> |
| <li> |
| <a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fresources%2Fcom%2Fpuppycrawl%2Ftools%2Fcheckstyle%2Fchecks%2Fjavadoc+filename%3Amessages*.properties+repo%3Acheckstyle%2Fcheckstyle+%22type.tagFormat%22"> |
| type.tagFormat</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"> |
| <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>Since Checkstyle 3.0</p> |
| <p> |
| Checks that variables have Javadoc comments. Ignores <code>serialVersionUID</code> |
| fields. |
| </p> |
| </subsection> |
| |
| <subsection name="Properties"> |
| <table> |
| <tr> |
| <th>name</th> |
| <th>description</th> |
| <th>type</th> |
| <th>default value</th> |
| <th>since</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> |
| <td>3.0</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> |
| <td>3.4</td> |
| </tr> |
| <tr> |
| <td>ignoreNamePattern</td> |
| <td>regexp to define variable names to ignore</td> |
| <td><a href="property_types.html#regexp">Regular Expression</a></td> |
| <td><code>null</code></td> |
| <td>5.8</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#ENUM_CONSTANT_DEF">ENUM_CONSTANT_DEF</a>. |
| </td> |
| <td> |
| <a href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#ENUM_CONSTANT_DEF">ENUM_CONSTANT_DEF</a>. |
| </td> |
| <td>3.0</td> |
| </tr> |
| </table> |
| </subsection> |
| |
| <subsection name="Examples"> |
| <p> |
| To configure the default check: |
| </p> |
| <source> |
| <module name="JavadocVariable"/> |
| </source> |
| |
| <p> |
| To configure the check for <code>public</code> |
| scope: |
| </p> |
| |
| <source> |
| <module name="JavadocVariable"> |
| <property name="scope" value="public"/> |
| </module> |
| </source> |
| |
| <p> |
| To configure the check for members which are in <code>private</code>, but not in <code>protected</code> scope: |
| </p> |
| |
| <source> |
| <module name="JavadocVariable"> |
| <property name="scope" value="private"/> |
| <property name="excludeScope" value="protected"/> |
| </module> |
| </source> |
| |
| <p> |
| To ignore absence of Javadoc comments for variables with names <code>log</code> or <code>logger</code>: |
| </p> |
| |
| <source> |
| <module name="JavadocVariable"> |
| <property name="ignoreNamePattern" value="log|logger"/> |
| </module> |
| </source> |
| </subsection> |
| |
| <subsection name="Example of Usage"> |
| <ul> |
| <li> |
| <a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fresources+filename%3Asun_checks.xml+repo%3Acheckstyle%2Fcheckstyle+JavadocVariable"> |
| Sun Style</a> |
| </li> |
| <li> |
| <a href="https://github.com/search?q=path%3Aconfig+filename%3Acheckstyle_checks.xml+repo%3Acheckstyle%2Fcheckstyle+JavadocVariable"> |
| Checkstyle Style</a> |
| </li> |
| </ul> |
| </subsection> |
| |
| <subsection name="Error Messages"> |
| <ul> |
| <li> |
| <a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fresources%2Fcom%2Fpuppycrawl%2Ftools%2Fcheckstyle%2Fchecks%2Fjavadoc+filename%3Amessages*.properties+repo%3Acheckstyle%2Fcheckstyle+%22javadoc.missing%22"> |
| javadoc.missing</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"> |
| <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="NonEmptyAtclauseDescription"> |
| <subsection name="Description"> |
| <p>Since Checkstyle 6.0</p> |
| <p> |
| Checks that the at-clause tag is followed by description. |
| </p> |
| </subsection> |
| |
| <subsection name="Properties"> |
| <table> |
| <tr> |
| <th>name</th> |
| <th>description</th> |
| <th>type</th> |
| <th>default value</th> |
| <th>since</th> |
| </tr> |
| <tr> |
| <td>violateExecutionOnNonTightHtml</td> |
| <td> |
| If turned on, will 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.3</td> |
| </tr> |
| <tr> |
| <td>javadocTokens</td> |
| <td>javadoc tokens to check</td> |
| <td>subset of javadoc tokens |
| <a href="apidocs/com/puppycrawl/tools/checkstyle/api/JavadocTokenTypes.html#PARAM_LITERAL">PARAM_LITERAL</a>, |
| <a href="apidocs/com/puppycrawl/tools/checkstyle/api/JavadocTokenTypes.html#RETURN_LITERAL">RETURN_LITERAL</a>, |
| <a href="apidocs/com/puppycrawl/tools/checkstyle/api/JavadocTokenTypes.html#THROWS_LITERAL">THROWS_LITERAL</a>, |
| <a href="apidocs/com/puppycrawl/tools/checkstyle/api/JavadocTokenTypes.html#DEPRECATED_LITERAL">DEPRECATED_LITERAL</a>. |
| </td> |
| <td> |
| <a href="apidocs/com/puppycrawl/tools/checkstyle/api/JavadocTokenTypes.html#PARAM_LITERAL">PARAM_LITERAL</a>, |
| <a href="apidocs/com/puppycrawl/tools/checkstyle/api/JavadocTokenTypes.html#RETURN_LITERAL">RETURN_LITERAL</a>, |
| <a href="apidocs/com/puppycrawl/tools/checkstyle/api/JavadocTokenTypes.html#THROWS_LITERAL">THROWS_LITERAL</a>, |
| <a href="apidocs/com/puppycrawl/tools/checkstyle/api/JavadocTokenTypes.html#DEPRECATED_LITERAL">DEPRECATED_LITERAL</a>. |
| </td> |
| <td>7.3</td> |
| </tr> |
| </table> |
| </subsection> |
| |
| <subsection name="Examples"> |
| <p> |
| Default configuration that will check <code>@param</code>, <code>@return</code>, |
| <code>@throws</code>, <code>@deprecated</code>: |
| </p> |
| <source> |
| <module name="NonEmptyAtclauseDescription"/> |
| </source> |
| </subsection> |
| |
| <subsection name="Example of Usage"> |
| <ul> |
| <li> |
| <a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fresources+filename%3Agoogle_checks.xml+repo%3Acheckstyle%2Fcheckstyle+NonEmptyAtclauseDescription"> |
| Google Style</a> |
| </li> |
| <li> |
| <a href="https://github.com/search?q=path%3Aconfig+filename%3Acheckstyle_checks.xml+repo%3Acheckstyle%2Fcheckstyle+NonEmptyAtclauseDescription"> |
| Checkstyle Style</a> |
| </li> |
| </ul> |
| </subsection> |
| |
| <subsection name="Error Messages"> |
| <ul> |
| <li> |
| <a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fresources%2Fcom%2Fpuppycrawl%2Ftools%2Fcheckstyle%2Fchecks%2Fjavadoc+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%2Fjavadoc+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%2Fjavadoc+filename%3Amessages*.properties+repo%3Acheckstyle%2Fcheckstyle+%22javadoc.wrong.singleton.html.tag%22"> |
| javadoc.wrong.singleton.html.tag</a> |
| </li> |
| <li> |
| <a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fresources%2Fcom%2Fpuppycrawl%2Ftools%2Fcheckstyle%2Fchecks%2Fjavadoc+filename%3Amessages*.properties+repo%3Acheckstyle%2Fcheckstyle+%22non.empty.atclause%22"> |
| non.empty.atclause</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"> |
| <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="SingleLineJavadoc"> |
| <subsection name="Description"> |
| <p>Since Checkstyle 6.0</p> |
| <p> |
| Checks that a JavaDoc block can fit in a single line and doesn't |
| contain at-clauses. Javadoc comment that contains at least one at-clause |
| should be formatted in a few lines. |
| </p> |
| </subsection> |
| |
| <subsection name="Properties"> |
| <table> |
| <tr> |
| <th>name</th> |
| <th>description</th> |
| <th>type</th> |
| <th>default value</th> |
| <th>since</th> |
| </tr> |
| <tr> |
| <td>violateExecutionOnNonTightHtml</td> |
| <td> |
| If turned on, will 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.3</td> |
| </tr> |
| <tr> |
| <td>ignoredTags</td> |
| <td>allows to specify at-clauses which are ignored by the check.</td> |
| <td><a href="property_types.html#stringSet">String Set</a></td> |
| <td><code>null</code></td> |
| <td>6.8</td> |
| </tr> |
| <tr> |
| <td>ignoreInlineTags</td> |
| <td>whether inline tags must be ignored.</td> |
| <td><a href="property_types.html#boolean">Boolean</a></td> |
| <td><code>true</code></td> |
| <td>6.8</td> |
| </tr> |
| </table> |
| </subsection> |
| |
| <subsection name="Examples"> |
| <p> |
| Default configuration: |
| </p> |
| <source> |
| <module name="SingleLineJavadoc"/> |
| </source> |
| <p> |
| To specify a list of ignored at-clauses and make inline at-clauses not ignored: |
| </p> |
| <source> |
| <module name="SingleLineJavadoc"> |
| <property name="ignoredTags" value="@inheritDoc, @see"/> |
| <property name="ignoreInlineTags" value="false"/> |
| </module> |
| </source> |
| </subsection> |
| |
| <subsection name="Example of Usage"> |
| <ul> |
| <li> |
| <a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fresources+filename%3Agoogle_checks.xml+repo%3Acheckstyle%2Fcheckstyle+SingleLineJavadoc"> |
| Google Style</a> |
| </li> |
| <li> |
| <a href="https://github.com/search?q=path%3Aconfig+filename%3Acheckstyle_checks.xml+repo%3Acheckstyle%2Fcheckstyle+SingleLineJavadoc"> |
| Checkstyle Style</a> |
| </li> |
| </ul> |
| </subsection> |
| |
| <subsection name="Error Messages"> |
| <ul> |
| <li> |
| <a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fresources%2Fcom%2Fpuppycrawl%2Ftools%2Fcheckstyle%2Fchecks%2Fjavadoc+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%2Fjavadoc+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%2Fjavadoc+filename%3Amessages*.properties+repo%3Acheckstyle%2Fcheckstyle+%22javadoc.wrong.singleton.html.tag%22"> |
| javadoc.wrong.singleton.html.tag</a> |
| </li> |
| <li> |
| <a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fresources%2Fcom%2Fpuppycrawl%2Ftools%2Fcheckstyle%2Fchecks%2Fjavadoc+filename%3Amessages*.properties+repo%3Acheckstyle%2Fcheckstyle+%22singleline.javadoc%22"> |
| singleline.javadoc</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"> |
| <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="SummaryJavadoc"> |
| <subsection name="Description"> |
| <p>Since Checkstyle 6.0</p> |
| <p> |
| Checks that <a href="http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html#firstsentence"> |
| Javadoc summary sentence</a> does not contain phrases that are not recommended to use. Summaries that contain |
| only the <code>{@inheritDoc}</code> tag are skipped. Check also violate javadoc that does not contain first sentence. |
| </p> |
| </subsection> |
| |
| <subsection name="Properties"> |
| <table> |
| <tr> |
| <th>name</th> |
| <th>description</th> |
| <th>type</th> |
| <th>default value</th> |
| <th>since</th> |
| </tr> |
| <tr> |
| <td>violateExecutionOnNonTightHtml</td> |
| <td> |
| If turned on, will 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.3</td> |
| </tr> |
| <tr> |
| <td>forbiddenSummaryFragments</td> |
| <td>forbidden summary fragments</td> |
| <td><a href="property_types.html#regexp">Regular Expression</a></td> |
| <td><code>"^$"</code></td> |
| <td>6.0</td> |
| </tr> |
| <tr> |
| <td>period</td> |
| <td>period symbol at the end of first javadoc sentence</td> |
| <td><a href="property_types.html#string">String literal</a></td> |
| <td><code>.</code></td> |
| <td>6.2</td> |
| </tr> |
| </table> |
| </subsection> |
| |
| <subsection name="Examples"> |
| <p> |
| By default Check validate that first sentence is not empty and first sentence is not missing: |
| </p> |
| <source> |
| <module name="SummaryJavadocCheck"/> |
| </source> |
| <p> |
| Example of <code>{@inheritDoc}</code> without summary. |
| </p> |
| <source> |
| <![CDATA[ |
| public class Test extends Exception { |
| //Valid |
| /** |
| * {@inheritDoc} |
| */ |
| public String ValidFunction(){ |
| return ""; |
| } |
| //Violation |
| /** |
| * |
| */ |
| public String InvalidFunction(){ |
| return ""; |
| } |
| } |
| ]]> |
| </source> |
| <p> |
| To ensure that summary do not contain phrase like "This method returns" , use following config: |
| </p> |
| <source> |
| <module name="SummaryJavadocCheck"> |
| <property name="forbiddenSummaryFragments" value="^This method returns.*"/> |
| </module> |
| </source> |
| <p> |
| To specify period symbol at the end of first javadoc sentence: |
| </p> |
| <source> |
| <module name="SummaryJavadocCheck"> |
| <property name="period" value="。"/> |
| </module> |
| </source> |
| <p> |
| Example of period property. |
| </p> |
| |
| <source><![CDATA[ |
| public class TestClass { |
| /** |
| * This is invalid java doc. |
| */ |
| void invalidJavaDocMethod() { |
| } |
| /** |
| * This is valid java doc。 |
| */ |
| void validJavaDocMethod() { |
| } |
| } |
| ]]></source> |
| </subsection> |
| <subsection name="Example of Usage"> |
| <ul> |
| <li> |
| <a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fresources+filename%3Agoogle_checks.xml+repo%3Acheckstyle%2Fcheckstyle+SummaryJavadoc"> |
| Google Style</a> |
| </li> |
| <li> |
| <a href="https://github.com/search?q=path%3Aconfig+filename%3Acheckstyle_checks.xml+repo%3Acheckstyle%2Fcheckstyle+SummaryJavadoc"> |
| Checkstyle Style</a> |
| </li> |
| </ul> |
| </subsection> |
| |
| <subsection name="Error Messages"> |
| <ul> |
| <li> |
| <a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fresources%2Fcom%2Fpuppycrawl%2Ftools%2Fcheckstyle%2Fchecks%2Fjavadoc+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%2Fjavadoc+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%2Fjavadoc+filename%3Amessages*.properties+repo%3Acheckstyle%2Fcheckstyle+%22javadoc.wrong.singleton.html.tag%22"> |
| javadoc.wrong.singleton.html.tag</a> |
| </li> |
| <li> |
| <a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fresources%2Fcom%2Fpuppycrawl%2Ftools%2Fcheckstyle%2Fchecks%2Fjavadoc+filename%3Amessages*.properties+repo%3Acheckstyle%2Fcheckstyle+%22summary.first.sentence%22"> |
| summary.first.sentence</a> |
| </li> |
| <li> |
| <a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fresources%2Fcom%2Fpuppycrawl%2Ftools%2Fcheckstyle%2Fchecks%2Fjavadoc+filename%3Amessages*.properties+repo%3Acheckstyle%2Fcheckstyle+%22summary.javaDoc%22"> |
| summary.javaDoc</a> |
| </li> |
| <li> |
| <a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fresources%2Fcom%2Fpuppycrawl%2Ftools%2Fcheckstyle%2Fchecks%2Fjavadoc+filename%3Amessages*.properties+repo%3Acheckstyle%2Fcheckstyle+%22summary.javaDoc.missing%22"> |
| summary.javaDoc.missing</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"> |
| <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="WriteTag"> |
| <subsection name="Description"> |
| <p>Since Checkstyle 4.2</p> |
| <p> |
| Requires user defined JavaDoc tag to be present in javadoc comment with defined format. To define the |
| format for a tag, set property tagFormat to a regular |
| expression. Property tagSeverity is used for severity of events when the tag exists. |
| </p> |
| </subsection> |
| |
| <subsection name="Properties"> |
| <table> |
| <tr> |
| <th>name</th> |
| <th>description</th> |
| <th>type</th> |
| <th>default value</th> |
| <th>since</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> |
| <td>4.2</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> |
| <td>4.2</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> |
| <td>4.2</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#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#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#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#ENUM_CONSTANT_DEF">ENUM_CONSTANT_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#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#ENUM_DEF">ENUM_DEF</a>, |
| <a href="apidocs/com/puppycrawl/tools/checkstyle/api/TokenTypes.html#ANNOTATION_DEF">ANNOTATION_DEF</a>. |
| </td> |
| <td>4.2</td> |
| </tr> |
| </table> |
| </subsection> |
| |
| <subsection name="Examples"> |
| <p> |
| An example of how to configure the check for printing author name is: |
| </p> |
| |
| <source> |
| <module name="WriteTag"> |
| <property name="tag" value="@author"/> |
| <property name="tagFormat" value="\S"/> |
| </module> |
| </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> |
| <module name="WriteTag"> |
| <property name="tag" value="@incomplete"/> |
| <property name="tagFormat" value="\S"/> |
| <property name="severity" value="ignore"/> |
| <property name="tagSeverity" value="warning"/> |
| </module> |
| </source> |
| </subsection> |
| |
| <subsection name="Example of Usage"> |
| <ul> |
| <li> |
| <a href="https://github.com/search?q=path%3Aconfig+filename%3Acheckstyle_checks.xml+repo%3Acheckstyle%2Fcheckstyle+WriteTag"> |
| Checkstyle Style</a> |
| </li> |
| </ul> |
| </subsection> |
| |
| <subsection name="Error Messages"> |
| <ul> |
| <li> |
| <a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fresources%2Fcom%2Fpuppycrawl%2Ftools%2Fcheckstyle%2Fchecks%2Fjavadoc+filename%3Amessages*.properties+repo%3Acheckstyle%2Fcheckstyle+%22javadoc.writeTag%22"> |
| javadoc.writeTag</a> |
| </li> |
| <li> |
| <a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fresources%2Fcom%2Fpuppycrawl%2Ftools%2Fcheckstyle%2Fchecks%2Fjavadoc+filename%3Amessages*.properties+repo%3Acheckstyle%2Fcheckstyle+%22type.missingTag%22"> |
| type.missingTag</a> |
| </li> |
| <li> |
| <a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fresources%2Fcom%2Fpuppycrawl%2Ftools%2Fcheckstyle%2Fchecks%2Fjavadoc+filename%3Amessages*.properties+repo%3Acheckstyle%2Fcheckstyle+%22type.tagFormat%22"> |
| type.tagFormat</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"> |
| <p> |
| com.puppycrawl.tools.checkstyle.checks.javadoc |
| </p> |
| </subsection> |
| |
| <subsection name="Parent Module"> |
| <p> |
| <a href="config.html#TreeWalker">TreeWalker</a> |
| </p> |
| </subsection> |
| </section> |
| |
| </body> |
| </document> |
| |