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

…annotations and comments
ddcprg · Jul 5, 2022 · b7f6f8f · b7f6f8f
1 parent 5444844
commit b7f6f8f
Show file tree

Hide file tree

Showing 6 changed files with 85 additions and 9 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="58,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
@@ -17,6 +17,8 @@
  -->
 
 <module name = "Checker">
+  <module name="SuppressWarningsFilter"/>
+
   <property name="charset" value="UTF-8"/>
 
   <property name="severity" value="warning"/>
@@ -363,5 +365,18 @@
              default="checkstyle-xpath-suppressions.xml" />
       <property name="optional" value="true"/>
     </module>
+    <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>
 </module>
diff --git a/src/test/java/com/puppycrawl/tools/checkstyle/internal/XdocsPagesTest.java b/src/test/java/com/puppycrawl/tools/checkstyle/internal/XdocsPagesTest.java
@@ -1541,6 +1541,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,65 @@
         <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>.
-          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>
+            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>.
+        </p>
+        <p>
+          Location of config file for
+          <a href="config_filters.html#SuppressionFilter">SuppressionFilter</a> can
+          be defined by system property <i>org.checkstyle.google.suppressionfilter.config</i>
+          (default value is <i>checkstyle-suppressions.xml</i>).
+        </p>
+        <p>
+          Location of config file for
+          <a href="config_filters.html#SuppressionXpathFilter">SuppressionXpathFilter</a>
           can be defined by system property
           <i>org.checkstyle.google.suppressionxpathfilter.config</i> (default value is
           <i>checkstyle-xpath-suppressions.xml</i>).
         </p>
+        <p>
+          To suppress a check in the next line of code using
+          <a href="config_filters.html#SuppressWithNearbyCommentFilter">
+            SuppressWithNearbyCommentFilter</a>precede the line of code with
+          <i>// CHECKSTYLE.SUPPRESS: NameOfTheCheck</i> (replace <i>NameOfTheCheck</i> with
+          the actual check to be suppressed).
+        </p>
+        <p>
+          To suppress a check on a block of code using
+          <a href="config_filters.html#SuppressionCommentFilter">SuppressionCommentFilter</a>
+          add <i>// CHECKSTYLE.OFF: NameOfTheCheck</i> before the beginning of the code block and
+          <i>// CHECKSTYLE.ON: NameOfTheCheck</i> after the end of the code block (replace
+          <i>NameOfTheCheck</i> with the actual check to be suppressed).
+        </p>
+        <p>
+          To suppress a check using
+          <a href="config_filters.html#SuppressWarningsFilter">SuppressWarningsFilter</a>
+          use Java's<i>@SuppressWarnings({"checkstyle:name_of_the_check", ...})</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> is 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>,
         </p>
       </subsection>
     </section>