Issue checkstyle#11655: allow suppressing Google style warnings with …

…annotations and comments
ddcprg · Jun 9, 2022 · 4c6c10d · 4c6c10d
1 parent 1398043
commit 4c6c10d
Show file tree

Hide file tree

Showing 6 changed files with 73 additions and 6 deletions.
diff --git a/config/suppressions.xml b/config/suppressions.xml
@@ -6,7 +6,7 @@
 
 <suppressions>
   <!-- can't split long messages between lines -->
-  <suppress id="lineLengthXml" files="google_checks\.xml" lines="56,127"/>
+  <suppress id="lineLengthXml" files="google_checks\.xml" lines="74,127"/>
   <!-- don't validate generated files -->
   <suppress id="lineLengthXml" files="releasenotes_old_6\-0_7\-8\.xml"/>
   <suppress id="lineLengthXml" files="releasenotes_old_1\-0_5\-9\.xml"/>

diff --git a/src/main/resources/google_checks.xml b/src/main/resources/google_checks.xml
@@ -16,7 +16,10 @@
     Authors: Max Vetrenko, Ruslan Diachenko, Roman Ivanov.
  -->
 
-<module name = "Checker">
+<module name="Checker">
+  <!-- IMPORTANT: Allows use of SuppressWarnings annotation -->
+  <module name="SuppressWarningsFilter"/>
+
   <property name="charset" value="UTF-8"/>
 
   <property name="severity" value="warning"/>
@@ -47,6 +50,21 @@
   </module>
 
   <module name="TreeWalker">
+    <module name="SuppressWarningsHolder" />
+    <module name="SuppressionCommentFilter">
+      <property name="offCommentFormat" value="CHECKSTYLE.OFF\: ([\w\|]+)" />
+      <property name="onCommentFormat" value="CHECKSTYLE.ON\: ([\w\|]+)" />
+      <property name="checkFormat" value="$1" />
+    </module>
+
+    <module name="SuppressWithNearbyCommentFilter">
+      <property name="commentFormat" value="CHECKSTYLE.SUPPRESS\: ([\w\|]+)"/>
+      <!-- $1 refers to the first match group in the regex defined in commentFormat -->
+      <property name="checkFormat" value="$1"/>
+      <!-- The check is suppressed in the next line of code after the comment -->
+      <property name="influenceFormat" value="1"/>
+    </module>
+
     <module name="OuterTypeFilename"/>
     <module name="IllegalTokenText">
       <property name="tokens" value="STRING_LITERAL, CHAR_LITERAL"/>

