Issue checkstyle#6531: aligned javadoc/xdoc for SuppressWarningsHolder

pbludov · Mar 11, 2019 · d677d51 · d677d51
1 parent 28c59c2
commit d677d51
Show file tree

Hide file tree

Showing 3 changed files with 94 additions and 31 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
@@ -33,8 +33,73 @@
 import com.puppycrawl.tools.checkstyle.api.TokenTypes;
 
 /**
- * Maintains a set of check suppressions from {@link SuppressWarnings}
- * annotations.
+ * <p>
+ * Maintains a set of check suppressions from {@code @SuppressWarnings} annotations.
+ * It allows to prevent Checkstyle from reporting errors from parts of code that were
+ * annotated with {@code @SuppressWarnings} and using name of the check to be excluded.
+ * You can also define aliases for check names that need to be suppressed.
+ * </p>
+ * <ul>
+ * <li>
+ * Property {@code aliasList} - Specify aliases for check names that can be used in code
+ * within {@code SuppressWarnings}.
+ * Default value is {@code null}.
+ * </li>
+ * </ul>
+ * <p>
+ * To prevent {@code FooCheck} errors from being reported write:
+ * </p>
+ * <pre>
+ * &#64;SuppressWarnings("foo") interface I { }
+ * &#64;SuppressWarnings("foo") enum E { }
+ * &#64;SuppressWarnings("foo") InputSuppressWarningsFilter() { }
+ * </pre>
+ * <p>
+ * Some real check examples:
+ * </p>
+ * <p>
+ * This will prevent from invocation of the MemberNameCheck:
+ * </p>
+ * <pre>
+ * &#64;SuppressWarnings({"membername"})
+ * private int J;
+ * </pre>
+ * <p>
+ * You can also use a {@code checkstyle} prefix to prevent compiler from
+ * processing this annotations. For example this will prevent ConstantNameCheck:
+ * </p>
+ * <pre>
+ * &#64;SuppressWarnings("checkstyle:constantname")
+ * private static final int m = 0;
+ * </pre>
+ * <p>
+ * The general rule is that the argument of the {@code @SuppressWarnings} will be
+ * matched against class name of the checker in lower case and without {@code Check}
+ * suffix if present.
+ * </p>
+ * <p>
+ * If {@code aliasList} property was provided you can use your own names e.g below
+ * code will work if there was provided a {@code ParameterNumberCheck=paramnum} in
+ * the {@code aliasList}:
+ * </p>
+ * <pre>
+ * &#64;SuppressWarnings("paramnum")
+ * public void needsLotsOfParameters(@SuppressWarnings("unused") int a,
+ *   int b, int c, int d, int e, int f, int g, int h) {
+ *   ...
+ * }
+ * </pre>
+ * <p>
+ * It is possible to suppress all the checkstyle warnings with the argument {@code "all"}:
+ * </p>
+ * <pre>
+ * &#64;SuppressWarnings("all")
+ * public void someFunctionWithInvalidStyle() {
+ *   //...
+ * }
+ * </pre>
+ *
+ * @since 5.7
  */
 @StatelessCheck
 public class SuppressWarningsHolder
@@ -118,10 +183,8 @@ private static void registerAlias(String sourceName, String checkAlias) {
     }
 
     /**
-     * Registers a list of source name aliases based on a comma-separated list
-     * of {@code source=alias} items, such as {@code
-     * com.puppycrawl.tools.checkstyle.checks.sizes.ParameterNumberCheck=
-     * paramnum}.
+     * Setter to specify aliases for check names that can be used in code
+     * within {@code SuppressWarnings}.
      * @param aliasList the list of comma-separated alias assignments
      */
     public void setAliasList(String... aliasList) {

diff --git a/src/test/java/com/puppycrawl/tools/checkstyle/internal/XdocsJavaDocsTest.java b/src/test/java/com/puppycrawl/tools/checkstyle/internal/XdocsJavaDocsTest.java
@@ -97,6 +97,7 @@ public class XdocsJavaDocsTest extends AbstractModuleTestSupport {
         "ParameterName",
         "StaticVariableName",
         "SuppressWarnings",
+        "SuppressWarningsHolder",
         "TypeName",
     };
 

diff --git a/src/xdocs/config_annotation.xml b/src/xdocs/config_annotation.xml
@@ -1030,8 +1030,8 @@ public static final int COUNTER = 10; // violation as javadoc exists
     </section>
 
     <section name="SuppressWarningsHolder">
+      <p>Since Checkstyle 5.7</p>
       <subsection name="Description" id="SuppressWarningsHolder_Description">
-        <p>Since Checkstyle 5.7</p>
         <p>
           Maintains a set of check suppressions from
           <code>@SuppressWarnings</code> annotations. It allows to
@@ -1053,11 +1053,12 @@ public static final int COUNTER = 10; // violation as javadoc exists
           </tr>
           <tr>
             <td>aliasList</td>
-            <td>Aliases for check names that can be used in code within
-                <code>SuppressWarnings</code></td>
-            <td><a href="property_types.html#stringSet">String Set</a> in a format of comma separated attribute=value entries.
+            <td>Specify aliases for check names that can be used in code within
+                <code>SuppressWarnings</code>.</td>
+            <td><a href="property_types.html#stringSet">String Set</a>
+                in a format of comma separated attribute=value entries.
             The attribute is the fully qualified name of the Check and value is its alias.</td>
-            <td>null</td>
+            <td><code>null</code></td>
             <td>5.7</td>
           </tr>
         </table>
@@ -1070,48 +1071,46 @@ public static final int COUNTER = 10; // violation as javadoc exists
 @SuppressWarnings("foo") enum E { }
 @SuppressWarnings("foo") InputSuppressWarningsFilter() { }
         </source>
-        <br />
         <p>Some real check examples:</p>
-        <p>This will prevent from invocation of the MemberNameCheck:
-          <source>
+        <p>This will prevent from invocation of the MemberNameCheck:</p>
+        <source>
 @SuppressWarnings({"membername"})
 private int J;
-           </source>
-        </p>
-
+        </source>
         <p>You can also use a <code>checkstyle</code> prefix to prevent compiler from
            processing this annotations.
-           For example this will prevent ConstantNameCheck
-          <source>
+           For example this will prevent ConstantNameCheck:
+        </p>
+        <source>
 @SuppressWarnings("checkstyle:constantname")
 private static final int m = 0;
-          </source>
-        </p>
+        </source>
 
         <p>The general rule is that the argument of the <code>@SuppressWarnings</code> will be
           matched against class name of the checker in lower case and without <code>Check</code>
-          suffix if present</p>
-          <p>If <code>aliasList</code> property was provided you can use your own names e.g below
+          suffix if present.
+        </p>
+        <p>If <code>aliasList</code> property was provided you can use your own names e.g below
              code will work if there was provided a <code>ParameterNumberCheck=paramnum</code> in
-             the <code>aliasList</code>
-          <source>
+             the <code>aliasList</code>:
+        </p>
+        <source>
 @SuppressWarnings("paramnum")
 public void needsLotsOfParameters(@SuppressWarnings("unused") int a,
   int b, int c, int d, int e, int f, int g, int h) {
   ...
 }
-          </source>
-      </p>
+        </source>
 
-      <p>It is possible to suppress all the checkstyle warnings with the argument
+        <p>It is possible to suppress all the checkstyle warnings with the argument
          <code>"all"</code>:
-          <source>
+        </p>
+        <source>
 @SuppressWarnings("all")
 public void someFunctionWithInvalidStyle() {
   //...
 }
-          </source>
-      </p>
+        </source>
 
       </subsection>