From 3ebddae1b928b69793717d4e207b660b31fefdb5 Mon Sep 17 00:00:00 2001 From: Andrei Selkin Date: Sun, 4 Oct 2015 12:22:49 +0300 Subject: [PATCH] Issue #819: Split config.html into few pages --- src/site/site.xml | 3 +- src/xdocs/config.xml | 798 +---------------------------------- src/xdocs/config_filters.xml | 756 +++++++++++++++++++++++++++++++++ src/xdocs/property_types.xml | 70 +-- 4 files changed, 801 insertions(+), 826 deletions(-) create mode 100644 src/xdocs/config_filters.xml diff --git a/src/site/site.xml b/src/site/site.xml index 856911cbd..da6575142 100644 --- a/src/site/site.xml +++ b/src/site/site.xml @@ -47,7 +47,7 @@ href="https://plus.google.com/108692338295483568100/posts" /> - + @@ -58,6 +58,7 @@ + diff --git a/src/xdocs/config.xml b/src/xdocs/config.xml index 18f866155..66a4fd2df 100644 --- a/src/xdocs/config.xml +++ b/src/xdocs/config.xml @@ -245,6 +245,11 @@ copy and maintain the whole configuration.

+

+ You can find information about property types on + Property Types page. +

+
@@ -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 + filters page.

- -

- Filter SeverityMatchFilter decides - audit events according to the severity - level of the event. -

- -
SeverityMatchFilter Properties
- - - - - - - - - - - - - - - - - - - -
namedescriptiontypedefault value
severitythe severity level of this filterseverityerror
acceptOnMatch - If acceptOnMatch is true, 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 false, 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. - booleantrue
- -

- For example, the following configuration fragment directs the - Checker to not report audit events with severity - level info: -

- - -<module name="SeverityMatchFilter"> - <property name="severity" value="info"/> - <property name="acceptOnMatch" value="false"/> -</module> - - - - -

- Filter SuppressionFilter rejects - audit events for Check errors according to - a suppressions XML - document in a file. If there is no configured - suppressions file, the Filter accepts all audit events. -

- -
SuppressionFilter Properties
- - - - - - - - - - - - - -
namedescriptiontypedefault value
file - the location of the suppressions XML document file. - The order the location is checked is: -
    -
  1. as a filesystem location
    2. -
  2. - if no file found, and the location starts with either - http:// or https://, then it - is interpreted as a URL -
    3. -
  3. - if no file found, then passed to the - ClassLoader.getResource() method. -
    4. -
- 		stringnone
- -

- For example, the following configuration fragment directs the - Checker to use a SuppressionFilter - with suppressions - file docs/suppressions.xml: -

- - -<module name="SuppressionFilter"> - <property name="file" value="docs/suppressions.xml"/> -</module> - - -

- A suppressions XML - document contains a set - of suppress elements, where - each suppress element can have the - following attributes: -

- -
    -
  • - files - - a regular expression - matched against the file name associated with an audit - event. It is mandatory. -
    • -
  • - checks - - a regular expression - matched against the name of the check associated with an audit - event. Optional if id is specified. -
    • -
  • - id - - a string - matched against the ID of the check associated with an audit - event. Optional if checks is specified. -
    • -
  • - lines - a comma-separated list of - values, where each value is - an integer or a - range of integers denoted by integer-integer. It is optional. -
    • -
  • - columns - a comma-separated list of - values, where each value is - an integer or a - range of integers denoted by integer-integer. It is optional. -
    • -
- -

- Each audit event is checked against - each suppress element. It is - suppressed if all specified attributes match against the audit - event. -

- -
Examples
- -

You can download template of empty suppression filter here.

- -

- The following suppressions XML document directs - a SuppressionFilter to - reject JavadocStyleCheck errors for - lines 82 and 108 to 122 of - file AbstractComplexityCheck.java, - and MagicNumberCheck errors for line - 221 of file JavadocStyleCheck.java: -

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

- As another example to suppress Check by module id: -

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

- Then the following can be used to suppress only the first - check and not the second by using - the id attribute: -

- - -<suppress id="stringEqual" files="SomeTestCode.java"/> - - -

- Suppress checks for hidden files and folders: -

- - -<suppress files="[/\\]\..+" checks=".*"/> - - -

- Suppress checks for Maven-generated code: -

- - -<suppress files="[/\\]target[/\\]" checks=".*"/> - - -

- Suppress checks for archives, classes and other binary files: -

- - -<suppress files=".+\.(?:jar|zip|war|class|tar|bin)$" checks=".*"/> - - -

- Suppress checks for image files: -

- - -<suppress files=".+\.(?:png|gif|jpg|jpeg)$" checks=".*"/> - - -

