diff options
Diffstat (limited to 'src/xdocs/config_filters.xml')
| -rw-r--r-- | src/xdocs/config_filters.xml | 542 |
1 files changed, 538 insertions, 4 deletions
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> |