diff --git a/src/test/java/com/puppycrawl/tools/checkstyle/internal/XdocsPagesTest.java b/src/test/java/com/puppycrawl/tools/checkstyle/internal/XdocsPagesTest.java
@@ -1539,6 +1539,10 @@ public void testAllStyleRules() throws Exception {
             styleChecks.remove("SuppressionXpathSingleFilter");
             styleChecks.remove("TreeWalker");
             styleChecks.remove("Checker");
+            styleChecks.remove("SuppressWithNearbyCommentFilter");
+            styleChecks.remove("SuppressionCommentFilter");
+            styleChecks.remove("SuppressWarningsFilter");
+            styleChecks.remove("SuppressWarningsHolder");
 
             assertWithMessage(
                     fileName + " requires the following check(s) to appear: " + styleChecks)

diff --git a/src/xdocs/config_annotation.xml b/src/xdocs/config_annotation.xml
@@ -1411,6 +1411,10 @@ public void someFunctionWithInvalidStyle() {
             <a href="https://github.com/search?q=path%3Aconfig+filename%3Acheckstyle_checks.xml+repo%3Acheckstyle%2Fcheckstyle+SuppressWarningsHolder">
             Checkstyle Style</a>
           </li>
+          <li>
+            <a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fresources+filename%3Agoogle_checks.xml+repo%3Acheckstyle%2Fcheckstyle+SuppressWarningsHolder">
+            Google Style</a>
+          </li>
         </ul>
       </subsection>
 

diff --git a/src/xdocs/config_filters.xml b/src/xdocs/config_filters.xml
@@ -422,6 +422,10 @@ public class UserService {
             <a href="https://github.com/search?q=path%3Aconfig+filename%3Acheckstyle_checks.xml+repo%3Acheckstyle%2Fcheckstyle+SuppressionCommentFilter">
             Checkstyle Style</a>
           </li>
+          <li>
+            <a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fresources+filename%3Agoogle_checks.xml+repo%3Acheckstyle%2Fcheckstyle+SuppressionCommentFilter">
+            Google Style</a>
+          </li>
         </ul>
       </subsection>
       <subsection name="Package" id="SuppressionCommentFilter_Package">
@@ -1934,6 +1938,10 @@ public static void foo() {
             <a href="https://github.com/search?q=path%3Aconfig+filename%3Acheckstyle_checks.xml+repo%3Acheckstyle%2Fcheckstyle+SuppressWarningsFilter">
             Checkstyle Style</a>
           </li>
+          <li>
+            <a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fresources+filename%3Agoogle_checks.xml+repo%3Acheckstyle%2Fcheckstyle+SuppressWarningsFilter">
+            Google Style</a>
+          </li>
         </ul>
       </subsection>
       <subsection name="Package" id="SuppressWarningsFilter_Package">
@@ -2209,6 +2217,10 @@ public class UserService {
             <a href="https://github.com/search?q=path%3Aconfig+filename%3Acheckstyle_checks.xml+repo%3Acheckstyle%2Fcheckstyle+SuppressWithNearbyCommentFilter">
             Checkstyle Style</a>
           </li>
+          <li>
+            <a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fresources+filename%3Agoogle_checks.xml+repo%3Acheckstyle%2Fcheckstyle+SuppressWithNearbyCommentFilter">
+            Google Style</a>
+          </li>
         </ul>
       </subsection>
       <subsection name="Package" id="SuppressWithNearbyCommentFilter_Package">

diff --git a/src/xdocs/google_style.xml b/src/xdocs/google_style.xml
@@ -2302,24 +2302,53 @@
         <p>
           It is possible to suppress some violations by embeded filters
           <a href="config_filters.html#SuppressionFilter">
-            SuppressionFilter</a>
-          and
+            SuppressionFilter</a>,
           <a href="config_filters.html#SuppressionXpathFilter">
-            SuppressionXpathFilter</a>.
+            SuppressionXpathFilter</a>,
+          <a href="config_filters.html#SuppressWithNearbyCommentFilter">
+            SuppressWithNearbyCommentFilter</a>,
+          <a href="config_filters.html#SuppressionCommentFilter">
+            SuppressionCommentFilter</a>
+          and
+          <a href="config_filters.html#SuppressWarningsFilter">
+            SuppressWarningsFilter</a>
+          in conjunction with
+          <a href="config_filters.html#SuppressWarningsHolder">
+            SuppressWarningsHolder</a>.
           Location of config file for <i>SuppressionFilter</i> can be defined by system property
           <i>org.checkstyle.google.suppressionfilter.config</i> (default value is
           <i>checkstyle-suppressions.xml</i>).
           Location of config file for <i>SuppressionXpathFilter</i>
           can be defined by system property
           <i>org.checkstyle.google.suppressionxpathfilter.config</i> (default value is
           <i>checkstyle-xpath-suppressions.xml</i>).
+          To suppress a check on a block of code using <i>SuppressWithNearbyCommentFilter</i>
+          surround the code block with <i>// CHECKSTYLE.OFF: NameOfTheCheck</i> and
+          <i>// CHECKSTYLE.ON: NameOfTheCheck</i> (replace <i>NameOfTheCheck</i> with the actual
+          check to be suppressed).
+          To suppress a check in the next line of code using <i>SuppressionCommentFilter</i>
+          precede the line of code with <i>// CHECKSTYLE.OFF: NameOfTheCheck</i> (replace
+          <i>NameOfTheCheck</i> with the actual check to be suppressed).
+          To suppress a check using <i>SuppressWarningsFilter</i> use Java's
+          <i>@SuppressWarnings</i> annotation. Each value passed in the array parameter must meet
+          the format <i>checkstyle:name_of_the_check</i> where the <i>checkstyle:</i> is optional
+          and <i>name_of_the_check</i> if the actual name of check to be suppressed in lowercase
+          format.
         </p>
         <p>
           For more details please review exact configuration of Filters in google_checks.xml:
           <a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fresources+filename%3Agoogle_checks.xml+repo%3Acheckstyle%2Fcheckstyle+SuppressionFilter">
                     SuppressionFilter</a>,
           <a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fresources+filename%3Agoogle_checks.xml+repo%3Acheckstyle%2Fcheckstyle+SuppressionXpathFilter">
-                    SuppressionXpathFilter</a>.
+                    SuppressionXpathFilter</a>
+          <a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fresources+filename%3Agoogle_checks.xml+repo%3Acheckstyle%2Fcheckstyle+SuppressWithNearbyCommentFilter">
+                    SuppressWithNearbyCommentFilter</a>,
+          <a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fresources+filename%3Agoogle_checks.xml+repo%3Acheckstyle%2Fcheckstyle+SuppressionCommentFilter">
+                    SuppressionCommentFilter</a>,
+          <a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fresources+filename%3Agoogle_checks.xml+repo%3Acheckstyle%2Fcheckstyle+SuppressWarningsFilter">
+                    SuppressWarningsFilter</a>,
+          <a href="https://github.com/search?q=path%3Asrc%2Fmain%2Fresources+filename%3Agoogle_checks.xml+repo%3Acheckstyle%2Fcheckstyle+SuppressWarningsHolder">
+            SuppressWarningsHolder</a>.
         </p>
       </subsection>
     </section>