- Suppress checks for non-java files: -

- - -<suppress files=".+\.(?:txt|xml|csv|sh|thrift|html|sql|eot|ttf|woff|css|png)$" checks=".*"/> - - -

- Suppress all checks in generated sources: -

- - -<suppress checks=".*" files="com[\\/]mycompany[\\/]app[\\/]gen[\\/]"/> - - -

- Suppress FileLength check on integration tests in certain folder: -

- - -<suppress checks="FileLength" files="com[\\/]mycompany[\\/]app[\\/].*IT.java"/> - - - - - -

SuppressionCommentFilter

- -

- Filter SuppressionCommentFilter uses - pairs of comments to suppress audit events. -

- -

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

- -

- Usage: This filter only works in conjunction with a FileContentsHolder, since that check makes - the suppression comments in the Java files available. A configuration that includes this filter must - configure FileContentsHolder as a - child module of TreeWalker. -

- -
SuppressionCommentFilter Properties
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
namedescriptiontypedefault value
offCommentFormatcomment pattern to trigger filter to begin suppressionregular expressionCHECKSTYLE\:OFF
onCommentFormatcomment pattern to trigger filter to end suppressionregular expressionCHECKSTYLE\:ON
checkFormatcheck pattern to suppressregular expression.* (all checks)
messageFormatmessage pattern to suppressregular expressionnone
checkCPPwhether to check C++ style comments (//)booleantrue
checkCwhether to check C style comments (/* ... */)booleantrue
- -
Restrictions
-

- offCommentFormat and onCommentFormat must have equal paren counts. -

- -
Examples
-

- Make sure that comments are available to the filter by enabling FileContentsHolder: -

- - -<module name="TreeWalker"> - ... - <module name="FileContentsHolder"/> - ... -</module> - - -

- To configure a filter to suppress audit events between a comment - containing CHECKSTYLE:OFF and a comment containing - CHECKSTYLE:ON: -

- - -<module name="Checker"> - ... - <module name="SuppressionCommentFilter"/> - ... -</module> - - -

- To configure a filter to suppress audit events between a comment - containing line BEGIN GENERATED CODE and a comment - containing line END GENERATED CODE: -

- - -<module name="SuppressionCommentFilter"> - <property name="offCommentFormat" value="BEGIN GENERATED CODE"/> - <property name="onCommentFormat" value="END GENERATED CODE"/> -</module> - - - -//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 -. . . - - -

- To configure a filter so that // stop constant - check and // resume constant check marks - legitimate constant names: -

- - -<module name="SuppressionCommentFilter"> - <property name="offCommentFormat" value="stop constant check"/> - <property name="onCommentFormat" value="resume constant check"/> - <property name="checkFormat" value="ConstantNameCheck"/> -</module> - - - -//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]*$" - - -

- To configure a filter so that UNUSED OFF: - var and UNUSED ON: var marks a - variable or parameter known not to be used by the code by - matching the variable name in the message: -

- - -<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> - - - -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); -} - - -

- To configure a filter so that name of suppressed check mentioned - in comment CSOFF: regexp - and CSN: regexp mark a matching check: -

- - -<module name="SuppressionCommentFilter"> - <property name="offCommentFormat" value="CSOFF\: ([\w\|]+)"/> - <property name="onCommentFormat" value="CSON\: ([\w\|]+)"/> - <property name="checkFormat" value="$1"/> -</module> - - - -public static final int lowerCaseConstant; // CSOFF: ConstantNameCheck -public static final int lowerCaseConstant1; // CSON: ConstantNameCheck - - -

- To configure a filter to suppress all audit events between a comment - containing CHECKSTYLE_OFF: ALMOST_ALL and a comment containing - CHECKSTYLE_OFF: ALMOST_ALL except for the EqualsHashCode check: -

- - -<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> - - - -public static final int array []; // CHECKSTYLE_OFF: ALMOST_ALL -private String [] strArray; -private int array1 []; // CHECKSTYLE_ON: ALMOST_ALL - - -

- To configure a filter to suppress Check's violation message which matches - specified message in messageFormat (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 stop and comment containing resume: -

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

- Code before filter above is applied with Check's audit events: -

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

- Code after filter is applied: -

- - -... -//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 -... - - - - - -

SuppressWithNearbyCommentFilter

- -

- Filter SuppressWithNearbyCommentFilter uses - individual comments to suppress audit events. -

- -

- Rationale: Same as SuppressionCommentFilter. - Whereas the SuppressionCommentFilter uses matched pairs of - filters to turn on/off comment matching, - SuppressWithNearbyCommentFilter uses - single comments. This requires fewer lines to mark a region, and - may be aesthetically preferable in some contexts. -

