Summary

Document the set of strings recognized by javac as arguments for @SuppressWarnings.

Problem

The set of strings accepted by javac as arguments for @SuppresWarnings are not formally documented. While the strings are similar to those accepted by the -Xlint and -Xdoclint options, even that correspondence is not formally documented.

Solution

The set of strings recognized by javac should be documented.

Specification

The "man" page is modified as follows:

 :   Enables or disables specific groups of checks in documentation comments.

     *group* can have one of the following values: 
-    `accessibility`, `html`, `missing`, `reference`, `syntax`
+    `accessibility`, `html`, `missing`, `reference`, `syntax`.

     The variable *access* specifies the minimum visibility level of classes and
     members that the `-Xdoclint` option checks. It can have one of the
@@ -495,6 +495,9 @@ file system locations may be directories, JAR files or JMOD files.

     The default *access* level is `private`.

+    When prefixed by `doclint:`, the *group* names and `all` can be used with `@SuppressWarnings`
+    to suppress warnings about documentation comments in parts of the code being compiled.
+
     For more information about these groups of checks, see the [DocLint](javadoc.html#doclint)
     section of the `javadoc` command documentation. 
     The `-Xdoclint` option is disabled by default in the `javac` command.
@@ -611,6 +614,10 @@ file system locations may be directories, JAR files or JMOD files.

     -   `none`: Disables all warnings.

+    With the exception of `all` and `none`, the keys can be used with
+    the `@SuppressWarnings` annotation to suppress warnings in a part
+    of the source code being compiled.
+
     See [Examples of Using -Xlint keys].

 <a id="option-Xmaxerrs">`-Xmaxerrs` *number*</a>

jdk.compiler module-info.java is modified as follows:

diff --git a/src/jdk.compiler/share/classes/module-info.java b/src/jdk.compiler/share/classes/module-info.java
index d65de5f8111..1a588289d8d 100644
--- a/src/jdk.compiler/share/classes/module-info.java
+++ b/src/jdk.compiler/share/classes/module-info.java
@@ -59,6 +59,70 @@
  * {@code jdk.zipfs} module, must be available if the compiler is to be able
  * to read JAR files.
  *
+ * <h3>SuppressWarnings</h3>
+ *
+ * JLS {@jls 9.6.4.5} specifies a number of strings that can be used to
+ * suppress warnings that may be generated by a Java compiler.
+ *
+ * In addition, <em>javac</em> also supports other strings that can be used
+ * to suppress other kinds of warnings. The following table lists all the
+ * strings that can be used with {@code @SuppressWarnings}.
+ *
+ * <table class="striped">
+ *     <caption>Strings supported by {@code SuppressWarnings}</caption>
+ * <thead>
+ * <tr><th>String<th>Suppress Warnings About ...
+ * </thead>
+ * <tbody>
+ * <tr><th scope="row">{@code auxiliaryclass}       <td>an auxiliary class that is hidden in a source file, and is used
+ *                                                      from other files
+ * <tr><th scope="row">{@code cast}                 <td>use of unnecessary casts
+ * <tr><th scope="row">{@code classfile}            <td>issues related to classfile contents
+ * <tr><th scope="row">{@code deprecation}          <td>use of deprecated items
+ * <tr><th scope="row">{@code dep-ann}              <td>items marked as deprecated in a documentation comment but not
+ *                                                      using the {@code @Deprecated} annotation
+ * <tr><th scope="row">{@code divzero}              <td>division by constant integer {@code 0}
+ * <tr><th scope="row">{@code empty}                <td>empty statement after {@code if}
+ * <tr><th scope="row">{@code exports}              <td>issues regarding module exports
+ * <tr><th scope="row">{@code fallthrough}          <td>falling through from one case of a {@code switch} statement to
+ *                                                      the next
+ * <tr><th scope="row">{@code finally}              <td>{@code finally} clauses that do not terminate normally
+ * <tr><th scope="row">{@code missing-explicit-ctor} <td>missing explicit constructors in public and protected classes
+ *                                                      in exported packages
+ * <tr><th scope="row">{@code module}               <td>module system related issues
+ * <tr><th scope="row">{@code opens}                <td>issues regarding module opens
+ * <tr><th scope="row">{@code overloads}            <td>issues regarding method overloads
+ * <tr><th scope="row">{@code overrides}            <td>issues regarding method overrides
+ * <tr><th scope="row">{@code path}                 <td>invalid path elements on the command line
+ * <tr><th scope="row">{@code preview}              <td>use of preview language features
+ * <tr><th scope="row">{@code rawtypes}             <td>use of raw types
+ * <tr><th scope="row">{@code removal}              <td>use of API that has been marked for removal
+ * <tr><th scope="row">{@code requires-automatic}   <td>use of automatic modules in the {@code requires} clauses
+ * <tr><th scope="row">{@code requires-transitive-automatic} <td>automatic modules in {@code requires transitive}
+ * <tr><th scope="row">{@code serial}               <td>{@link java.base/java.io.Serializable Serializable} classes
+ *                                                      that do not have a {@code serialVersionUID} field, or other
+ *                                                      suspect declarations in {@code Serializable} and
+ *                                                      {@link java.base/java.io.Externalizable Externalizable} classes
+ *                                                      and interfaces
+ * <tr><th scope="row">{@code static}               <td>accessing a static member using an instance
+ * <tr><th scope="row">{@code strictfp}             <td>unnecessary use of the {@code strictfp} modifier
+ * <tr><th scope="row">{@code synchronization}      <td>synchronization attempts on instances of value-based classes
+ * <tr><th scope="row">{@code text-blocks}          <td>inconsistent white space characters in text block indentation
+ * <tr><th scope="row">{@code try}                  <td>issues relating to use of {@code try} blocks
+ *                                                      (that is, try-with-resources)
+ * <tr><th scope="row">{@code unchecked}            <td>unchecked operations
+ * <tr><th scope="row">{@code varargs}              <td>potentially unsafe vararg methods
+ * <tr><th scope="row">{@code doclint:accessibility} <td>accessibility issues found in documentation comments
+ * <tr><th scope="row">{@code doclint:all}          <td>all issues found in documentation comments
+ * <tr><th scope="row">{@code doclint:html}         <td>HTML issues found in documentation comments
+ * <tr><th scope="row">{@code doclint:missing}      <td>missing items in documentation comments
+ * <tr><th scope="row">{@code doclint:reference}    <td>reference issues found in documentation comments
+ * <tr><th scope="row">{@code doclint:syntax}       <td>syntax issues found in documentation comments
+ * </tbody>
+ * </table>
+ *
  * @toolGuide javac
  *
  * @provides java.util.spi.ToolProvider