Issue #819: Split config.html into few pages
This commit is contained in:
Andrei Selkin
Roman Ivanov
parent
040436b960
commit
3ebddae1b9
|
|
@ -47,7 +47,7 @@
|
|||
href="https://plus.google.com/108692338295483568100/posts"
|
||||
/>
|
||||
</poweredBy>
|
||||
|
||||
|
||||
<body>
|
||||
<menu name="About">
|
||||
<item name="Checkstyle" href="index.html"/>
|
||||
|
|
@ -58,6 +58,7 @@
|
|||
<menu name="Documentation">
|
||||
<item name="Configuration" href="config.html">
|
||||
<item name="Property Types" href="property_types.html"/>
|
||||
<item name="Filters" href="config_filters.html"/>
|
||||
</item>
|
||||
|
||||
<item name="Running" href="running.html">
|
||||
|
|
|
|||
|
|
@ -245,6 +245,11 @@
|
|||
copy and maintain the whole configuration.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
You can find information about property types on
|
||||
<a href="property_types.html">Property Types</a> page.
|
||||
</p>
|
||||
|
||||
</section>
|
||||
|
||||
<section name="Checker">
|
||||
|
|
@ -637,797 +642,10 @@ OR
|
|||
can accept or reject an audit event. If all Filters accept an
|
||||
audit event, then the Checker reports the event. If any Filter
|
||||
rejects an event, then the Checker does not report the
|
||||
event.
|
||||
event. For more information please visit
|
||||
<a href="config_filters.html">filters page</a>.
|
||||
</p>
|
||||
|
||||
<subsection name="SeverityMatchFilter">
|
||||
<p>
|
||||
Filter <code>SeverityMatchFilter</code> decides
|
||||
audit events according to the <a href="#Severity">severity
|
||||
level</a> of the event.
|
||||
</p>
|
||||
|
||||
<h5>SeverityMatchFilter Properties</h5>
|
||||
<table>
|
||||
<tr>
|
||||
<th>name</th>
|
||||
<th>description</th>
|
||||
<th>type</th>
|
||||
<th>default value</th>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>severity</td>
|
||||
<td>the severity level of this filter</td>
|
||||
<td><a href="property_types.html#severity">severity</a></td>
|
||||
<td><code>error</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>acceptOnMatch</td>
|
||||
<td>
|
||||
If acceptOnMatch is <code>true</code>, then
|
||||
the filter accepts an audit event if and only if there is
|
||||
a match between the event's severity level and property
|
||||
severity. If acceptOnMatch
|
||||
is <code>false</code>, then the filter
|
||||
accepts an audit event if and only if there is not a match
|
||||
between the event's severity level and property severity.
|
||||
</td>
|
||||
<td><a href="property_types.html#boolean">boolean</a></td>
|
||||
<td><code>true</code></td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
<p>
|
||||
For example, the following configuration fragment directs the
|
||||
Checker to not report audit events with severity
|
||||
level <code>info</code>:
|
||||
</p>
|
||||
|
||||
<source>
|
||||
<module name="SeverityMatchFilter">
|
||||
<property name="severity" value="info"/>
|
||||
<property name="acceptOnMatch" value="false"/>
|
||||
</module>
|
||||
</source>
|
||||
</subsection>
|
||||
|
||||
<subsection name="SuppressionFilter">
|
||||
<p>
|
||||
Filter <code>SuppressionFilter</code> rejects
|
||||
audit events for Check errors according to
|
||||
a <a href="#XML_Details"><em>suppressions XML
|
||||
document</em></a> in a file. If there is no configured
|
||||
suppressions file, the Filter accepts all audit events.
|
||||
</p>
|
||||
|
||||
<h5>SuppressionFilter Properties</h5>
|
||||
<table>
|
||||
<tr>
|
||||
<th>name</th>
|
||||
<th>description</th>
|
||||
<th>type</th>
|
||||
<th>default value</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>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
<p>
|
||||
For example, the following configuration fragment directs the
|
||||
Checker to use a <code>SuppressionFilter</code>
|
||||
with suppressions
|
||||
file <code>docs/suppressions.xml</code>:
|
||||
</p>
|
||||
|
||||
<source>
|
||||
<module name="SuppressionFilter">
|
||||
<property name="file" value="docs/suppressions.xml"/>
|
||||
</module>
|
||||
</source>
|
||||
|
||||
<p>
|
||||
A <a href="#XML_Details"><em>suppressions XML
|
||||
document</em></a> contains a set
|
||||
of <code>suppress</code> elements, where
|
||||
each <code>suppress</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 mandatory.
|
||||
</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.
|
||||
</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.
|
||||
</li>
|
||||
<li>
|
||||
<code>lines</code> - a comma-separated list of
|
||||
values, where each value is
|
||||
an <a href="property_types.html#integer">integer</a> or a
|
||||
range of integers denoted by integer-integer. It is optional.
|
||||
</li>
|
||||
<li>
|
||||
<code>columns</code> - a comma-separated list of
|
||||
values, where each value is
|
||||
an <a href="property_types.html#integer">integer</a> or a
|
||||
range of integers denoted by integer-integer. It is optional.
|
||||
</li>
|
||||
</ul>
|
||||
|
||||
<p>
|
||||
Each audit event is checked against
|
||||
each <code>suppress</code> element. It is
|
||||
suppressed if all specified attributes match against the audit
|
||||
event.
|
||||
</p>
|
||||
|
||||
<h5>Examples</h5>
|
||||
|
||||
<p> You can download template of empty suppression filter <a href="files/suppressions_none.xml">here</a>.</p>
|
||||
|
||||
<p>
|
||||
The following suppressions XML document directs
|
||||
a <code>SuppressionFilter</code> to
|
||||
reject <code>JavadocStyleCheck</code> errors for
|
||||
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>:
|
||||
</p>
|
||||
|
||||
<source>
|
||||
<?xml version="1.0"?>
|
||||
|
||||
<!DOCTYPE suppressions PUBLIC
|
||||
"-//Puppy Crawl//DTD Suppressions 1.1//EN"
|
||||
"http://www.puppycrawl.com/dtds/suppressions_1_1.dtd">
|
||||
|
||||
<suppressions>
|
||||
<suppress checks="JavadocStyleCheck"
|
||||
files="AbstractComplexityCheck.java"
|
||||
lines="82,108-122"/>
|
||||
<suppress checks="MagicNumberCheck"
|
||||
files="JavadocStyleCheck.java"
|
||||
lines="221"/>
|
||||
</suppressions>
|
||||
</source>
|
||||
|
||||
<p>
|
||||
As another example to suppress Check by module id:
|
||||
</p>
|
||||
|
||||
<source>
|
||||
<module name="DescendantToken">
|
||||
<property name="id" value="stringEqual"/>
|
||||
<property name="tokens" value="EQUAL,NOT_EQUAL"/>
|
||||
<property name="limitedTokens" value="STRING_LITERAL"/>
|
||||
<property name="maximumNumber" value="0"/>
|
||||
<property name="maximumDepth" value="1"/>
|
||||
</module>
|
||||
|
||||
<module name="DescendantToken">
|
||||
<property name="id" value="switchNoDefault"/>
|
||||
<property name="tokens" value="LITERAL_SWITCH"/>
|
||||
<property name="maximumDepth" value="2"/>
|
||||
<property name="limitedTokens" value="LITERAL_DEFAULT"/>
|
||||
<property name="minimumNumber" value="1"/>
|
||||
</module>
|
||||
</source>
|
||||
|
||||
<p>
|
||||
Then the following can be used to suppress only the first
|
||||
check and not the second by using
|
||||
the <code>id</code> attribute:
|
||||
</p>
|
||||
|
||||
<source>
|
||||
<suppress id="stringEqual" files="SomeTestCode.java"/>
|
||||
</source>
|
||||
|
||||
<p>
|
||||
Suppress checks for hidden files and folders:
|
||||
</p>
|
||||
|
||||
<source>
|
||||
<suppress files="[/\\]\..+" checks=".*"/>
|
||||
</source>
|
||||
|
||||
<p>
|
||||
Suppress checks for Maven-generated code:
|
||||
</p>
|
||||
|
||||
<source>
|
||||
<suppress files="[/\\]target[/\\]" checks=".*"/>
|
||||
</source>
|
||||
|
||||
<p>
|
||||
Suppress checks for archives, classes and other binary files:
|
||||
</p>
|
||||
|
||||
<source>
|
||||
<suppress files=".+\.(?:jar|zip|war|class|tar|bin)$" checks=".*"/>
|
||||
</source>
|
||||
|
||||
<p>
|
||||
Suppress checks for image files:
|
||||
</p>
|
||||
|
||||
<source>
|
||||
<suppress files=".+\.(?:png|gif|jpg|jpeg)$" checks=".*"/>
|
||||
</source>
|
||||
|
||||
<p>
|
||||
Suppress checks for non-java files:
|
||||
</p>
|
||||
|
||||
<source>
|
||||
<suppress files=".+\.(?:txt|xml|csv|sh|thrift|html|sql|eot|ttf|woff|css|png)$" checks=".*"/>
|
||||
</source>
|
||||
|
||||
<p>
|
||||
Suppress all checks in generated sources:
|
||||
</p>
|
||||
|
||||
<source>
|
||||
<suppress checks=".*" files="com[\\/]mycompany[\\/]app[\\/]gen[\\/]"/>
|
||||
</source>
|
||||
|
||||
<p>
|
||||
Suppress FileLength check on integration tests in certain folder:
|
||||
</p>
|
||||
|
||||
<source>
|
||||
<suppress checks="FileLength" files="com[\\/]mycompany[\\/]app[\\/].*IT.java"/>
|
||||
</source>
|
||||
|
||||
</subsection>
|
||||
|
||||
<subsection name="SuppressionCommentFilter">
|
||||
<h4>SuppressionCommentFilter</h4>
|
||||
|
||||
<p>
|
||||
Filter <code>SuppressionCommentFilter</code> uses
|
||||
pairs of comments to suppress audit events.
|
||||
</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>
|
||||
Usage: This filter only works in conjunction with a <code>FileContentsHolder</code>, since that check makes
|
||||
the suppression comments in the Java files available. A configuration that includes this filter must
|
||||
configure <code>FileContentsHolder</code> as a
|
||||
child module of <code>TreeWalker</code>.
|
||||
</p>
|
||||
|
||||
<h5>SuppressionCommentFilter Properties</h5>
|
||||
<table>
|
||||
<tr>
|
||||
<th>name</th>
|
||||
<th>description</th>
|
||||
<th>type</th>
|
||||
<th>default value</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>
|
||||
</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>
|
||||
</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> (all checks)</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>messageFormat</td>
|
||||
<td>message pattern to suppress</td>
|
||||
<td><a href="property_types.html#regexp">regular expression</a></td>
|
||||
<td>none</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>checkCPP</td>
|
||||
<td>whether to check C++ style comments (<code>//</code>)</td>
|
||||
<td><a href="property_types.html#boolean">boolean</a></td>
|
||||
<td><code>true</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>checkC</td>
|
||||
<td>whether to check C style comments (<code>/* ... */</code>)</td>
|
||||
<td><a href="property_types.html#boolean">boolean</a></td>
|
||||
<td><code>true</code></td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
<h5>Restrictions</h5>
|
||||
<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>
|
||||
|
||||
<h5>Examples</h5>
|
||||
<p>
|
||||
Make sure that comments are available to the filter by enabling FileContentsHolder:
|
||||
</p>
|
||||
|
||||
<source>
|
||||
<module name="TreeWalker">
|
||||
...
|
||||
<module name="FileContentsHolder"/>
|
||||
...
|
||||
</module>
|
||||
</source>
|
||||
|
||||
<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="SuppressionCommentFilter"/>
|
||||
...
|
||||
</module>
|
||||
</source>
|
||||
|
||||
<p>
|
||||
To configure a filter to suppress audit events between a comment
|
||||
containing line <code>BEGIN GENERATED CODE</code> and a comment
|
||||
containing line <code>END GENERATED CODE</code>:
|
||||
</p>
|
||||
|
||||
<source>
|
||||
<module name="SuppressionCommentFilter">
|
||||
<property name="offCommentFormat" value="BEGIN GENERATED CODE"/>
|
||||
<property name="onCommentFormat" value="END GENERATED CODE"/>
|
||||
</module>
|
||||
</source>
|
||||
|
||||
<source>
|
||||
//BEGIN GENERATED CODE
|
||||
@Override
|
||||
public boolean equals(Object obj) { ... } // No violation events will be reported
|
||||
|
||||
@Override
|
||||
public int hashCode() { ... } // No violation events will be reported
|
||||
//END GENERATED CODE
|
||||
. . .
|
||||
</source>
|
||||
|
||||
<p>
|
||||
To configure a filter so that <code>// stop constant
|
||||
check</code> and <code>// resume constant check</code> marks
|
||||
legitimate constant names:
|
||||
</p>
|
||||
|
||||
<source>
|
||||
<module name="SuppressionCommentFilter">
|
||||
<property name="offCommentFormat" value="stop constant check"/>
|
||||
<property name="onCommentFormat" value="resume constant check"/>
|
||||
<property name="checkFormat" value="ConstantNameCheck"/>
|
||||
</module>
|
||||
</source>
|
||||
|
||||
<source>
|
||||
//stop constant check
|
||||
public static final int someConstant; // won't warn here
|
||||
//resume constant check
|
||||
public static final int someConstant; // will warn here as constant's name doesn't match the
|
||||
// pattern "^[A-Z][A-Z0-9]*$"
|
||||
</source>
|
||||
|
||||
<p>
|
||||
To configure a filter so that <code>UNUSED OFF:
|
||||
<i>var</i></code> and <code>UNUSED ON: <i>var</i></code> marks a
|
||||
variable or parameter known not to be used by the code by
|
||||
matching the variable name in the message:
|
||||
</p>
|
||||
|
||||
<source>
|
||||
<module name="SuppressionCommentFilter">
|
||||
<property name="offCommentFormat" value="UNUSED OFF\: (\w+)"/>
|
||||
<property name="onCommentFormat" value="UNUSED ON\: (\w+)"/>
|
||||
<property name="checkFormat" value="Unused"/>
|
||||
<property name="messageFormat" value="^Unused \w+ '$1'.$"/>
|
||||
</module>
|
||||
</source>
|
||||
|
||||
<source>
|
||||
private static void foo(int a, int b) // UNUSED OFF: b
|
||||
{
|
||||
System.out.println(a);
|
||||
}
|
||||
|
||||
private static void foo1(int a, int b) // UNUSED ON: b
|
||||
{
|
||||
System.out.println(a);
|
||||
}
|
||||
</source>
|
||||
|
||||
<p>
|
||||
To configure a filter so that name of suppressed check mentioned
|
||||
in comment <code>CSOFF: <i>regexp</i></code>
|
||||
and <code>CSN: <i>regexp</i></code> mark a matching check:
|
||||
</p>
|
||||
|
||||
<source>
|
||||
<module name="SuppressionCommentFilter">
|
||||
<property name="offCommentFormat" value="CSOFF\: ([\w\|]+)"/>
|
||||
<property name="onCommentFormat" value="CSON\: ([\w\|]+)"/>
|
||||
<property name="checkFormat" value="$1"/>
|
||||
</module>
|
||||
</source>
|
||||
|
||||
<source>
|
||||
public static final int lowerCaseConstant; // CSOFF: ConstantNameCheck
|
||||
public static final int lowerCaseConstant1; // CSON: ConstantNameCheck
|
||||
</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:
|
||||
</p>
|
||||
|
||||
<source>
|
||||
<module name="SuppressionCommentFilter">
|
||||
<property name="offCommentFormat" value="CHECKSTYLE_OFF: ALMOST_ALL"/>
|
||||
<property name="onCommentFormat" value="CHECKSTYLE_ON: ALMOST_ALL"/>
|
||||
<property name="checkFormat" value="^((?!(EqualsHashCode)).)*$"/>
|
||||
</module>
|
||||
</source>
|
||||
|
||||
<source>
|
||||
public static final int array []; // CHECKSTYLE_OFF: ALMOST_ALL
|
||||
private String [] strArray;
|
||||
private int array1 []; // CHECKSTYLE_ON: ALMOST_ALL
|
||||
</source>
|
||||
|
||||
<p>
|
||||
To configure a filter to suppress Check's violation message <b>which matches
|
||||
specified message in messageFormat</b> (so suppression will be not only by
|
||||
Check's name, but by message text additionally, as the same Check could report
|
||||
different by message format violations) between a comment
|
||||
containing <code>stop</code> and comment containing <code>resume</code>:
|
||||
</p>
|
||||
|
||||
<source>
|
||||
<module name="SuppressionCommentFilter">
|
||||
<property name="offCommentFormat" value="stop"/>
|
||||
<property name="onCommentFormat" value="resume"/>
|
||||
<property name="checkFormat" value="IllegalTypeCheck"/>
|
||||
<property name="messageFormat" value="^Declaring variables, return values or parameters of type 'GregorianCalendar' is not allowed.$"/>
|
||||
</module>
|
||||
</source>
|
||||
|
||||
<p>
|
||||
Code before filter above is applied with Check's audit events:
|
||||
</p>
|
||||
|
||||
<source>
|
||||
...
|
||||
GregorianCalendar calendar; // Warning here: Declaring variables, return values or parameters of type 'GregorianCalendar' is not allowed.
|
||||
HashSet hashSet; // Warning here: Declaring variables, return values or parameters of type 'HashSet' is not allowed.
|
||||
...
|
||||
</source>
|
||||
|
||||
<p>
|
||||
Code after filter is applied:
|
||||
</p>
|
||||
|
||||
<source>
|
||||
...
|
||||
//stop
|
||||
GregorianCalendar calendar; // No warning here as it is suppressed by filter.
|
||||
HashSet hashSet; // Warning here: Declaring variables, return values or parameters of type 'HashSet' is not allowed.
|
||||
//resume
|
||||
...
|
||||
</source>
|
||||
|
||||
</subsection>
|
||||
|
||||
<subsection name="SuppressWithNearbyCommentFilter">
|
||||
<h4>SuppressWithNearbyCommentFilter</h4>
|
||||
|
||||
<p>
|
||||
Filter <code>SuppressWithNearbyCommentFilter</code> uses
|
||||
individual comments to suppress audit events.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
Rationale: Same as <code>SuppressionCommentFilter</code>.
|
||||
Whereas the SuppressionCommentFilter uses matched pairs of
|
||||
filters to turn on/off comment matching,
|
||||
<code>SuppressWithNearbyCommentFilter</code> uses
|
||||
single comments. This requires fewer lines to mark a region, and
|
||||
may be aesthetically preferable in some contexts.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
Usage: This filter only works in conjunction with a <code>FileContentsHolder</code>, since that check makes
|
||||
the suppression comments in the Java files available. A configuration that includes this filter must
|
||||
configure <code>FileContentsHolder</code> as a
|
||||
child module of <code>TreeWalker</code>.
|
||||
</p>
|
||||
|
||||
<h5>SuppressWithNearbyCommentFilter Properties</h5>
|
||||
<table>
|
||||
<tr>
|
||||
<th>name</th>
|
||||
<th>description</th>
|
||||
<th>type</th>
|
||||
<th>default value</th>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>commentFormat</td>
|
||||
<td>comment pattern to trigger filter to begin suppression</td>
|
||||
<td><a href="property_types.html#regexp">regular expression</a></td>
|
||||
<td><code>SUPPRESS CHECKSTYLE (\w+)</code></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>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>messageFormat</td>
|
||||
<td>message pattern to suppress</td>
|
||||
<td><a href="property_types.html#regexp">regular expression</a></td>
|
||||
<td>none</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>influenceFormat</td>
|
||||
<td>a negative/zero/positive value that defines the number of
|
||||
lines preceding/at/following the suppression comment</td>
|
||||
<td><a href="property_types.html#regexp">regular expression</a></td>
|
||||
<td><code>0</code> (the line containing the comment)</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>checkCPP</td>
|
||||
<td>whether to check C++ style comments (<code>//</code>)</td>
|
||||
<td><a href="property_types.html#boolean">boolean</a></td>
|
||||
<td><code>true</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>checkC</td>
|
||||
<td>whether to check C style comments (<code>/* ... */</code>)</td>
|
||||
<td><a href="property_types.html#boolean">boolean</a></td>
|
||||
<td><code>true</code></td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
<h5>Examples</h5>
|
||||
<p>
|
||||
To configure the check that makes comments available to the filter:
|
||||
</p>
|
||||
|
||||
<source>
|
||||
<module name="TreeWalker">
|
||||
...
|
||||
<module name="FileContentsHolder"/>
|
||||
...
|
||||
</module>
|
||||
</source>
|
||||
|
||||
<p>
|
||||
To configure a filter to suppress audit events for <i>check</i>
|
||||
on any line with a comment <code>SUPPRESS CHECKSTYLE <i>check</i></code>:
|
||||
</p>
|
||||
|
||||
<source>
|
||||
<module name="SuppressWithNearbyCommentFilter"/>
|
||||
</source>
|
||||
|
||||
<source>
|
||||
private int [] array; // SUPPRESS CHECKSTYLE
|
||||
</source>
|
||||
|
||||
<p>
|
||||
To configure a filter to suppress all audit events on any line
|
||||
containing the comment <code>CHECKSTYLE IGNORE THIS LINE</code>:
|
||||
</p>
|
||||
|
||||
<source>
|
||||
<module name="SuppressWithNearbyCommentFilter">
|
||||
<property name="commentFormat" value="CHECKSTYLE IGNORE THIS LINE"/>
|
||||
<property name="checkFormat" value=".*"/>
|
||||
<property name="influenceFormat" value="0"/>
|
||||
</module>
|
||||
</source>
|
||||
|
||||
<source>
|
||||
public static final int lowerCaseConstant; // CHECKSTYLE IGNORE THIS LINE
|
||||
</source>
|
||||
|
||||
<p>
|
||||
To configure a filter so that
|
||||
<code>// OK to catch (Throwable|Exception|RuntimeException) here</code>
|
||||
permits the current and previous line to avoid generating an IllegalCatch
|
||||
audit event:
|
||||
</p>
|
||||
|
||||
<source>
|
||||
<module name="SuppressWithNearbyCommentFilter">
|
||||
<property name="commentFormat" value="OK to catch (\w+) here"/>
|
||||
<property name="checkFormat" value="IllegalCatchCheck"/>
|
||||
<property name="messageFormat" value="$1"/>
|
||||
<property name="influenceFormat" value="-1"/>
|
||||
</module>
|
||||
</source>
|
||||
|
||||
<source>
|
||||
. . .
|
||||
catch (RuntimeException re) {
|
||||
// OK to catch RuntimeException here
|
||||
}
|
||||
catch (Throwable th) { ... }
|
||||
. . .
|
||||
</source>
|
||||
|
||||
<p>
|
||||
To configure a filter so that <code>CHECKSTYLE IGNORE <i>check</i> FOR NEXT <i>var</i> LINES</code>
|
||||
avoids triggering any audits for the given check for the current line and the next <i>var</i> lines
|
||||
(for a total of <i>var</i>+1 lines):
|
||||
</p>
|
||||
|
||||
<source>
|
||||
<module name="SuppressWithNearbyCommentFilter">
|
||||
<property name="commentFormat" value="CHECKSTYLE IGNORE (\w+) FOR NEXT (\d+) LINES"/>
|
||||
<property name="checkFormat" value="$1"/>
|
||||
<property name="influenceFormat" value="$2"/>
|
||||
</module>
|
||||
</source>
|
||||
|
||||
<source>
|
||||
public static final int lowerCaseConstant; // CHECKSTYLE IGNORE ConstantNameCheck FOR NEXT 3 LINES
|
||||
public static final int lowerCaseConstant1;
|
||||
public static final int lowerCaseConstant2;
|
||||
public static final int lowerCaseConstant3;
|
||||
public static final int lowerCaseConstant4; // will warn here
|
||||
</source>
|
||||
|
||||
<p>
|
||||
To configure a filter to avoid any audits on code like:
|
||||
</p>
|
||||
|
||||
<source>
|
||||
<module name="SuppressWithNearbyCommentFilter">
|
||||
<property name="commentFormat" value="ALLOW (\\w+) ON PREVIOUS LINE"/>
|
||||
<property name="checkFormat" value="$1"/>
|
||||
<property name="influenceFormat" value="-1"/>
|
||||
</module>
|
||||
</source>
|
||||
|
||||
<source>
|
||||
private int D2;
|
||||
// ALLOW MemberName ON PREVIOUS LINE
|
||||
. . .
|
||||
</source>
|
||||
|
||||
<p>
|
||||
To configure a filter to allow suppress one or more Checks(separated by "|")
|
||||
and demand comment no less than 14 symbols:
|
||||
</p>
|
||||
|
||||
<source>
|
||||
<module name="SuppressWithNearbyCommentFilter">
|
||||
<property name="commentFormat" value="@cs.suppress \[(\w(\|\w)*)\] \w[-\.'`,:;\w ]{14,}"/>
|
||||
<property name="checkFormat" value="$1"/>
|
||||
<property name="influenceFormat" value="1"/>
|
||||
</module>
|
||||
</source>
|
||||
|
||||
<source>
|
||||
public static final int [] array; // @cs.suppress ConstantName | NoWhitespaceAfter
|
||||
</source>
|
||||
|
||||
</subsection>
|
||||
|
||||
<subsection name="SuppressWarningsFilter">
|
||||
<h4>SuppressWarningsFilter</h4>
|
||||
<p>
|
||||
Filter <code>SuppressWarningsFilter</code> uses annotations to
|
||||
suppress audit events.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
Rationale: Same as for
|
||||
<code>SuppressionCommentFilter</code>. In the contrary to it
|
||||
here, comments are not used comments but the builtin syntax of
|
||||
<code>@SuppressWarnings</code>. This can be perceived as a
|
||||
more elegant solution than using comments. Also this approach
|
||||
maybe supported by various IDE.
|
||||
</p>
|
||||
<p>
|
||||
Usage: This filter only works in conjunction with a
|
||||
<a href="config_annotation.html#SuppressWarningsHolder">SuppressWarningsHolder</a>, since that check finds
|
||||
the annotations in the Java files and makes them available for
|
||||
the filter. Because of that, a configuration that includes
|
||||
this filter must also include
|
||||
<code>SuppressWarningsHolder</code> as a child module of the
|
||||
<code>TreeWalker</code>. Name of check in annotation should
|
||||
be written in lower case with any dotted prefix or "Check" suffix removed.
|
||||
</p>
|
||||
|
||||
<h5>SuppressWarningsFilter Properties</h5>
|
||||
<p>This filter does not expose any properties</p>
|
||||
|
||||
<h5>Examples</h5>
|
||||
<p>
|
||||
To configure the check that makes tha annotations available to
|
||||
the filter.
|
||||
</p>
|
||||
<source>
|
||||
<module name="TreeWalker">
|
||||
...
|
||||
<module name="SuppressWarningsHolder" />
|
||||
...
|
||||
</module>
|
||||
</source>
|
||||
|
||||
<p>To configure filter to suppress audit events for annotations add:</p>
|
||||
<source>
|
||||
<module name="SuppressWarningsFilter" />
|
||||
</source>
|
||||
|
||||
<source>
|
||||
@SuppressWarnings({"membername"})
|
||||
private int J; // should NOT fail MemberNameCheck
|
||||
|
||||
@SuppressWarnings({"membername"})
|
||||
@SuppressWarnings({"nowhitespaceafter"})
|
||||
private int [] ARRAY; // should NOT fail MemberNameCheck and NoWhitespaceAfterCheck
|
||||
</source>
|
||||
</subsection>
|
||||
|
||||
</section>
|
||||
|
||||
<section name="AuditListeners">
|
||||
|
|
@ -1539,7 +757,7 @@ private int [] ARRAY; // should NOT fail MemberNameCheck and NoWhitespaceAfterCh
|
|||
|
||||
</section>
|
||||
|
||||
<section name="XML Details">
|
||||
<section name="XML Structure">
|
||||
|
||||
<h4>Configuration XML Document</h4>
|
||||
<p>
|
||||
|
|
|
|||
|
|
@ -0,0 +1,756 @@
|
|||
<?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>Filters</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="SeverityMatchFilter">
|
||||
<subsection name="Description">
|
||||
<p>
|
||||
Filter <code>SeverityMatchFilter</code> decides
|
||||
audit events according to the <a href="#Severity">severity
|
||||
level</a> of the event.
|
||||
</p>
|
||||
</subsection>
|
||||
<subsection name="Properties">
|
||||
<table>
|
||||
<tr>
|
||||
<th>name</th>
|
||||
<th>description</th>
|
||||
<th>type</th>
|
||||
<th>default value</th>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>severity</td>
|
||||
<td>the severity level of this filter</td>
|
||||
<td><a href="property_types.html#severity">severity</a></td>
|
||||
<td><code>error</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>acceptOnMatch</td>
|
||||
<td>
|
||||
If acceptOnMatch is <code>true</code>, then
|
||||
the filter accepts an audit event if and only if there is
|
||||
a match between the event's severity level and property
|
||||
severity. If acceptOnMatch
|
||||
is <code>false</code>, then the filter
|
||||
accepts an audit event if and only if there is not a match
|
||||
between the event's severity level and property severity.
|
||||
</td>
|
||||
<td><a href="property_types.html#boolean">boolean</a></td>
|
||||
<td><code>true</code></td>
|
||||
</tr>
|
||||
</table>
|
||||
</subsection>
|
||||
<subsection name="Example of Usage">
|
||||
<p>
|
||||
For example, the following configuration fragment directs the
|
||||
Checker to not report audit events with severity
|
||||
level <code>info</code>:
|
||||
</p>
|
||||
<source>
|
||||
<module name="SeverityMatchFilter">
|
||||
<property name="severity" value="info"/>
|
||||
<property name="acceptOnMatch" value="false"/>
|
||||
</module>
|
||||
</source>
|
||||
</subsection>
|
||||
<subsection name="Package">
|
||||
<p> com.puppycrawl.tools.checkstyle.checks.filters </p>
|
||||
</subsection>
|
||||
</section>
|
||||
|
||||
<section name="SuppressionFilter">
|
||||
<subsection name="Description">
|
||||
<p>
|
||||
Filter <code>SuppressionFilter</code> rejects
|
||||
audit events for Check errors according to
|
||||
a <a href="#XML_Details"><em>suppressions XML
|
||||
document</em></a> in a file. If there is no configured
|
||||
suppressions file, the Filter accepts all audit events.
|
||||
</p>
|
||||
</subsection>
|
||||
<subsection name="Properties">
|
||||
<table>
|
||||
<tr>
|
||||
<th>name</th>
|
||||
<th>description</th>
|
||||
<th>type</th>
|
||||
<th>default value</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>
|
||||
</tr>
|
||||
</table>
|
||||
</subsection>
|
||||
<subsection name="Examples">
|
||||
<p>
|
||||
For example, the following configuration fragment directs the
|
||||
Checker to use a <code>SuppressionFilter</code>
|
||||
with suppressions
|
||||
file <code>docs/suppressions.xml</code>:
|
||||
</p>
|
||||
<source>
|
||||
<module name="SuppressionFilter">
|
||||
<property name="file" value="docs/suppressions.xml"/>
|
||||
</module>
|
||||
</source>
|
||||
<p>
|
||||
A <a href="#XML_Details"><em>suppressions XML
|
||||
document</em></a> contains a set
|
||||
of <code>suppress</code> elements, where
|
||||
each <code>suppress</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 mandatory.
|
||||
</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.
|
||||
</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.
|
||||
</li>
|
||||
<li>
|
||||
<code>lines</code> - a comma-separated list of
|
||||
values, where each value is
|
||||
an <a href="property_types.html#integer">integer</a> or a
|
||||
range of integers denoted by integer-integer. It is optional.
|
||||
</li>
|
||||
<li>
|
||||
<code>columns</code> - a comma-separated list of
|
||||
values, where each value is
|
||||
an <a href="property_types.html#integer">integer</a> or a
|
||||
range of integers denoted by integer-integer. It is optional.
|
||||
</li>
|
||||
</ul>
|
||||
<p>
|
||||
Each audit event is checked against
|
||||
each <code>suppress</code> element. It is
|
||||
suppressed if all specified attributes match against the audit
|
||||
event.
|
||||
</p>
|
||||
</subsection>
|
||||
<subsection name="Example of Usage">
|
||||
<p>
|
||||
You can download template of empty suppression filter
|
||||
<a href="files/suppressions_none.xml">here</a>.
|
||||
</p>
|
||||
<p>
|
||||
The following suppressions XML document directs
|
||||
a <code>SuppressionFilter</code> to
|
||||
reject <code>JavadocStyleCheck</code> errors for
|
||||
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>:
|
||||
</p>
|
||||
<source>
|
||||
<?xml version="1.0"?>
|
||||
|
||||
<!DOCTYPE suppressions PUBLIC
|
||||
"-//Puppy Crawl//DTD Suppressions 1.1//EN"
|
||||
"http://www.puppycrawl.com/dtds/suppressions_1_1.dtd">
|
||||
|
||||
<suppressions>
|
||||
<suppress checks="JavadocStyleCheck"
|
||||
files="AbstractComplexityCheck.java"
|
||||
lines="82,108-122"/>
|
||||
<suppress checks="MagicNumberCheck"
|
||||
files="JavadocStyleCheck.java"
|
||||
lines="221"/>
|
||||
</suppressions>
|
||||
</source>
|
||||
<p>
|
||||
As another example to suppress Check by module id:
|
||||
</p>
|
||||
<source>
|
||||
<module name="DescendantToken">
|
||||
<property name="id" value="stringEqual"/>
|
||||
<property name="tokens" value="EQUAL,NOT_EQUAL"/>
|
||||
<property name="limitedTokens" value="STRING_LITERAL"/>
|
||||
<property name="maximumNumber" value="0"/>
|
||||
<property name="maximumDepth" value="1"/>
|
||||
</module>
|
||||
|
||||
<module name="DescendantToken">
|
||||
<property name="id" value="switchNoDefault"/>
|
||||
<property name="tokens" value="LITERAL_SWITCH"/>
|
||||
<property name="maximumDepth" value="2"/>
|
||||
<property name="limitedTokens" value="LITERAL_DEFAULT"/>
|
||||
<property name="minimumNumber" value="1"/>
|
||||
</module>
|
||||
</source>
|
||||
<p>
|
||||
Then the following can be used to suppress only the first
|
||||
check and not the second by using
|
||||
the <code>id</code> attribute:
|
||||
</p>
|
||||
<source>
|
||||
<suppress id="stringEqual" files="SomeTestCode.java"/>
|
||||
</source>
|
||||
<p>
|
||||
Suppress checks for hidden files and folders:
|
||||
</p>
|
||||
<source>
|
||||
<suppress files="[/\\]\..+" checks=".*"/>
|
||||
</source>
|
||||
<p>
|
||||
Suppress checks for Maven-generated code:
|
||||
</p>
|
||||
<source>
|
||||
<suppress files="[/\\]target[/\\]" checks=".*"/>
|
||||
</source>
|
||||
<p>
|
||||
Suppress checks for archives, classes and other binary files:
|
||||
</p>
|
||||
<source>
|
||||
<suppress files=".+\.(?:jar|zip|war|class|tar|bin)$" checks=".*"/>
|
||||
</source>
|
||||
<p>
|
||||
Suppress checks for image files:
|
||||
</p>
|
||||
<source>
|
||||
<suppress files=".+\.(?:png|gif|jpg|jpeg)$" checks=".*"/>
|
||||
</source>
|
||||
<p>
|
||||
Suppress checks for non-java files:
|
||||
</p>
|
||||
<source>
|
||||
<suppress files=".+\.(?:txt|xml|csv|sh|thrift|html|sql|eot|ttf|woff|css|png)$" checks=".*"/>
|
||||
</source>
|
||||
<p>
|
||||
Suppress all checks in generated sources:
|
||||
</p>
|
||||
<source>
|
||||
<suppress checks=".*" files="com[\\/]mycompany[\\/]app[\\/]gen[\\/]"/>
|
||||
</source>
|
||||
<p>
|
||||
Suppress FileLength check on integration tests in certain folder:
|
||||
</p>
|
||||
<source>
|
||||
<suppress checks="FileLength" files="com[\\/]mycompany[\\/]app[\\/].*IT.java"/>
|
||||
</source>
|
||||
</subsection>
|
||||
<subsection name="Package">
|
||||
<p> com.puppycrawl.tools.checkstyle.checks.filters </p>
|
||||
</subsection>
|
||||
</section>
|
||||
|
||||
<section name="SuppressionCommentFilter">
|
||||
<subsection name="Description">
|
||||
<p>
|
||||
Filter <code>SuppressionCommentFilter</code> uses
|
||||
pairs of comments to suppress audit events.
|
||||
</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>
|
||||
Usage: This filter only works in conjunction with a <code>FileContentsHolder</code>, since that check makes
|
||||
the suppression comments in the Java files available. A configuration that includes this filter must
|
||||
configure <code>FileContentsHolder</code> as a
|
||||
child module of <code>TreeWalker</code>.
|
||||
</p>
|
||||
</subsection>
|
||||
<subsection name="Properties">
|
||||
<table>
|
||||
<tr>
|
||||
<th>name</th>
|
||||
<th>description</th>
|
||||
<th>type</th>
|
||||
<th>default value</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>
|
||||
</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>
|
||||
</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> (all checks)</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>messageFormat</td>
|
||||
<td>message pattern to suppress</td>
|
||||
<td><a href="property_types.html#regexp">regular expression</a></td>
|
||||
<td>none</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>checkCPP</td>
|
||||
<td>whether to check C++ style comments (<code>//</code>)</td>
|
||||
<td><a href="property_types.html#boolean">boolean</a></td>
|
||||
<td><code>true</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>checkC</td>
|
||||
<td>whether to check C style comments (<code>/* ... */</code>)</td>
|
||||
<td><a href="property_types.html#boolean">boolean</a></td>
|
||||
<td><code>true</code></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>
|
||||
Make sure that comments are available to the filter by enabling FileContentsHolder:
|
||||
</p>
|
||||
<source>
|
||||
<module name="TreeWalker">
|
||||
...
|
||||
<module name="FileContentsHolder"/>
|
||||
...
|
||||
</module>
|
||||
</source>
|
||||
<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="SuppressionCommentFilter"/>
|
||||
...
|
||||
</module>
|
||||
</source>
|
||||
<p>
|
||||
To configure a filter to suppress audit events between a comment
|
||||
containing line <code>BEGIN GENERATED CODE</code> and a comment
|
||||
containing line <code>END GENERATED CODE</code>:
|
||||
</p>
|
||||
<source>
|
||||
<module name="SuppressionCommentFilter">
|
||||
<property name="offCommentFormat" value="BEGIN GENERATED CODE"/>
|
||||
<property name="onCommentFormat" value="END GENERATED CODE"/>
|
||||
</module>
|
||||
</source>
|
||||
<source>
|
||||
//BEGIN GENERATED CODE
|
||||
@Override
|
||||
public boolean equals(Object obj) { ... } // No violation events will be reported
|
||||
|
||||
@Override
|
||||
public int hashCode() { ... } // No violation events will be reported
|
||||
//END GENERATED CODE
|
||||
. . .
|
||||
</source>
|
||||
<p>
|
||||
To configure a filter so that <code>// stop constant
|
||||
check</code> and <code>// resume constant check</code> marks
|
||||
legitimate constant names:
|
||||
</p>
|
||||
<source>
|
||||
<module name="SuppressionCommentFilter">
|
||||
<property name="offCommentFormat" value="stop constant check"/>
|
||||
<property name="onCommentFormat" value="resume constant check"/>
|
||||
<property name="checkFormat" value="ConstantNameCheck"/>
|
||||
</module>
|
||||
</source>
|
||||
<source>
|
||||
//stop constant check
|
||||
public static final int someConstant; // won't warn here
|
||||
//resume constant check
|
||||
public static final int someConstant; // will warn here as constant's name doesn't match the
|
||||
// pattern "^[A-Z][A-Z0-9]*$"
|
||||
</source>
|
||||
<p>
|
||||
To configure a filter so that <code>UNUSED OFF:
|
||||
<i>var</i></code> and <code>UNUSED ON: <i>var</i></code> marks a
|
||||
variable or parameter known not to be used by the code by
|
||||
matching the variable name in the message:
|
||||
</p>
|
||||
<source>
|
||||
<module name="SuppressionCommentFilter">
|
||||
<property name="offCommentFormat" value="UNUSED OFF\: (\w+)"/>
|
||||
<property name="onCommentFormat" value="UNUSED ON\: (\w+)"/>
|
||||
<property name="checkFormat" value="Unused"/>
|
||||
<property name="messageFormat" value="^Unused \w+ '$1'.$"/>
|
||||
</module>
|
||||
</source>
|
||||
<source>
|
||||
private static void foo(int a, int b) // UNUSED OFF: b
|
||||
{
|
||||
System.out.println(a);
|
||||
}
|
||||
|
||||
private static void foo1(int a, int b) // UNUSED ON: b
|
||||
{
|
||||
System.out.println(a);
|
||||
}
|
||||
</source>
|
||||
<p>
|
||||
To configure a filter so that name of suppressed check mentioned
|
||||
in comment <code>CSOFF: <i>regexp</i></code>
|
||||
and <code>CSN: <i>regexp</i></code> mark a matching check:
|
||||
</p>
|
||||
<source>
|
||||
<module name="SuppressionCommentFilter">
|
||||
<property name="offCommentFormat" value="CSOFF\: ([\w\|]+)"/>
|
||||
<property name="onCommentFormat" value="CSON\: ([\w\|]+)"/>
|
||||
<property name="checkFormat" value="$1"/>
|
||||
</module>
|
||||
</source>
|
||||
<source>
|
||||
public static final int lowerCaseConstant; // CSOFF: ConstantNameCheck
|
||||
public static final int lowerCaseConstant1; // CSON: ConstantNameCheck
|
||||
</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:
|
||||
</p>
|
||||
<source>
|
||||
<module name="SuppressionCommentFilter">
|
||||
<property name="offCommentFormat" value="CHECKSTYLE_OFF: ALMOST_ALL"/>
|
||||
<property name="onCommentFormat" value="CHECKSTYLE_ON: ALMOST_ALL"/>
|
||||
<property name="checkFormat" value="^((?!(EqualsHashCode)).)*$"/>
|
||||
</module>
|
||||
</source>
|
||||
<source>
|
||||
public static final int array []; // CHECKSTYLE_OFF: ALMOST_ALL
|
||||
private String [] strArray;
|
||||
private int array1 []; // CHECKSTYLE_ON: ALMOST_ALL
|
||||
</source>
|
||||
<p>
|
||||
To configure a filter to suppress Check's violation message <b>which matches
|
||||
specified message in messageFormat</b> (so suppression will be not only by
|
||||
Check's name, but by message text additionally, as the same Check could report
|
||||
different by message format violations) between a comment
|
||||
containing <code>stop</code> and comment containing <code>resume</code>:
|
||||
</p>
|
||||
<source>
|
||||
<module name="SuppressionCommentFilter">
|
||||
<property name="offCommentFormat" value="stop"/>
|
||||
<property name="onCommentFormat" value="resume"/>
|
||||
<property name="checkFormat" value="IllegalTypeCheck"/>
|
||||
<property name="messageFormat" value="^Declaring variables, return values or parameters of type 'GregorianCalendar' is not allowed.$"/>
|
||||
</module>
|
||||
</source>
|
||||
<p>
|
||||
Code before filter above is applied with Check's audit events:
|
||||
</p>
|
||||
<source>
|
||||
...
|
||||
GregorianCalendar calendar; // Warning here: Declaring variables, return values or parameters of type 'GregorianCalendar' is not allowed.
|
||||
HashSet hashSet; // Warning here: Declaring variables, return values or parameters of type 'HashSet' is not allowed.
|
||||
...
|
||||
</source>
|
||||
<p>
|
||||
Code after filter is applied:
|
||||
</p>
|
||||
<source>
|
||||
...
|
||||
//stop
|
||||
GregorianCalendar calendar; // No warning here as it is suppressed by filter.
|
||||
HashSet hashSet; // Warning here: Declaring variables, return values or parameters of type 'HashSet' is not allowed.
|
||||
//resume
|
||||
...
|
||||
</source>
|
||||
</subsection>
|
||||
<subsection name="Package">
|
||||
<p> com.puppycrawl.tools.checkstyle.checks.filters </p>
|
||||
</subsection>
|
||||
</section>
|
||||
|
||||
<section name="SuppressWithNearbyCommentFilter">
|
||||
<subsection name="Description">
|
||||
<p>
|
||||
Filter <code>SuppressWithNearbyCommentFilter</code> uses
|
||||
individual comments to suppress audit events.
|
||||
</p>
|
||||
<p>
|
||||
Rationale: Same as <code>SuppressionCommentFilter</code>.
|
||||
Whereas the SuppressionCommentFilter uses matched pairs of
|
||||
filters to turn on/off comment matching,
|
||||
<code>SuppressWithNearbyCommentFilter</code> uses
|
||||
single comments. This requires fewer lines to mark a region, and
|
||||
may be aesthetically preferable in some contexts.
|
||||
</p>
|
||||
<p>
|
||||
Usage: This filter only works in conjunction with a <code>FileContentsHolder</code>, since that check makes
|
||||
the suppression comments in the Java files available. A configuration that includes this filter must
|
||||
configure <code>FileContentsHolder</code> as a
|
||||
child module of <code>TreeWalker</code>.
|
||||
</p>
|
||||
</subsection>
|
||||
<subsection name="Properties">
|
||||
<table>
|
||||
<tr>
|
||||
<th>name</th>
|
||||
<th>description</th>
|
||||
<th>type</th>
|
||||
<th>default value</th>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>commentFormat</td>
|
||||
<td>comment pattern to trigger filter to begin suppression</td>
|
||||
<td><a href="property_types.html#regexp">regular expression</a></td>
|
||||
<td><code>SUPPRESS CHECKSTYLE (\w+)</code></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>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>messageFormat</td>
|
||||
<td>message pattern to suppress</td>
|
||||
<td><a href="property_types.html#regexp">regular expression</a></td>
|
||||
<td>none</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>influenceFormat</td>
|
||||
<td>a negative/zero/positive value that defines the number of
|
||||
lines preceding/at/following the suppression comment</td>
|
||||
<td><a href="property_types.html#regexp">regular expression</a></td>
|
||||
<td><code>0</code> (the line containing the comment)</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>checkCPP</td>
|
||||
<td>whether to check C++ style comments (<code>//</code>)</td>
|
||||
<td><a href="property_types.html#boolean">boolean</a></td>
|
||||
<td><code>true</code></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>checkC</td>
|
||||
<td>whether to check C style comments (<code>/* ... */</code>)</td>
|
||||
<td><a href="property_types.html#boolean">boolean</a></td>
|
||||
<td><code>true</code></td>
|
||||
</tr>
|
||||
</table>
|
||||
</subsection>
|
||||
<subsection name="Example of Usage">
|
||||
<p>
|
||||
To configure the check that makes comments available to the filter:
|
||||
</p>
|
||||
<source>
|
||||
<module name="TreeWalker">
|
||||
...
|
||||
<module name="FileContentsHolder"/>
|
||||
...
|
||||
</module>
|
||||
</source>
|
||||
<p>
|
||||
To configure a filter to suppress audit events for <i>check</i>
|
||||
on any line with a comment <code>SUPPRESS CHECKSTYLE <i>check</i></code>:
|
||||
</p>
|
||||
<source>
|
||||
<module name="SuppressWithNearbyCommentFilter"/>
|
||||
</source>
|
||||
<source>
|
||||
private int [] array; // SUPPRESS CHECKSTYLE
|
||||
</source>
|
||||
<p>
|
||||
To configure a filter to suppress all audit events on any line
|
||||
containing the comment <code>CHECKSTYLE IGNORE THIS LINE</code>:
|
||||
</p>
|
||||
<source>
|
||||
<module name="SuppressWithNearbyCommentFilter">
|
||||
<property name="commentFormat" value="CHECKSTYLE IGNORE THIS LINE"/>
|
||||
<property name="checkFormat" value=".*"/>
|
||||
<property name="influenceFormat" value="0"/>
|
||||
</module>
|
||||
</source>
|
||||
<source>
|
||||
public static final int lowerCaseConstant; // CHECKSTYLE IGNORE THIS LINE
|
||||
</source>
|
||||
<p>
|
||||
To configure a filter so that
|
||||
<code>// OK to catch (Throwable|Exception|RuntimeException) here</code>
|
||||
permits the current and previous line to avoid generating an IllegalCatch
|
||||
audit event:
|
||||
</p>
|
||||
<source>
|
||||
<module name="SuppressWithNearbyCommentFilter">
|
||||
<property name="commentFormat" value="OK to catch (\w+) here"/>
|
||||
<property name="checkFormat" value="IllegalCatchCheck"/>
|
||||
<property name="messageFormat" value="$1"/>
|
||||
<property name="influenceFormat" value="-1"/>
|
||||
</module>
|
||||
</source>
|
||||
<source>
|
||||
. . .
|
||||
catch (RuntimeException re) {
|
||||
// OK to catch RuntimeException here
|
||||
}
|
||||
catch (Throwable th) { ... }
|
||||
. . .
|
||||
</source>
|
||||
<p>
|
||||
To configure a filter so that <code>CHECKSTYLE IGNORE <i>check</i> FOR NEXT <i>var</i> LINES</code>
|
||||
avoids triggering any audits for the given check for the current line and the next <i>var</i> lines
|
||||
(for a total of <i>var</i>+1 lines):
|
||||
</p>
|
||||
<source>
|
||||
<module name="SuppressWithNearbyCommentFilter">
|
||||
<property name="commentFormat" value="CHECKSTYLE IGNORE (\w+) FOR NEXT (\d+) LINES"/>
|
||||
<property name="checkFormat" value="$1"/>
|
||||
<property name="influenceFormat" value="$2"/>
|
||||
</module>
|
||||
</source>
|
||||
<source>
|
||||
public static final int lowerCaseConstant; // CHECKSTYLE IGNORE ConstantNameCheck FOR NEXT 3 LINES
|
||||
public static final int lowerCaseConstant1;
|
||||
public static final int lowerCaseConstant2;
|
||||
public static final int lowerCaseConstant3;
|
||||
public static final int lowerCaseConstant4; // will warn here
|
||||
</source>
|
||||
<p>
|
||||
To configure a filter to avoid any audits on code like:
|
||||
</p>
|
||||
<source>
|
||||
<module name="SuppressWithNearbyCommentFilter">
|
||||
<property name="commentFormat" value="ALLOW (\\w+) ON PREVIOUS LINE"/>
|
||||
<property name="checkFormat" value="$1"/>
|
||||
<property name="influenceFormat" value="-1"/>
|
||||
</module>
|
||||
</source>
|
||||
<source>
|
||||
private int D2;
|
||||
// ALLOW MemberName ON PREVIOUS LINE
|
||||
. . .
|
||||
</source>
|
||||
<p>
|
||||
To configure a filter to allow suppress one or more Checks(separated by "|")
|
||||
and demand comment no less than 14 symbols:
|
||||
</p>
|
||||
<source>
|
||||
<module name="SuppressWithNearbyCommentFilter">
|
||||
<property name="commentFormat" value="@cs.suppress \[(\w(\|\w)*)\] \w[-\.'`,:;\w ]{14,}"/>
|
||||
<property name="checkFormat" value="$1"/>
|
||||
<property name="influenceFormat" value="1"/>
|
||||
</module>
|
||||
</source>
|
||||
<source>
|
||||
public static final int [] array; // @cs.suppress ConstantName | NoWhitespaceAfter
|
||||
</source>
|
||||
</subsection>
|
||||
<subsection name="Package">
|
||||
<p> com.puppycrawl.tools.checkstyle.checks.filters </p>
|
||||
</subsection>
|
||||
</section>
|
||||
|
||||
<section name="SuppressWarningsFilter">
|
||||
<subsection name="Description">
|
||||
<p>
|
||||
Filter <code>SuppressWarningsFilter</code> uses annotations to
|
||||
suppress audit events.
|
||||
</p>
|
||||
<p>
|
||||
Rationale: Same as for
|
||||
<code>SuppressionCommentFilter</code>. In the contrary to it
|
||||
here, comments are not used comments but the builtin syntax of
|
||||
<code>@SuppressWarnings</code>. This can be perceived as a
|
||||
more elegant solution than using comments. Also this approach
|
||||
maybe supported by various IDE.
|
||||
</p>
|
||||
<p>
|
||||
Usage: This filter only works in conjunction with a
|
||||
<a href="config_annotation.html#SuppressWarningsHolder">SuppressWarningsHolder</a>, since that check finds
|
||||
the annotations in the Java files and makes them available for
|
||||
the filter. Because of that, a configuration that includes
|
||||
this filter must also include
|
||||
<code>SuppressWarningsHolder</code> as a child module of the
|
||||
<code>TreeWalker</code>. Name of check in annotation should
|
||||
be written in lower case with any dotted prefix or "Check" suffix removed.
|
||||
</p>
|
||||
</subsection>
|
||||
<subsection name="Properties">
|
||||
<p>This filter does not expose any properties</p>
|
||||
</subsection>
|
||||
<subsection name="Example of Usage">
|
||||
<p>
|
||||
To configure the check that makes tha annotations available to
|
||||
the filter.
|
||||
</p>
|
||||
<source>
|
||||
<module name="TreeWalker">
|
||||
...
|
||||
<module name="SuppressWarningsHolder" />
|
||||
...
|
||||
</module>
|
||||
</source>
|
||||
<p>To configure filter to suppress audit events for annotations add:</p>
|
||||
<source>
|
||||
<module name="SuppressWarningsFilter" />
|
||||
</source>
|
||||
<source>
|
||||
@SuppressWarnings({"membername"})
|
||||
private int J; // should NOT fail MemberNameCheck
|
||||
|
||||
@SuppressWarnings({"membername"})
|
||||
@SuppressWarnings({"nowhitespaceafter"})
|
||||
private int [] ARRAY; // should NOT fail MemberNameCheck and NoWhitespaceAfterCheck
|
||||
</source>
|
||||
</subsection>
|
||||
<subsection name="Package">
|
||||
<p> com.puppycrawl.tools.checkstyle.checks.filters </p>
|
||||
</subsection>
|
||||
</section>
|
||||
</body>
|
||||
</document>
|
||||
|
|
@ -21,28 +21,29 @@
|
|||
</macro>
|
||||
</section>
|
||||
|
||||
<section name="Property Types">
|
||||
<section name="Overview">
|
||||
<p>
|
||||
Checkstyle is configured using properties, which are string
|
||||
representations. This document describes how these string
|
||||
representations are mapped to typed properties.
|
||||
</p>
|
||||
</section>
|
||||
|
||||
<subsection name="integer">
|
||||
<section name="integer">
|
||||
<p>
|
||||
This property represents an integer. The string representation is
|
||||
parsed using the <code>java.lang.Integer</code> class.
|
||||
</p>
|
||||
</subsection>
|
||||
</section>
|
||||
|
||||
<subsection name="string">
|
||||
<section name="string">
|
||||
<p>
|
||||
This property represents a string. The literal string representation
|
||||
is used.
|
||||
</p>
|
||||
</subsection>
|
||||
</section>
|
||||
|
||||
<subsection name="boolean">
|
||||
<section name="boolean">
|
||||
<p>
|
||||
This property represents a boolean. The default value is <code>false</code>. The following string representations will
|
||||
map to <code>true</code>:
|
||||
|
|
@ -55,9 +56,9 @@
|
|||
</ul>
|
||||
|
||||
<p>Anything else will map to <code>false</code>.</p>
|
||||
</subsection>
|
||||
</section>
|
||||
|
||||
<subsection name="stringSet">
|
||||
<section name="stringSet">
|
||||
<p>
|
||||
This property represents a set of strings. The string representation
|
||||
is parsed as a set of comma (',') separated strings.
|
||||
|
|
@ -75,9 +76,9 @@
|
|||
<property name="tokens" value="DIV_ASSIGN"/>
|
||||
<property name="tokens" value="PLUS_ASSIGN"/>
|
||||
</source>
|
||||
</subsection>
|
||||
</section>
|
||||
|
||||
<subsection name="intSet">
|
||||
<section name="intSet">
|
||||
<p>
|
||||
This property represents a set of integers. The string representation
|
||||
is parsed as a set of comma (',') separated integers that are parsed
|
||||
|
|
@ -96,18 +97,18 @@
|
|||
<property name="tokens" value="42"/>
|
||||
<property name="tokens" value="666"/>
|
||||
</source>
|
||||
</subsection>
|
||||
</section>
|
||||
|
||||
<subsection name="regexp">
|
||||
<section name="regexp">
|
||||
<p>
|
||||
This property represents a regular expression. The string
|
||||
representation is parsed using <a
|
||||
href="http://docs.oracle.com/javase/7/docs/api/index.html?java/util/regex/package-summary.html">java.util.regex
|
||||
package</a>.
|
||||
</p>
|
||||
</subsection>
|
||||
</section>
|
||||
|
||||
<subsection name="parenPad">
|
||||
<section name="parenPad">
|
||||
<p>
|
||||
This property represents the policy for padding with white space. The
|
||||
following table describes the valid options:
|
||||
|
|
@ -132,9 +133,9 @@
|
|||
</td>
|
||||
</tr>
|
||||
</table>
|
||||
</subsection>
|
||||
</section>
|
||||
|
||||
<subsection name="wrapOp">
|
||||
<section name="wrapOp">
|
||||
<p>
|
||||
This property represents the policy for wrapping lines.
|
||||
The following table describes the valid options:
|
||||
|
|
@ -166,9 +167,9 @@
|
|||
</td>
|
||||
</tr>
|
||||
</table>
|
||||
</subsection>
|
||||
</section>
|
||||
|
||||
<subsection name="block">
|
||||
<section name="block">
|
||||
<p>
|
||||
This property represents the policy for checking block statements. The
|
||||
following table describes the valid options:
|
||||
|
|
@ -202,9 +203,9 @@
|
|||
</td>
|
||||
</tr>
|
||||
</table>
|
||||
</subsection>
|
||||
</section>
|
||||
|
||||
<subsection name="lcurly">
|
||||
<section name="lcurly">
|
||||
<p>
|
||||
This property represents the policy for checking the placement of a
|
||||
left curly brace (<code>'{'</code>). The following table
|
||||
|
|
@ -263,9 +264,9 @@
|
|||
</td>
|
||||
</tr>
|
||||
</table>
|
||||
</subsection>
|
||||
</section>
|
||||
|
||||
<subsection name="rcurly">
|
||||
<section name="rcurly">
|
||||
<p>
|
||||
This property represents the policy for checking the placement of a
|
||||
right curly brace (<code>'}'</code>). The following table
|
||||
|
|
@ -375,9 +376,9 @@
|
|||
</td>
|
||||
</tr>
|
||||
</table>
|
||||
</subsection>
|
||||
</section>
|
||||
|
||||
<subsection name="scope">
|
||||
<section name="scope">
|
||||
<p>This property represents a Java scope. The scope is treated
|
||||
inclusively (as javadoc does): 'package' means all 'package', 'protected'
|
||||
and 'public' methods/fields/classes. The valid options are:</p>
|
||||
|
|
@ -390,9 +391,9 @@
|
|||
<li><code>private</code></li>
|
||||
<li><code>anoninner</code></li>
|
||||
</ul>
|
||||
</subsection>
|
||||
</section>
|
||||
|
||||
<subsection name="severity">
|
||||
<section name="severity">
|
||||
<p>
|
||||
This property represents the severity level of a check violation. The
|
||||
valid options are:
|
||||
|
|
@ -404,9 +405,9 @@
|
|||
<li><code>warning</code></li>
|
||||
<li><code>error</code></li>
|
||||
</ul>
|
||||
</subsection>
|
||||
</section>
|
||||
|
||||
<subsection name="importOrder">
|
||||
<section name="importOrder">
|
||||
<p>
|
||||
This property represents the policy for checking imports order.
|
||||
The following table describes the valid options:
|
||||
|
|
@ -479,9 +480,9 @@
|
|||
</td>
|
||||
</tr>
|
||||
</table>
|
||||
</subsection>
|
||||
</section>
|
||||
|
||||
<subsection name="elementStyle">
|
||||
<section name="elementStyle">
|
||||
<p>
|
||||
This property represents the policy for the styles for defining
|
||||
elements in an annotation. The following table
|
||||
|
|
@ -535,9 +536,9 @@
|
|||
</td>
|
||||
</tr>
|
||||
</table>
|
||||
</subsection>
|
||||
</section>
|
||||
|
||||
<subsection name="closingParens">
|
||||
<section name="closingParens">
|
||||
<p>
|
||||
This property represents the policy for the styles for the ending
|
||||
parenthesis. The following table describes the valid options:
|
||||
|
|
@ -572,9 +573,9 @@
|
|||
</td>
|
||||
</tr>
|
||||
</table>
|
||||
</subsection>
|
||||
</section>
|
||||
|
||||
<subsection name="trailingArrayComma">
|
||||
<section name="trailingArrayComma">
|
||||
<p>
|
||||
This property represents the policy for the styles for the trailing
|
||||
array comma. The following table describes the valid options:
|
||||
|
|
@ -609,7 +610,6 @@
|
|||
</td>
|
||||
</tr>
|
||||
</table>
|
||||
</subsection>
|
||||
</section>
|
||||
</body>
|
||||
</document>
|
||||
|
|
|
|||
Loading…
Reference in New Issue