From 61e2ff5df73224f23f1b0434b0fb3b8f46419b5a Mon Sep 17 00:00:00 2001 From: pbludov Date: Wed, 1 May 2019 23:19:26 +0300 Subject: [PATCH] Issue #6726: aligned javadoc/xdoc for SuppressionFilter --- .../checkstyle/filters/SuppressionFilter.java | 194 +++++++++++++++++- .../internal/XdocsJavaDocsTest.java | 1 - src/xdocs/config_filters.xml | 179 ++++++++-------- 3 files changed, 277 insertions(+), 97 deletions(-) diff --git a/src/main/java/com/puppycrawl/tools/checkstyle/filters/SuppressionFilter.java b/src/main/java/com/puppycrawl/tools/checkstyle/filters/SuppressionFilter.java index 7880f25d8a9..ec4c26adb64 100644 --- a/src/main/java/com/puppycrawl/tools/checkstyle/filters/SuppressionFilter.java +++ b/src/main/java/com/puppycrawl/tools/checkstyle/filters/SuppressionFilter.java @@ -32,21 +32,200 @@ /** *

- * This filter accepts AuditEvents according to file, check, line, and - * column, as specified in a suppression file. + * Filter {@code SuppressionFilter} rejects audit events for Check errors according to a + * suppressions XML document + * in a file. If there is no configured suppressions file or the optional is set to true and + * suppressions file was not found the Filter accepts all audit events. *

+ *

+ * A suppressions XML document + * contains a set of {@code suppress} elements, where each {@code suppress} + * element can have the following attributes: + *

+ * + *

+ * Each audit event is checked against each {@code suppress} element. + * It is suppressed if all specified attributes match against the audit event. + *

+ *

+ * ATTENTION: filtering by message is dependant on runtime locale. + * If project is running in different languages it is better to avoid filtering by message. + *

+ *

+ * You can download template of empty suppression filter + * here. + *

+ *

+ * Location of the file defined in {@code file} property is checked in the following order: + *

