From 0b78aeda9406f40e890ac00ad55a1ff596e29439 Mon Sep 17 00:00:00 2001 From: Kevin222004 Date: Wed, 13 Jul 2022 10:54:11 +0530 Subject: [PATCH] Issue #7576: update doc for SuppressWarningsHolder --- .../checks/SuppressWarningsHolder.java | 93 ++++++++++++------ .../meta/checks/SuppressWarningsHolder.xml | 3 + src/xdocs/config_annotation.xml | 95 +++++++++++++------ 3 files changed, 129 insertions(+), 62 deletions(-) diff --git a/src/main/java/com/puppycrawl/tools/checkstyle/checks/SuppressWarningsHolder.java b/src/main/java/com/puppycrawl/tools/checkstyle/checks/SuppressWarningsHolder.java index 15589792665..e9e28d0f651 100644 --- a/src/main/java/com/puppycrawl/tools/checkstyle/checks/SuppressWarningsHolder.java +++ b/src/main/java/com/puppycrawl/tools/checkstyle/checks/SuppressWarningsHolder.java @@ -39,6 +39,9 @@ * Maintains a set of check suppressions from {@code @SuppressWarnings} annotations. * It allows to prevent Checkstyle from reporting violations from parts of code that were * annotated with {@code @SuppressWarnings} and using name of the check to be excluded. + * It is possible to suppress all the checkstyle warnings with the argument {@code "all"}. + * You can also use a {@code checkstyle:} prefix to prevent compiler + * from processing these annotations. * You can also define aliases for check names that need to be suppressed. *

* *

- * To prevent {@code FooCheck} violations from being reported write: + * To use default module configuration: *

* 
- * @SuppressWarnings("foo") interface I { }
- * @SuppressWarnings("foo") enum E { }
- * @SuppressWarnings("foo") InputSuppressWarningsFilter() { }
- *
- *

- * Some real check examples: - *

- *

- * This will prevent from invocation of the MemberNameCheck: - *

- * 
- * @SuppressWarnings({"membername"})
- * private int J;
+ * <module name="TreeWalker">
+ *   <module name="MemberName"/>
+ *   <module name="ConstantName"/>
+ *   <module name="ParameterNumber">
+ *     <property name="id" value="ParamNumberId"/>
+ *   </module>
+ *   <module name="NoWhitespaceAfter"/>
+ *
+ *   <module name="SuppressWarningsHolder"/>
+ * </module>
+ * <module name="SuppressWarningsFilter"/>
  *
- *

- * You can also use a {@code checkstyle} prefix to prevent compiler from - * processing these annotations. For example this will prevent ConstantNameCheck: - *

* 
- * @SuppressWarnings("checkstyle:constantname")
- * private static final int m = 0;
+ * class Test {
+ *
+ *     private int K; // violation
+ *     @SuppressWarnings({"membername"})
+ *     private int J; // violation suppressed
+ *
+ *     private static final int i = 0; // violation
+ *     @SuppressWarnings("checkstyle:constantname")
+ *     private static final int m = 0; // violation suppressed
+ *
+ *     public void needsLotsOfParameters (int a, // violation
+ *       int b, int c, int d, int e, int f, int g, int h) {
+ *       // ...
+ *     }
+ *
+ *     @SuppressWarnings("ParamNumberId")
+ *     public void needsLotsOfParameters1 (int a, // violation suppressed
+ *       int b, int c, int d, int e, int f, int g, int h) {
+ *       //  ...
+ *     }
+ *
+ *    private int [] ARR; // 2 violations
+ *    @SuppressWarnings("all")
+ *    private int [] ARRAY; // violations suppressed
+ * }
  *
*

* The general rule is that the argument of the {@code @SuppressWarnings} will be @@ -86,19 +106,30 @@ * the {@code aliasList}: *

* 
- * @SuppressWarnings("paramnum")
- * public void needsLotsOfParameters(@SuppressWarnings("unused") int a,
- *   int b, int c, int d, int e, int f, int g, int h) {
- *   ...
- * }
+ * <module name="TreeWalker">
+ *   <module name="ParameterNumber"/>
+ *
+ *   <module name="SuppressWarningsHolder">
+ *     <property name="aliasList" value=
+ *       "com.puppycrawl.tools.checkstyle.checks.sizes.ParameterNumberCheck=paramnum"/>
+ *   </module>
+ * </module>
+ * <module name="SuppressWarningsFilter"/>
  *
- *

- * It is possible to suppress all the checkstyle warnings with the argument {@code "all"}: - *

