A Checkstyle configuration specifies which modules to plug in and apply to Java source files. Modules are structured in a tree whose root is the Checker - module. The next level of modules contains FileSetChecks- modules that - take a set of input files and fire error messages. Many checks are submodules of + module. The next level of modules contains +
++ Many checks are submodules of the TreeWalker FileSetCheck module. The TreeWalker operates by separately transforming each of the Java source files into an abstract syntax tree and then handing the result over to each of its submodules which in turn @@ -157,7 +170,7 @@
- Properties of a module control how the module performs its checks. + Properties of a module control how the module performs its task. Each module property has a default value, and you are not required to define a property in the configuration document if the default value is satisfactory. To assign a non-default value to a module's property, @@ -219,8 +232,13 @@
All configurations have root module Checker. - Checker contains FileSetCheck children: modules that - check sets of files. + Checker contains +
++ A Checker module applies Filter submodules to audit events, including the error messages fired by Checks. + The Filters form a chain in the same order as they appear in the configuration file. A Checker applies the + Filters in chain order. A Filter can accept, deny, or be neutral about an audit event. If a Filter accepts + an audit event, then the Checker reports the event without consulting later Filters in the chain. + If a Filter denies an event, then the Checker does not report the event. If a Filter is neutral for an event, then the + Checker consults the next Filter. If all Filters are neutral for an event, the Checker reports the event. +
++ Filter SeverityMatchFilter decides audit events for Check errors according to the + severity level of the Check. The filter is neutral on audit events that do not + have a severity level, such as "Starting audit". +
+| name | +description | +type | +default value | +
|---|---|---|---|
| severity | +the severity level of this filter | +severity | +error | +
| acceptOnMatch | +If there is a match between the severity level of the Check for the audit event and property severity, and + acceptOnMatch is true, then the filter accepts the audit event. + If there is a match between the severity level of the Check for the audit event and property severity, and + acceptOnMatch is false, then the filter denies the audit event. | +boolean | +true | +
+ 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 decides audit events for Check errors according to a + suppressions XML document in a file. If there is no configured suppressions file, the + Filter is neutral on all audit events. +
+ +| name | +description | +type | +default value | +
|---|---|---|---|
| file | +the name of the suppressions XML document file | +string | +none | +
+ 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 + has a files attribute, a checks attribute, + an optional lines attribute, and an optional + columns attribute. + Attributes files and checks are + regular expressions. + Attributes lines and columns are + comma-separated values, where each value is an integer or + a range of integers denoted by integer-integer. +
++ An audit event for a Check error matches a suppress element if + the file name for the event matches the files attribute of the element, + the name of the Check matches the checks attribute, and + the line of the event matches the lines attribute (provided the attribute exists) or + the column of the event matches the columns attribute (provided the attribute exists). + When a SuppressionFilter decides an audit event for a Check error, it denies + the event if the event matches any one of the configured suppress elements. In all other + cases, the Filter is neutral to the event. +
+ ++ For example, the following suppressions XML document directs a SuppressionFilter + to deny 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.0//EN" + "http://www.puppycrawl.com/dtds/suppressions_1_0.dtd"> + +<suppressions> + <suppress checks="JavadocStyleCheck" + files="AbstractComplexityCheck.java" + lines="82,108-122"/> + <suppress checks="MagicNumberCheck" + files="JavadocStyleCheck.java" + lines="221"/> +</suppressions> ++ + +
+ TODO +
@@ -570,6 +726,23 @@ "-//Puppy Crawl//DTD Package Names 1.0//EN" "http://www.puppycrawl.com/dtds/packages_1_0.dtd"> + + +
+ This is a DTD for a suppressions XML document: +
++<?xml version="1.0" encoding="UTF-8"?> + +<!ELEMENT suppressions (suppress*)> + +<!ELEMENT suppress EMPTY> +<!ATTLIST suppress files CDATA #REQUIRED + checks CDATA #REQUIRED + lines CDATA #IMPLIED + columns CDATA #IMPLIED> +