From 7a51dd2b237aaf1dd4e582bbdfb94c29d4dd2422 Mon Sep 17 00:00:00 2001
From: Daniel del Castillo <dadelcas@hotmail.com>
Date: Wed, 18 May 2022 22:41:57 +0100
Subject: [PATCH] Issue #11655: allow suppressing Google style warnings with
 annotations and comments

---
 src/main/resources/google_checks.xml | 18 ++++++++++++++-
 src/xdocs/google_style.xml           | 34 ++++++++++++++++++++++++----
 2 files changed, 47 insertions(+), 5 deletions(-)

diff --git a/src/main/resources/google_checks.xml b/src/main/resources/google_checks.xml
index a24ce515d45..f0fb6f4e874 100644
--- 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,19 @@
   </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>
+    <!-- Allow suppression using a comment on the same line or the line before -->
+    <module name="SuppressWithNearbyCommentFilter">
+      <property name="commentFormat" value="CHECKSTYLE.OFF\: ([\w\|]+)"/>
+      <property name="checkFormat" value="$1"/>
+      <property name="influenceFormat" value="1"/>
+    </module>
+
     <module name="OuterTypeFilename"/>
     <module name="IllegalTokenText">
       <property name="tokens" value="STRING_LITERAL, CHAR_LITERAL"/>
diff --git a/src/xdocs/google_style.xml b/src/xdocs/google_style.xml
index abb72772284..a49f40740c1 100644
--- a/src/xdocs/google_style.xml
+++ b/src/xdocs/google_style.xml
@@ -2302,10 +2302,19 @@
         <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>).
@@ -2313,13 +2322,30 @@
           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:maneofthecheck</i> where the <i>checkstyle:</i> is optional and
+          <i>maneofthecheck</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>.
         </p>
       </subsection>
     </section>