+ *
    + *
  1. + * as a filesystem location + *
    2. + *
  2. + * if no file found, and the location starts with either {@code http://} or {@code https://}, + * then it is interpreted as a URL + *
    3. + *
  3. + * if no file found, then passed to the {@code ClassLoader.getResource()} method. + *
    4. + *
+ * + *

+ * For example, the following configuration fragment directs the Checker to use + * a {@code SuppressionFilter} with suppressions file {@code config/suppressions.xml}: + *

+ * 
+ * <module name="SuppressionFilter">
+ *   <property name="file" value="config/suppressions.xml"/>
+ *   <property name="optional" value="false"/>
+ * </module>
+ *
+ *

+ * The following suppressions XML document directs a {@code SuppressionFilter} to + * reject {@code JavadocStyleCheck} errors for lines 82 and 108 to 122 of file + * {@code AbstractComplexityCheck.java}, and {@code MagicNumberCheck} errors for + * line 221 of file {@code JavadocStyleCheck.java}, and + * {@code 'Missing a Javadoc comment'} errors for all lines and files: + *

+ * 
+ * <?xml version="1.0"?>
+ *
+ * <!DOCTYPE suppressions PUBLIC
+ *   "-//Checkstyle//DTD SuppressionFilter Configuration 1.2//EN"
+ *   "https://checkstyle.org/dtds/suppressions_1_2.dtd">
+ *
+ * <suppressions>
+ *   <suppress checks="JavadocStyleCheck"
+ *     files="AbstractComplexityCheck.java"
+ *     lines="82,108-122"/>
+ *   <suppress checks="MagicNumberCheck"
+ *     files="JavadocStyleCheck.java"
+ *     lines="221"/>
+ *   <suppress message="Missing a Javadoc comment"/>
+ * </suppressions>
+ *
+ *

+ * Suppress check by module id + * when config have two instances on the same check: + *

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

+ * Suppress all checks for hidden files and folders: + *

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

+ * Suppress all checks for Maven-generated code: + *

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

+ * Suppress all checks for archives, classes and other binary files: + *

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

+ * Suppress all checks for image files: + *

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

+ * Suppress all 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"/>
+ *
+ *

+ * Suppress naming errors on variable named 'log' in all files: + *

+ * 
+ * <suppress message="Name 'log' must match pattern"/>
+ *
+ * + * @since 3.2 */ public class SuppressionFilter extends AutomaticBean implements Filter, ExternalResourceHolder { - /** Filename of suppression file. */ + /** Specify the location of the suppressions XML document file. */ private String file; - /** Tells whether config file existence is optional. */ + /** + * Control what to do when the file is not existing. If {@code optional} is + * set to {@code false} the file must exist, or else it ends with error. + * On the other hand if optional is {@code true} and file is not found, + * the filter accept all audit events. + */ private boolean optional; /** Set of individual suppresses. */ private FilterSet filters = new FilterSet(); /** - * Sets name of the suppression file. + * Setter to specify the location of the suppressions XML document file. * @param fileName name of the suppressions file. */ public void setFile(String fileName) { @@ -54,7 +233,10 @@ public void setFile(String fileName) { } /** - * Sets whether config file existence is optional. + * Setter to control what to do when the file is not existing. + * If {@code optional} is set to {@code false} the file must exist, or else + * it ends with error. On the other hand if optional is {@code true} + * and file is not found, the filter accept all audit events. * @param optional tells if config file existence is optional. */ public void setOptional(boolean optional) { diff --git a/src/test/java/com/puppycrawl/tools/checkstyle/internal/XdocsJavaDocsTest.java b/src/test/java/com/puppycrawl/tools/checkstyle/internal/XdocsJavaDocsTest.java index 31fad932831..7f38de8a508 100644 --- a/src/test/java/com/puppycrawl/tools/checkstyle/internal/XdocsJavaDocsTest.java +++ b/src/test/java/com/puppycrawl/tools/checkstyle/internal/XdocsJavaDocsTest.java @@ -72,7 +72,6 @@ public class XdocsJavaDocsTest extends AbstractModuleTestSupport { // filters "SeverityMatchFilter", "SuppressionCommentFilter", - "SuppressionFilter", "SuppressionXpathFilter", "SuppressionXpathSingleFilter", "SuppressWarningsFilter", diff --git a/src/xdocs/config_filters.xml b/src/xdocs/config_filters.xml index 89aac8a23ba..60ed6d109f8 100644 --- a/src/xdocs/config_filters.xml +++ b/src/xdocs/config_filters.xml @@ -422,13 +422,13 @@ public class UserService {
+

Since Checkstyle 3.2

-

Since Checkstyle 3.2

Filter SuppressionFilter rejects audit events for Check errors according to - a suppressions XML - document in a file. If there is no configured + a suppressions XML + document in a file. If there is no configured suppressions file or the optional is set to true and suppressions file was not found the Filter accepts all audit events.

@@ -445,20 +445,7 @@ public class UserService { 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. -
+ Specify the location of the suppressions XML document file. String null @@ -467,10 +454,10 @@ public class UserService { optional - Tells what to do when the file is not existing. If - optional is set to false the file must exist, or else + Control 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 + true and file is not found, the filter accept all audit events. Boolean @@ -480,66 +467,78 @@ public class UserService { -

- 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 optional. -
    • -
  • - checks - - a Regular Expression - matched against the name of the check associated with an audit - event. Optional as long as id or message is specified. -
    • -
  • - message - - a Regular Expression - matched against the message of the check associated with an audit - event. Optional as long as checks or id is specified. -
    • -
  • - id - - a string - matched against the check id associated with an audit - event. Optional as long as checks or message - 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. -

-

- ATTENTION: filtering by message is dependant on runtime locale. If project is running - in different languages it is better to avoid filtering by message. -

-

- You can download template of empty suppression filter - here. -

+

+ 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 optional. +
    • +
  • + checks - + a Regular Expression + matched against the name of the check associated with an audit + event. Optional as long as id or message is specified. +
    • +
  • + message - + a Regular Expression + matched against the message of the check associated with an audit + event. Optional as long as checks or id is specified. +
    • +
  • + id - + a string + matched against the check id associated with an audit + event. Optional as long as checks or message + 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. +

+

+ ATTENTION: filtering by message is dependant on runtime locale. If project is running + in different languages it is better to avoid filtering by message. +

+

+ You can download template of empty suppression filter + here. +

+

+ Location of the file defined in file property is checked + in the following order: +

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

@@ -562,7 +561,7 @@ public class UserService { file AbstractComplexityCheck.java, and MagicNumberCheck errors for line 221 of file JavadocStyleCheck.java, - and 'Missing a Javadoc comment' errors + and 'Missing a Javadoc comment' errors for all lines and files:

@@ -583,51 +582,51 @@ public class UserService { </suppressions>

- Suppress Check by module id - when config have two instances on the same Check: + Suppress check by module id + when config have two instances on the same check:

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

- Suppress all Checks for hidden files and folders: + Suppress all checks for hidden files and folders:

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

- Suppress all Checks for Maven-generated code: + Suppress all checks for Maven-generated code:

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

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

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

- Suppress all Checks for image files: + Suppress all checks for image files:

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

- Suppress all Checks for non-java files: + Suppress all 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 all checks in generated sources:

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

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

<suppress checks="FileLength"