diff options
Diffstat (limited to 'src/xdocs')
| -rw-r--r-- | src/xdocs/config.xml | 14 | ||||
| -rw-r--r-- | src/xdocs/config_coding.xml | 4 | ||||
| -rw-r--r-- | src/xdocs/config_filters.xml | 542 | ||||
| -rw-r--r-- | src/xdocs/config_javadoc.xml | 62 | ||||
| -rw-r--r-- | src/xdocs/index.xml.vm | 6 | ||||
| -rw-r--r-- | src/xdocs/releasenotes.xml | 125 | ||||
| -rw-r--r-- | src/xdocs/writingjavadocchecks.xml.vm | 63 |
7 files changed, 797 insertions, 19 deletions
diff --git a/src/xdocs/config.xml b/src/xdocs/config.xml index 2e8103b16..1b7143160 100644 --- a/src/xdocs/config.xml +++ b/src/xdocs/config.xml @@ -14,13 +14,12 @@ </head> <body> -<!-- till https://issues.apache.org/jira/browse/MSITE-748 <section name="Content"> <macro name="toc"> <param name="fromDepth" value="1"/> <param name="toDepth" value="1"/> </macro> - </section> --> + </section> <section name="Overview"> <p> @@ -823,7 +822,7 @@ </source> <div class="tip"> - <h4>Note</h4> + <b>Note</b> <p> As of Checkstyle 5.0 it is unnecessary to repeat the <code>package</code> elements for Checkstyle's packages in @@ -835,7 +834,7 @@ <section name="XML Structure"> - <h4>Configuration XML Document</h4> + <b>Configuration XML Document</b> <p> The following DTD for a configuration XML document specifies the hierarchy of modules and their properties: @@ -880,7 +879,7 @@ conventions. </p> - <h4>Package Names XML Document</h4> + <b>Package Names XML Document</b> <p> This is a DTD for a package names XML document: </p> @@ -907,7 +906,7 @@ "http://checkstyle.sourceforge.net/dtds/packages_1_1.dtd"> </source> - <h4>Suppressions XML Document</h4> + <b>Suppressions XML Document</b> <p> This is a DTD for a suppressions XML document: </p> @@ -918,8 +917,9 @@ <!ELEMENT suppressions (suppress*)> <!ELEMENT suppress EMPTY> -<!ATTLIST suppress files CDATA #REQUIRED +<!ATTLIST suppress files CDATA #IMPLIED checks CDATA #IMPLIED + message CDATA #IMPLIED id CDATA #IMPLIED lines CDATA #IMPLIED columns CDATA #IMPLIED> diff --git a/src/xdocs/config_coding.xml b/src/xdocs/config_coding.xml index d05b6c229..c44d889f6 100644 --- a/src/xdocs/config_coding.xml +++ b/src/xdocs/config_coding.xml @@ -3984,6 +3984,10 @@ class C { <a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fresources%2Fcom%2Fpuppycrawl%2Ftools%2Fcheckstyle%2Fchecks%2Fcoding+filename%3Amessages*.properties+repo%3Acheckstyle%2Fcheckstyle+%22return.count%22"> return.count</a> </li> + <li> + <a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fresources%2Fcom%2Fpuppycrawl%2Ftools%2Fcheckstyle%2Fchecks%2Fcoding+filename%3Amessages*.properties+repo%3Acheckstyle%2Fcheckstyle+%22return.countVoid%22"> + return.countVoid</a> + </li> </ul> <p> All messages can be customized if the default message doesn't suit you. diff --git a/src/xdocs/config_filters.xml b/src/xdocs/config_filters.xml index e5ae5cd77..f78de0410 100644 --- a/src/xdocs/config_filters.xml +++ b/src/xdocs/config_filters.xml @@ -483,19 +483,25 @@ public class UserService { <code>files</code> - a <a href="property_types.html#regexp">Regular Expression</a> matched against the file name associated with an audit - event. It is mandatory. + event. It is optional. </li> <li> <code>checks</code> - a <a href="property_types.html#regexp">Regular Expression</a> matched against the name of the check associated with an audit - event. Optional if <code>id</code> is specified. + event. Optional as long as <code>id</code> or <code>message</code> is specified. + </li> + <li> + <code>message</code> - + a <a href="property_types.html#regexp">Regular Expression</a> + matched against the message of the check associated with an audit + event. Optional as long as <code>checks</code> or <code>id</code> is specified. </li> <li> <code>id</code> - a <a href="property_types.html#string">string</a> matched against the ID of the check associated with an audit - event. Optional if <code>checks</code> is specified. + event. Optional as long as <code>checks</code> or <code>message</code> is specified. </li> <li> <code>lines</code> - a comma-separated list of @@ -527,7 +533,9 @@ public class UserService { lines 82 and 108 to 122 of file <code>AbstractComplexityCheck.java</code>, and <code>MagicNumberCheck</code> errors for line - 221 of file <code>JavadocStyleCheck.java</code>: + 221 of file <code>JavadocStyleCheck.java</code>, + and '<code>Missing a Javadoc comment</code>' errors + for all lines and files: </p> <source> <?xml version="1.0"?> @@ -544,6 +552,7 @@ public class UserService { files="JavadocStyleCheck.java" lines="221"/> </suppressions> +<suppress message="Missing a Javadoc comment"/></suppressions> </source> <p> As another example to suppress Check by module id: @@ -615,6 +624,12 @@ public class UserService { <source> <suppress checks="FileLength" files="com[\\/]mycompany[\\/]app[\\/].*IT.java"/> </source> + <p> + Suppress naming errors on variable named 'log' in all files: + </p> + <source> +<suppress message="Name 'log' must match pattern"/> + </source> </subsection> <subsection name="Example of Usage"> <ul> @@ -633,6 +648,229 @@ public class UserService { </subsection> </section> + <section name="SuppressionXpathFilter"> + <subsection name="Description"> + <p>Since Checkstyle 8.6</p> + <p> + Filter <code>SuppressionXpathFilter</code> works as + <a href="config_filters.html#SuppressionFilter">SuppressionFilter</a>. + Additionally, filter processes <code>suppress-xpath</code> elements, + which contains xpath-expressions. Xpath-expressions + are queries for suppressed nodes inside the AST tree. + </p> + <p> + Note, after resolving + <a href="https://github.com/checkstyle/checkstyle/issues/4530">issue 4530</a> + CLI will have option to generate the basic suppression xpath to elements. + </p> + <p> + Currently, filter supports the following + checks: + </p> + <ul> + <li>CyclomaticComplexityCheck</li> + <li>DeclarationOrderCheck</li> + <li>DefaultComesLastCheck</li> + <li>ExplicitInitializationCheck</li> + <li>FallThroughCheck</li> + <li>HiddenFieldCheck</li> + <li>IllegalCatchCheck</li> + <li>IllegalThrowsCheck</li> + <li>JavadocMethodCheck</li> + <li>JavadocVariableCheck</li> + <li>ImportControlCheck</li> + <li>LeftCurlyCheck</li> + <li>MethodParamPadCheck</li> + <li>MultipleVariableDeclarationCheck</li> + <li>NestedForDepthCheck</li> + <li>NestedIfDepthCheck</li> + <li>NestedTryDepthCheck</li> + <li>NPathComplexityCheck</li> + <li>OneStatementPerLineCheck</li> + <li>OuterTypeNumberCheck</li> + <li>RequireThisCheck</li> + <li>RightCurlyCheck</li> + </ul> + <p> + Note, that support for other Checks will be available after resolving + <a href="https://github.com/checkstyle/checkstyle/issues/4830">issue 4830</a>. + </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>file</td> + <td> + the location of the <em>suppressions XML document</em> file. + The order the location is checked is: + <ol> + <li>as a filesystem location</li> + <li> + if no file found, and the location starts with either + <code>http://</code> or <code>https://</code>, then it + is interpreted as a URL + </li> + <li> + if no file found, then passed to the + <code>ClassLoader.getResource()</code> method. + </li> + </ol> + </td> + <td><a href="property_types.html#string">string</a></td> + <td><code>none</code></td> + <td>8.6</td> + </tr> + <tr> + <td>optional</td> + <td> + Tells what to do when the file is not existing. If + optional is set to false the file must exist, or else + it ends with error. On the other hand if optional is + true and file is not found, the filter accept all + audit events. + </td> + <td><a href="property_types.html#boolean">Boolean</a></td> + <td><code>false</code></td> + <td>8.6</td> + </tr> + </table> + </subsection> + <subsection name="Examples"> + <p> + For example, the following configuration fragment directs the + Checker to use a <code>SuppressionXpathFilter</code> + with suppressions + file <code>config/suppressions.xml</code>: + </p> + <source> +<module name="SuppressionXpathFilter"> + <property name="file" value="config/suppressions.xml"/> + <property name="optional" value="false"/> +</module> + </source> + <p> + A <a href="config.html#XML_Structure"><em>suppressions XML + document</em></a> contains a set + of <code>suppress</code> and <code>suppress-xpath</code> elements, where + each <code>suppress-xpath</code> element can have the + following attributes: + </p> + <ul> + <li> + <code>files</code> - + a <a href="property_types.html#regexp">Regular Expression</a> + matched against the file name associated with an audit + event. It is optional. + </li> + <li> + <code>checks</code> - + a <a href="property_types.html#regexp">Regular Expression</a> + matched against the name of the check associated with an audit + event. Optional as long as <code>id</code> or <code>message</code> is specified. + </li> + <li> + <code>message</code> - + a <a href="property_types.html#regexp">Regular Expression</a> + matched against the message of the check associated with an audit + event. Optional as long as <code>checks</code> or <code>id</code> is specified. + </li> + <li> + <code>id</code> - + a <a href="property_types.html#string">string</a> + matched against the ID of the check associated with an audit + event. Optional as long as <code>checks</code> or <code>message</code> is specified. + </li> + <li> + <code>query</code> - + a <a href="property_types.html#string">string</a> + xpath query. It is optional. + </li> + </ul> + <p> + Each audit event is checked against + each <code>suppress</code> and <code>suppress-xpath</code> element. It is + suppressed if all specified attributes match against the audit + event. + </p> + <p> + The following suppressions XML document directs + a <code>SuppressionXpathFilter</code> to + reject <code>CyclomaticComplexity</code> errors for + all methods with name <i>sayHelloWorld</i> inside <i>FileOne</i> + and <i>FileTwo</i> classes: + </p> + <source> +<?xml version="1.0"?> + +<!DOCTYPE suppressions PUBLIC +"-//Puppy Crawl//DTD Suppressions Xpath Experimental 1.2//EN" +"http://checkstyle.sourceforge.net/dtds/suppressions_1_2_xpath_experimental.dtd"> + +<suppressions> + <suppress-xpath checks="CyclomaticComplexity" + files="FileOne.java,FileTwo.java" + query="//METHOD_DEF[@text='sayHelloWorld']"/> +</suppressions> + </source> + <p> + Suppress checks for package definitions: + </p> + <source> +<suppress-xpath checks=".*" query="/PACKAGE_DEF"/> + </source> + <p> + Suppress checks for parent element of the first variable definition: + </p> + <source> +<suppress-xpath checks=".*" query="(//VARIABLE_DEF)[1]/.."/> + </source> + <p> + Suppress checks for elements which are either class definitions, + either method definitions. + </p> + <source> +<suppress-xpath checks=".*" query="//CLASS_DEF | //METHOD_DEF"/> + </source> + <p> + Suppress checks for certain methods: + </p> + <source> +<suppress-xpath checks=".*" query="//METHOD_DEF[@text='getSomeVar' + or @text='setSomeVar']"/> + </source> + <p> + Suppress checks for variable <i>testVariable</i> inside <i>testMethod</i> method + inside <i>TestClass</i> class. + </p> + <source> +<suppress-xpath checks=".*" query="/CLASS_DEF[@text='TestClass'] + //METHOD_DEF[@text='testMethod']//VARIABLE_DEF[@text='testVariable']"/> + </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+SuppressionXpathFilter"> + Checkstyle Style</a> + </li> + </ul> + </subsection> + <subsection name="Package"> + <p> com.puppycrawl.tools.checkstyle.filters </p> + </subsection> + + <subsection name="Parent Module"> + <p> <a href="config.html#TreeWalker">TreeWalker</a> </p> + </subsection> + </section> + <section name="SuppressWarningsFilter"> <subsection name="Description"> <p>Since Checkstyle 5.7</p> @@ -986,5 +1224,301 @@ public class UserService { <p> <a href="config.html#TreeWalker">TreeWalker</a> </p> </subsection> </section> + + <section name="SuppressWithPlainTextCommentFilter"> + <subsection name="Description"> + <p>Since Checkstyle 8.6</p> + <p> + Filter <code>SuppressWithPlainTextCommentFilter</code> uses plain text to suppress + audit events. The filter can be used only to suppress audit events received from + the checks which implement FileSetCheck interface. In other words, the checks + which have Checker as a parent module. The filter knows nothing about AST, + it treats only plain text comments and extracts the information required + for suppression from the plain text comments. Currently the filter supports + only single line comments. + </p> + <p> + Please, be aware of the fact that, it is not recommended to use the filter + for Java code anymore, however you still are able to use it to suppress audit + events received from the checks which implement FileSetCheck interface. + </p> + <p> + Rationale: Sometimes there are legitimate reasons for violating + a check. When this is a matter of the code in question and not + personal preference, the best place to override the policy is in + the code itself. Semi-structured comments can be associated + with the check. This is sometimes superior to a separate + suppressions file, which must be kept up-to-date as the source + file is edited. + </p> + <p> + Note that the suppression comment should be put before the violation. You can use more + than one suppression comment each on separate line. + </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>offCommentFormat</td> + <td>comment pattern to trigger filter to begin suppression</td> + <td><a href="property_types.html#regexp">Regular Expression</a></td> + <td><code>"// CHECKSTYLE:OFF"</code></td> + <td>8.6</td> + </tr> + <tr> + <td>onCommentFormat</td> + <td>comment pattern to trigger filter to end suppression</td> + <td><a href="property_types.html#regexp">Regular Expression</a></td> + <td><code>"// CHECKSTYLE:ON"</code></td> + <td>8.6</td> + </tr> + <tr> + <td>checkFormat</td> + <td>check pattern to suppress</td> + <td><a href="property_types.html#regexp">Regular Expression</a></td> + <td><code>".*"</code></td> + <td>8.6</td> + </tr> + <tr> + <td>messageFormat</td> + <td>message pattern to suppress</td> + <td><a href="property_types.html#regexp">Regular Expression</a></td> + <td><code>null</code></td> + <td>8.6</td> + </tr> + </table> + <p> + offCommentFormat and onCommentFormat must have equal <a + href="https://docs.oracle.com/javase/7/docs/api/java/util/regex/Matcher.html#groupCount()">paren counts</a>. + </p> + </subsection> + <subsection name="Examples"> + <p> + To configure a filter to suppress audit events between a comment + containing <code>CHECKSTYLE:OFF</code> and a comment containing + <code>CHECKSTYLE:ON</code>: + </p> + <source> +<module name="Checker"> + ... + <module name="SuppressWithPlainTextCommentFilter"/> + ... +</module> + </source> + <p> + To configure a filter to suppress audit events between a comment + containing line <code>BEGIN GENERATED CONTENT</code> and a comment + containing line <code>END GENERATED CONTENT</code> + (Checker is configured to check only properties files): + </p> + <source> +<module name="Checker"> + <property name="fileExtensions" value="properties"/> + + <module name="SuppressWithPlainTextCommentFilter"> + <property name="offCommentFormat" value="BEGIN GENERATED CONTENT"/> + <property name="onCommentFormat" value="END GENERATED CONTENT"/> + </module> + +</module> + </source> + <source> +//BEGIN GENERATED CONTENT +my.property=value1 // No violation events will be reported +my.property=value2 // No violation events will be reported +//END GENERATED CONTENT +. . . + </source> + <p> + To configure a filter so that <code>-- stop tab + check</code> and <code>-- resume tab check</code> marks allowed tab positions + (Checker is configured to check only sql files): + </p> + <source> +<module name="Checker"> + <property name="fileExtensions" value="sql"/> + + <module name="SuppressWithPlainTextCommentFilter"> + <property name="offCommentFormat" value="stop tab check"/> + <property name="onCommentFormat" value="resume tab check"/> + <property name="checkFormat" value="FileTabCharacterCheck"/> + </module> + +</module> + </source> + <source> +-- stop tab check + SELECT * FROM users // won't warn here if there is a tab character on line +-- resume tab check + SELECT 1 // will warn here if there is a tab character on line + </source> + <p> + To configure a filter so that name of suppressed check mentioned + in comment <code>CSOFF: <i>regexp</i></code> + and <code>CSON: <i>regexp</i></code> mark a matching check + (Checker is configured to check only xml files): + </p> + <source> +<module name="Checker"> + <property name="fileExtensions" value="xml"/> + + <module name="SuppressWithPlainTextCommentFilter"> + <property name="offCommentFormat" value="CSOFF\: ([\w\|]+)"/> + <property name="onCommentFormat" value="CSON\: ([\w\|]+)"/> + <property name="checkFormat" value="$1"/> + </module> + +</module> + </source> + <source> +// CSOFF: RegexpSinglelineCheck +<condition property="checkstyle.ant.skip"> // RegexpSingleline check won't warn here if the line matches regexp + <isset property="checkstyle.ant.skip"/> // RegexpSingleline check won't warn here if the line matches regexp +</condition> // RegexpSingleline check won't warn here if the line matches regexp +// CSON: RegexpSinglelineCheck +<property name="checkstyle.pattern.todo" value="NOTHingWillMatCH_-"/> // RegexpSingleline check will warn here if the line matches regexp + </source> + <p> + To configure a filter to suppress all audit events between a comment + containing <code>CHECKSTYLE_OFF: ALMOST_ALL</code> and a comment containing + <code>CHECKSTYLE_OFF: ALMOST_ALL</code> except for the <em>EqualsHashCode</em> check + (Checker is configured to check only java files): + </p> + <source> +<module name="Checker"> + <property name="fileExtensions" value="java"/> + + <module name="SuppressWithPlainTextCommentFilter"> + <property name="offCommentFormat" value="CHECKSTYLE_OFF: ALMOST_ALL"/> + <property name="onCommentFormat" value="CHECKSTYLE_ON: ALMOST_ALL"/> + <property name="checkFormat" value="^((?!(FileTabCharacterCheck)).)*$"/> + </module> + +</module> + </source> + <source> +// CHECKSTYLE_OFF: ALMOST_ALL +public static final int array []; +private String [] strArray; +// CHECKSTYLE_ON: ALMOST_ALL +private int array1 []; + </source> + <p> + To configure a filter to suppress Check's violation message <b>which matches + specified message in messageFormat</b> (so suppression will not be only by + Check's name, but also by message text, as the same Check can report + violations with different message format) between a comment + containing <code>stop</code> and comment containing <code>resume</code>: + </p> + <source> +<module name="Checker"> + <module name="SuppressWithPlainTextCommentFilter"> + <property name="offCommentFormat" value="stop"/> + <property name="onCommentFormat" value="resume"/> + <property name="checkFormat" value="FileTabCharacterCheck"/> + <property name="messageFormat" value="^File contains tab characters (this is the first instance)\.$"/> + </module> +</module> + </source> + <p> + It is possible to specify an ID of checks, so that it can be leveraged by the + SuppressWithPlainTextCommentFilter to skip validations. + The following examples show how to skip validations near code that is surrounded + with <code>-- CSOFF <ID> (reason)</code> and <code>-- CSON <ID></code>, + where ID is the ID of checks you want to suppress. + </p> + <p> + Examples of Checkstyle checks configuration: + </p> + <source> +<module name="RegexpSinglelineJava"> + <property name="id" value="count"/> + <property name="format" value="^.*COUNT(*).*$"/> + <property name="message" value="Don't use COUNT(*), use COUNT(1) instead."/> +</module> + +<module name="RegexpSinglelineJava"> + <property name="id" value="join"/> + <property name="format" value="^.*JOIN\s.+\s(ON|USING)$"/> + <property name="message" value="Don't use JOIN, use sub-select instead."/> +</module> + </source> + <p> + Example of SuppressWithPlainTextCommentFilter configuration (checkFormat which is set to '$1' + points that ID of the checks is in the first group of offCommentFormat and + onCommentFormat regular expressions): + </p> + <source> +<module name="Checker"> + <property name="fileExtensions" value="sql"/> + + <module name="SuppressWithPlainTextCommentFilter"> + <property name="offCommentFormat" value="CSOFF (\w+) \(\w+\)"/> + <property name="onCommentFormat" value="CSON (\w+)"/> + <property name="checkFormat" value="$1"/> + </module> + +</module> + </source> + <source> +-- CSOFF join (it is ok to use join here for performance reasons) +SELECT name, job_name +FROM users AS u +JOIN jobs AS j ON u.job_id = j.id +-- CSON join + +-- CSOFF count (test query execution plan) +EXPLAIN SELECT COUNT(*) FROM restaurants +-- CSON count + </source> + <p> + Example of how to configure the check to suppress more than one check + (Checker is configured to check only sql files). + </p> + <source> +<module name="Checker"> + <property name="fileExtensions" value="sql"/> + + <module name="SuppressWithPlainTextCommentFilter"> + <property name="offCommentFormat" value="@cs-\: ([\w\|]+)"/> + <property name="checkFormat" value="$1"/> + </module> + +</module> + </source> + <source> +-- @cs-: RegexpSinglelineCheck +-- @cs-: FileTabCharacterCheck +CREATE TABLE STATION ( + ID INTEGER PRIMARY KEY, + CITY CHAR(20), + STATE CHAR(2), + LAT_N REAL, + LONG_W REAL); + </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+SuppressWithPlainTextCommentFilter"> + Checkstyle Style</a> + </li> + </ul> + </subsection> + <subsection name="Package"> + <p> com.puppycrawl.tools.checkstyle.filters </p> + </subsection> + + <subsection name="Parent Module"> + <p> <a href="config.html#Checker">Checker</a> </p> + </subsection> + </section> </body> </document> diff --git a/src/xdocs/config_javadoc.xml b/src/xdocs/config_javadoc.xml index c1ade7ffd..49da8de24 100644 --- a/src/xdocs/config_javadoc.xml +++ b/src/xdocs/config_javadoc.xml @@ -41,6 +41,16 @@ <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 @@ -619,6 +629,16 @@ public boolean isSomething() <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> @@ -991,6 +1011,16 @@ public boolean isSomething() <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> @@ -1417,18 +1447,30 @@ public boolean isSomething() <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#TEXCEPTION_LITERAL">EXCEPTION_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#TEXCEPTION_LITERAL">EXCEPTION_LITERAL</a>, <a href="apidocs/com/puppycrawl/tools/checkstyle/api/JavadocTokenTypes.html#DEPRECATED_LITERAL">DEPRECATED_LITERAL</a>. </td> <td>7.3</td> @@ -1517,6 +1559,16 @@ public boolean isSomething() <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> @@ -1622,6 +1674,16 @@ public boolean isSomething() <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> diff --git a/src/xdocs/index.xml.vm b/src/xdocs/index.xml.vm index 1b281fe52..56ad4ecad 100644 --- a/src/xdocs/index.xml.vm +++ b/src/xdocs/index.xml.vm @@ -312,6 +312,12 @@ <td>Part of the standard JDEE distribution - <a href="https://github.com/jdee-emacs/jdee"/></td> <td><a href="https://github.com/jdee-emacs/jdee/blob/master/jdee-checkstyle.el">configuration could be seen at jdee-checkstyle.el</a></td> </tr> + <tr> + <td><a href="https://code.visualstudio.com/">Visual Studio Code</a></td> + <td>Sheng Chen</td> + <td><a href="https://marketplace.visualstudio.com/items?itemName=shengchen.vscode-checkstyle">vscode-checkstyle</a></td> + <td>Checkstyle for Microsoft Visual Studio Code</td> + </tr> </table> </subsection> diff --git a/src/xdocs/releasenotes.xml b/src/xdocs/releasenotes.xml index b4580cc8a..9a511e499 100644 --- a/src/xdocs/releasenotes.xml +++ b/src/xdocs/releasenotes.xml @@ -16,6 +16,129 @@ <body> <!-- placeholder for a new section --> + <section name="Release 8.6"> + <p>Breaking backward compatibility:</p> + <ul> + <li> + AbstractLoader: move out of api, rename, and remove abstract modifier . Author: Roman_Zhigunov <a href="https://github.com/checkstyle/checkstyle/issues/5338">#5338</a> + </li> + </ul> + <p>New:</p> + <ul> + <li> + new Checker filter SuppressWithPlainTextCommentFilter as akin to Treewalker's SuppressionCommentFilter. Author: Andrei Selkin <a href="https://github.com/checkstyle/checkstyle/issues/4841">#4841</a> + </li> + <li> + Add @exception JavaDoc block tag to NonEmptyAtclauseDescriptionCheck. Author: Lev_Sikhovets <a href="https://github.com/checkstyle/checkstyle/issues/5388">#5388</a> + </li> + <li> + Support suppression-xpath element in SuppressionLoader. Author: Timur Tibeyev <a href="https://github.com/checkstyle/checkstyle/issues/4421">#4421</a> + </li> + <li> + add ANNOTATION_DEF to RequireThisCheck. Author: rnveach <a href="https://github.com/checkstyle/checkstyle/issues/5363">#5363</a> + </li> + <li> + SuppressionFilter: add suppression by message. Author: rnveach <a href="https://github.com/checkstyle/checkstyle/issues/2804">#2804</a> + </li> + </ul> + <p>Bug fixes:</p> + <ul> + <li> + TranslationCheck: should fire file started/finished when invoking errors. Author: rnveach <a href="https://github.com/checkstyle/checkstyle/issues/5057">#5057</a> + </li> + <li> + fixed RequireThisCheck and for loop variable handling. Author: rnveach <a href="https://github.com/checkstyle/checkstyle/issues/5392">#5392</a> + </li> + <li> + changed RequireThis kept track of the frame being examined. Author: rnveach <a href="https://github.com/checkstyle/checkstyle/issues/5364">#5364</a> + </li> + <li> + ImportOrder with option=bottom should not allow non-static import after static import. Author: Julian Hyde <a href="https://github.com/checkstyle/checkstyle/issues/4981">#4981</a> + </li> + <li> + ReturnCount: unclear message when only max property is specified. Author: vaano94 <a href="https://github.com/checkstyle/checkstyle/issues/5306">#5306</a> + </li> + <li> + Incorrect indentation check for method preceded by annotation, with method parameter on separate line. Author: BBG <a href="https://github.com/checkstyle/checkstyle/issues/5154">#5154</a> + </li> + <li> + fixed RequireThisCheck and enum constants handling. Author: rnveach <a href="https://github.com/checkstyle/checkstyle/issues/5361">#5361</a> + </li> + <li> + fixed RequireThisCheck and catch variable handling. Author: rnveach <a href="https://github.com/checkstyle/checkstyle/issues/5351">#5351</a> + </li> + <li> + AnnotationUtility.getAnnotation fails when there is an comment in the annotation. Author: rnveach <a href="https://github.com/checkstyle/checkstyle/issues/5327">#5327</a> + </li> + <li> + False RedundantModifier violation for final method of enum inside final class. Author: BBG <a href="https://github.com/checkstyle/checkstyle/issues/5268">#5268</a> + </li> + <li> + fixed bug on matching xpath when no xpath given. Author: rnveach <a href="https://github.com/checkstyle/checkstyle/issues/5321">#5321</a> + </li> + <li> + Checkstyle ignores javadoc that placed over Annotation type elements . Author: Pavel Bludov <a href="https://github.com/checkstyle/checkstyle/issues/4169">#4169</a> + </li> + <li> + JavadocMethod: No error for a misplaced javadoc tag. Author: Pavel Bludov <a href="https://github.com/checkstyle/checkstyle/issues/4701">#4701</a> + </li> + </ul> + <p>Notes:</p> + <ul> + <li> + pitest: increase mutation coverage for pitest-checks-misc profile to 100%. Author: rnveach, vasilyeva <a href="https://github.com/checkstyle/checkstyle/issues/4675">#4675</a> + </li> + <li> + Some contents in messages_zh.properties for imports check are not well translated. Author: zhangduo <a href="https://github.com/checkstyle/checkstyle/issues/5393">#5393</a> + </li> + <li> + TranslationCheckTest.testLogOutput is failed . Author: rnveach <a href="https://github.com/checkstyle/checkstyle/issues/5141">#5141</a> + </li> + <li> + pitest: increase mutation coverage for pitest-checks-imports profile to 100%. Author: BBG <a href="https://github.com/checkstyle/checkstyle/issues/5004">#5004</a> + </li> + <li> + Indentaion problem in pjdbc project. Author: Roman Ivanov <a href="https://github.com/checkstyle/checkstyle/issues/5286">#5286</a> + </li> + <li> + Use versions-maven-plugin to report versions to update. Author: Roman Ivanov <a href="https://github.com/checkstyle/checkstyle/issues/5208">#5208</a> + </li> + <li> + minimize pitest-checkstyle-utils profile execution. Author: rnveach <a href="https://github.com/checkstyle/checkstyle/issues/4605">#4605</a> + </li> + <li> + api: abstract classes that extending concrete class. Author: rnveach <a href="https://github.com/checkstyle/checkstyle/issues/4716">#4716</a> + </li> + <li> + pitest: increase mutation coverage for pitest-checks-whitespace profile to 100%. Author: rnveach <a href="https://github.com/checkstyle/checkstyle/issues/5003">#5003</a> + </li> + <li> + pitest: increase mutation coverage for pitest-checks-metrics profile to 100%. Author: rnveach <a href="https://github.com/checkstyle/checkstyle/issues/5005">#5005</a> + </li> + <li> + pitest: increase mutation coverage for pitest-checks-coding profile to 100%. Author: rnveach <a href="https://github.com/checkstyle/checkstyle/issues/5008">#5008</a> + </li> + <li> + internal code: terminolozy problems in ModuleReflectionUtils. Author: rnveach <a href="https://github.com/checkstyle/checkstyle/issues/4876">#4876</a> + </li> + <li> + Add violateExecutionOnNonTightHtml property of AbstractJavadocCheck to xdoc. Author: rnveach <a href="https://github.com/checkstyle/checkstyle/issues/5002">#5002</a> + </li> + <li> + change all sonarqube.com to sonarcloud.io. Author: Roman Ivanov <a href="https://github.com/checkstyle/checkstyle/issues/5290">#5290</a> + </li> + <li> + doc: add 'Checkstyle for Microsoft Visual Studio Code' in known tools. Author: Roman Ivanov + </li> + <li> + Revert "infra: fix for travis:osx problem with 'shell_session_update: command not found'". Author: Roman Ivanov + </li> + <li> + Remove usage of DetailAST.branchContains. Author: rnveach <a href="https://github.com/checkstyle/checkstyle/issues/5124">#5124</a> + </li> + </ul> + </section> + <section name="Release 8.5"> <p>New:</p> <ul> @@ -3818,7 +3941,7 @@ Remove usage of deprecated methods from MainTest. Author: Michal Kordas <a href="https://github.com/checkstyle/checkstyle/issues/1325">#1325</a> </li> <li> - Restore checkstyle validation on https://sonarqube.com. Author: Roman Ivanov <a href="https://github.com/checkstyle/checkstyle/issues/1319">#1319</a> + Restore checkstyle validation on https://sonarcloud.io. Author: Roman Ivanov <a href="https://github.com/checkstyle/checkstyle/issues/1319">#1319</a> </li> <li> Update Maven Shade Plugin, EqualsVerifier, antlr, system-rules and Maven PMD Plugin to latest versions. Author: Michal Kordas diff --git a/src/xdocs/writingjavadocchecks.xml.vm b/src/xdocs/writingjavadocchecks.xml.vm index b07b52d14..209cbe666 100644 --- a/src/xdocs/writingjavadocchecks.xml.vm +++ b/src/xdocs/writingjavadocchecks.xml.vm @@ -23,25 +23,74 @@ <section name="What is Javadoc comment"> <p> - Javadoc comment is multiline comment <code>/* */</code> that starts with <b>*</b> character and placed above class definition, interface definition, enum definition, method definition or field definition. + Javadoc comment is a multiline comment <code>/* */</code> that starts with the <b>*</b> + character and placed above the class definition, interface definition, enum definition, + method definition or field definition. + If an annotation precedes any of the definitions listed above, then the javadoc comment + should be placed before the annotation. + If several multiline comments with javadoc identifiers are placed sequentially, only + the one closest to the definition, right above it, with the javadoc identifier will be used. + </p> + <p> + Javadoc comments should contain: a short summary (the first sentence), an optional + documentation section, an optional tag section. + The first sentence has a special meaning and should be clear, punchy, short, and is ended by + a period symbol. + Immediately after the first sentence, the main description could begin, which may be followed + by the tag section. + The tag section starts with the first block tag, which is defined by the first <code>@</code> + character that begins a line (ignoring leading asterisks, white space, and leading separator + <code>/**</code>). + </p> <p>For example, here is java file:</p> <source><![CDATA[ /** * My <b>class</b>. - * @see AbstractClass + * + * @see Annotation */ public class MyClass { + /** Not a javadoc (ignored). */ + + /** + * Doubles the value. + * The long and detailed explanation what the method does. + * + * @param value for doubling. + * @return double value. + */ + + /* + Multiline comment (ignored). + */ + @Annotation + /** Extra javadoc (ignored). */ + // Single line comment (ignored). + public int method(int value) { + /** Inner javadoc (ignored). */ + return value * 2; + } } ]]></source> - Javadoc content is: + <p>Javadoc content for the MyClass will be:</p> <source><![CDATA[ - * My <b>class</b>. - * @see AbstractClass + My <b>class</b>. + + @see Annotation ]]></source> - </p> + <p>Javadoc content for the MyClass.method will be:</p> + <source><![CDATA[ + Doubles the value. + The long and detailed explanation what the method does. + + @param value for doubling. + @return double value. + ]]></source> + <p> Attention that java comment starts with <code>/*</code>, following with Identificator of comment type. Javadoc Identificator is <code>*</code>. All symbols after Javadoc Identificator till <code>*/</code> are part of javadoc comment. - <p>Please note that javadoc-like(miltiline comment with javdoc identificator) comment inside a method is not a javadoc comment and skipped by + </p> + <p>Please note that javadoc-like (miltiline comment with javdoc identificator) comment inside a method is not a javadoc comment and skipped by Sun/Oracle javadoc tool and by our javadoc comment matcher, but such comment will be in AST. </p> <p>In internet you can find different types of documentation |