* 
- * @SuppressWarnings("all")
- * public void someFunctionWithInvalidStyle() {
- *   //...
+ * class Test {
+ *
+ *     public void needsLotsOfParameters (int a, // violation
+ *       int b, int c, int d, int e, int f, int g, int h) {
+ *       // ...
+ *     }
+ *
+ *     @SuppressWarnings("paramnum")
+ *     public void needsLotsOfParameters1 (int a, // violation suppressed
+ *       int b, int c, int d, int e, int f, int g, int h) {
+ *       //  ...
+ *     }
+ *
  * }
  *
*

diff --git a/src/main/resources/com/puppycrawl/tools/checkstyle/meta/checks/SuppressWarningsHolder.xml b/src/main/resources/com/puppycrawl/tools/checkstyle/meta/checks/SuppressWarningsHolder.xml index 8ca129b7cd8..4535d64ba22 100644 --- a/src/main/resources/com/puppycrawl/tools/checkstyle/meta/checks/SuppressWarningsHolder.xml +++ b/src/main/resources/com/puppycrawl/tools/checkstyle/meta/checks/SuppressWarningsHolder.xml @@ -8,6 +8,9 @@ Maintains a set of check suppressions from {@code @SuppressWarnings} annotations. It allows to prevent Checkstyle from reporting violations from parts of code that were annotated with {@code @SuppressWarnings} and using name of the check to be excluded. + It is possible to suppress all the checkstyle warnings with the argument {@code "all"}. + You can also use a {@code checkstyle:} prefix to prevent compiler + from processing these annotations. You can also define aliases for check names that need to be suppressed. </p> diff --git a/src/xdocs/config_annotation.xml b/src/xdocs/config_annotation.xml index 72cf40c814e..d6ffbba40ce 100644 --- a/src/xdocs/config_annotation.xml +++ b/src/xdocs/config_annotation.xml @@ -1321,7 +1321,11 @@ package com.example.annotations.packageannotation; //ok @SuppressWarnings annotations. It allows to prevent Checkstyle from reporting violations from parts of code that were annotated with @SuppressWarnings and - using name of the check to be excluded. You can also define + using name of the check to be excluded. It is possible to suppress + all the checkstyle warnings with the argument + "all". + You can also use a checkstyle: prefix to prevent compiler from + processing these annotations. You can also define aliases for check names that need to be suppressed.

@@ -1355,27 +1359,47 @@ package com.example.annotations.packageannotation; //ok -

To prevent FooCheck violations from being reported write:

+

To use default module configuration:

-@SuppressWarnings("foo") interface I { } -@SuppressWarnings("foo") enum E { } -@SuppressWarnings("foo") InputSuppressWarningsFilter() { } - -

Some real check examples:

-

This will prevent from invocation of the MemberNameCheck:

- -@SuppressWarnings({"membername"}) -private int J; +<module name="TreeWalker"> + <module name="MemberName"/> + <module name="ConstantName"/> + <module name="ParameterNumber"> + <property name="id" value="ParamNumberId"/> + </module> + <module name="NoWhitespaceAfter"/> + + <module name="SuppressWarningsHolder"/> +</module> +<module name="SuppressWarningsFilter"/> -

You can also use a checkstyle prefix to prevent compiler from - processing these annotations. - For example this will prevent ConstantNameCheck: -

-@SuppressWarnings("checkstyle:constantname") -private static final int m = 0; +class Test { + + private int K; // violation + @SuppressWarnings({"membername"}) + private int J; // violation suppressed + + private static final int i = 0; // violation + @SuppressWarnings("checkstyle:constantname") + private static final int m = 0; // violation suppressed + + public void needsLotsOfParameters (int a, // violation + int b, int c, int d, int e, int f, int g, int h) { + // ... + } + + @SuppressWarnings("ParamNumberId") + public void needsLotsOfParameters1 (int a, // violation suppressed + int b, int c, int d, int e, int f, int g, int h) { + // ... + } + + private int [] ARR; // 2 violations + @SuppressWarnings("all") + private int [] ARRAY; // violations suppressed +} -

The general rule is that the argument of the @SuppressWarnings will be matched against class name of the checker in lower case and without Check suffix if present. @@ -1385,21 +1409,30 @@ private static final int m = 0; the aliasList:

-@SuppressWarnings("paramnum") -public void needsLotsOfParameters(@SuppressWarnings("unused") int a, - int b, int c, int d, int e, int f, int g, int h) { - ... -} - +<module name="TreeWalker"> + <module name="ParameterNumber"/> -

- It is possible to suppress all the checkstyle warnings with the argument - "all": -

+ <module name="SuppressWarningsHolder"> + <property name="aliasList" value= + "com.puppycrawl.tools.checkstyle.checks.sizes.ParameterNumberCheck=paramnum"/> + </module> +</module> +<module name="SuppressWarningsFilter"/> + -@SuppressWarnings("all") -public void someFunctionWithInvalidStyle() { - //... +class Test { + + public void needsLotsOfParameters (int a, // violation + int b, int c, int d, int e, int f, int g, int h) { + // ... + } + + @SuppressWarnings("paramnum") + public void needsLotsOfParameters1 (int a, // violation suppressed + int b, int c, int d, int e, int f, int g, int h) { + // ... + } + }