- -

- Usage: This filter only works in conjunction with a FileContentsHolder, since that check makes - the suppression comments in the Java files available. A configuration that includes this filter must - configure FileContentsHolder as a - child module of TreeWalker. -

- -
SuppressWithNearbyCommentFilter Properties
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
namedescriptiontypedefault value
commentFormatcomment pattern to trigger filter to begin suppressionregular expressionSUPPRESS CHECKSTYLE (\w+)
checkFormatcheck pattern to suppressregular expression.*
messageFormatmessage pattern to suppressregular expressionnone
influenceFormata negative/zero/positive value that defines the number of - lines preceding/at/following the suppression commentregular expression0 (the line containing the comment)
checkCPPwhether to check C++ style comments (//)booleantrue
checkCwhether to check C style comments (/* ... */)booleantrue
- -
Examples
-

- To configure the check that makes comments available to the filter: -

- - -<module name="TreeWalker"> - ... - <module name="FileContentsHolder"/> - ... -</module> - - -

- To configure a filter to suppress audit events for check - on any line with a comment SUPPRESS CHECKSTYLE check: -

- - -<module name="SuppressWithNearbyCommentFilter"/> - - - -private int [] array; // SUPPRESS CHECKSTYLE - - -

- To configure a filter to suppress all audit events on any line - containing the comment CHECKSTYLE IGNORE THIS LINE: -

- - -<module name="SuppressWithNearbyCommentFilter"> - <property name="commentFormat" value="CHECKSTYLE IGNORE THIS LINE"/> - <property name="checkFormat" value=".*"/> - <property name="influenceFormat" value="0"/> -</module> - - - -public static final int lowerCaseConstant; // CHECKSTYLE IGNORE THIS LINE - - -

- To configure a filter so that - // OK to catch (Throwable|Exception|RuntimeException) here - permits the current and previous line to avoid generating an IllegalCatch - audit event: -

- - -<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> - - - -. . . -catch (RuntimeException re) { - // OK to catch RuntimeException here -} -catch (Throwable th) { ... } -. . . - - -

- To configure a filter so that CHECKSTYLE IGNORE check FOR NEXT var LINES - avoids triggering any audits for the given check for the current line and the next var lines - (for a total of var+1 lines): -

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

- To configure a filter to avoid any audits on code like: -

- - -<module name="SuppressWithNearbyCommentFilter"> - <property name="commentFormat" value="ALLOW (\\w+) ON PREVIOUS LINE"/> - <property name="checkFormat" value="$1"/> - <property name="influenceFormat" value="-1"/> -</module> - - - -private int D2; -// ALLOW MemberName ON PREVIOUS LINE -. . . - - -

- To configure a filter to allow suppress one or more Checks(separated by "|") - and demand comment no less than 14 symbols: -

- - -<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> - - - -public static final int [] array; // @cs.suppress ConstantName | NoWhitespaceAfter - - - - - -

SuppressWarningsFilter

-

- Filter SuppressWarningsFilter uses annotations to - suppress audit events. -

- -

- Rationale: Same as for - SuppressionCommentFilter. In the contrary to it - here, comments are not used comments but the builtin syntax of - @SuppressWarnings. This can be perceived as a - more elegant solution than using comments. Also this approach - maybe supported by various IDE. -

-

- Usage: This filter only works in conjunction with a - SuppressWarningsHolder, 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 - SuppressWarningsHolder as a child module of the - TreeWalker. Name of check in annotation should - be written in lower case with any dotted prefix or "Check" suffix removed. -

- -
SuppressWarningsFilter Properties
-

This filter does not expose any properties

- -
Examples
-

- To configure the check that makes tha annotations available to - the filter. -

- -<module name="TreeWalker"> - ... - <module name="SuppressWarningsHolder" /> - ... -</module> - - -

To configure filter to suppress audit events for annotations add:

- -<module name="SuppressWarningsFilter" /> - - - -@SuppressWarnings({"membername"}) -private int J; // should NOT fail MemberNameCheck - -@SuppressWarnings({"membername"}) -@SuppressWarnings({"nowhitespaceafter"}) -private int [] ARRAY; // should NOT fail MemberNameCheck and NoWhitespaceAfterCheck - - -
@@ -1539,7 +757,7 @@ private int [] ARRAY; // should NOT fail MemberNameCheck and NoWhitespaceAfterCh
-
+

Configuration XML Document

diff --git a/src/xdocs/config_filters.xml b/src/xdocs/config_filters.xml new file mode 100644 index 000000000..fab53b7d4 --- /dev/null +++ b/src/xdocs/config_filters.xml @@ -0,0 +1,756 @@ + + + + + + Filters +