Summary

Improve compiler documentation around the -Xlint flag and lint categories.

Problem

The compiler documentation can be improved to clarify how the -Xlint flag works. For example, it's not clear that -Xlint is the same as -Xlint:all, or that without any -Xlint flags at all, there is a default set of lint categories that get enabled, and what those defaults are.

Also, the module-info.java man page includes lint categories under the description of @SuppressWarnings that are not actually supported by @SuppressWarnings (such as options). It should only list those categories that are actually supported by @SuppressWarnings.

Solution

Update the output of --help, --help-extra, --help-lint, the javac(1) man page, and the module-info.java Javadoc for module jdk.compiler.

Specification

Changes to javac --help:

--- x0  2025-09-09 15:15:08.815412206 -0500
+++ x1  2025-09-09 15:15:09.059702199 -0500
@@ -13,7 +13,7 @@
   -deprecation
         Output source locations where deprecated APIs are used
   --enable-preview
-        Enable preview language features.
+        Enable preview language features. Also disables the 'preview' lint category.
         To be used in conjunction with either -source or --release.
   -encoding <encoding>         Specify character encoding used by source files
   -endorseddirs <dirs>         Override location of endorsed standards path

Changes to javac --help-extra:

--- x0  2025-09-09 15:15:09.158528861 -0500
+++ x1  2025-09-09 15:15:09.333207226 -0500
@@ -33,11 +33,14 @@
         a qualified package name or a package name prefix followed by '.*',
         which expands to all sub-packages of the given package. Each <package>
         can be prefixed with '-' to disable checks for the specified package(s).
-  -Xlint                       Enable recommended warning categories
+  -Xlint
+        Enable recommended lint warning categories. In this release, all
+        available lint warning categories are recommended.
   -Xlint:<key>(,<key>)*
-        Warning categories to enable or disable, separated by comma.
-        Precede a key by '-' to disable the specified warning.
-        Use --help-lint to see the supported keys.
+        Lint warning categories to enable or disable, separated by comma.
+        Precede a key by '-' to disable the specified category. Use
+        '--help-lint' to show supported keys and which categories are
+        enabled by default.
   -Xmaxerrs <number>           Set the maximum number of errors to print
   -Xmaxwarns <number>          Set the maximum number of warnings to print
   -Xpkginfo:{always,legacy,nonempty}

Changes to javac --help-lint:

--- x0  2025-09-09 15:15:09.422584295 -0500
+++ x1  2025-09-09 15:15:09.603213110 -0500
@@ -1,21 +1,17 @@
 The supported keys for -Xlint are:
-    all                  Enable all warning categories
+    all                  Enable all lint warning categories
     auxiliaryclass       Warn about an auxiliary class that is hidden in a source file, and is used from other files.
     cast                 Warn about use of unnecessary casts.
     classfile            Warn about issues related to classfile contents.
     dangling-doc-comments Warn about dangling documentation comments, not attached to any declaration.
-    deprecation          Warn about use of deprecated items.
     dep-ann              Warn about items marked as deprecated in JavaDoc but not using the @Deprecated annotation.
+    deprecation          Warn about use of deprecated items.
     divzero              Warn about division by constant integer 0.
     empty                Warn about empty statement after if.
     exports              Warn about issues regarding module exports.
     fallthrough          Warn about falling through from one case of a switch statement to the next.
     finally              Warn about finally clauses that do not terminate normally.
     identity             Warn about uses of value-based classes where an identity class is expected.
-    synchronization      Warn about synchronization attempts on instances of value-based classes.
-                         This key is a deprecated alias for 'identity', which has the same uses and
-                         effects. Users are encouraged to use the 'identity' category for all future
-                         and existing uses of 'synchronization'.
     incubating           Warn about use of incubating modules.
     lossy-conversions    Warn about possible lossy conversions in compound assignment.
     missing-explicit-ctor Warn about missing explicit constructors in public and protected classes in exported packages.
@@ -27,21 +23,27 @@
     overloads            Warn about issues regarding method overloads.
     overrides            Warn about issues regarding method overrides.
     path                 Warn about invalid path elements on the command line.
+    preview              Warn about use of preview language features.
     processing           Warn about issues regarding annotation processing.
     rawtypes             Warn about use of raw types.
     removal              Warn about use of API that has been marked for removal.
     requires-automatic   Warn about use of automatic modules in the requires clauses.
     requires-transitive-automatic Warn about automatic modules in requires transitive.
+    restricted           Warn about use of restricted methods.
     serial               Warn about Serializable classes that do not have a serialVersionUID field. 
                          Also warn about other suspect declarations in Serializable and Externalizable classes and interfaces.
     static               Warn about accessing a static member using an instance.
     strictfp             Warn about unnecessary use of the strictfp modifier.
+    synchronization      Deprecated alias for 'identity' with an identical effect. Users are encouraged to use
+                         'identity' instead of 'synchronization' for all current and future uses.
     text-blocks          Warn about inconsistent white space characters in text block indentation.
     this-escape          Warn when a constructor invokes a method that could be overriden in an external subclass.
                          Such a method would execute before the subclass constructor completes its initialization.
     try                  Warn about issues relating to use of try blocks (i.e. try-with-resources).
     unchecked            Warn about unchecked operations.
     varargs              Warn about potentially unsafe vararg methods.
-    preview              Warn about use of preview language features.
-    restricted           Warn about use of restricted methods.
-    none                 Disable all warning categories
+    none                 Disable all lint warning categories
+The following lint warning categories are enabled by default:
+    dep-ann, identity, incubating, module, opens, preview, removal, requires-transitive-automatic, strictfp.
+Categories and their aliases can be used interchangeably; for example, the flag
+'-Xlint:identity,synchronization' would be redundant.

Changes to module-info.java Javadoc for module jdk.compiler:

diff --git a/src/jdk.compiler/share/classes/module-info.java b/src/jdk.compiler/share/classes/module-info.java
index 33cff9379f2..46ada3a12e7 100644
--- a/src/jdk.compiler/share/classes/module-info.java
+++ b/src/jdk.compiler/share/classes/module-info.java
@@ -141,7 +141,8 @@
  *
  * 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}.
+ * strings that are recognized by <em>javac</em> in {@code @SuppressWarnings}
+ * annotations. Unrecognized strings are ignored.
  *
  * <table class="striped">
  *     <caption>Strings supported by {@code SuppressWarnings}</caption>
@@ -152,7 +153,6 @@
  * <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 dangling-doc-comments} <td>issues related to "dangling" documentation comments,
  *                                                       not attached to a declaration
  * <tr><th scope="row">{@code deprecation}          <td>use of deprecated items
@@ -165,7 +165,6 @@
  *                                                      the next
  * <tr><th scope="row">{@code finally}              <td>{@code finally} clauses that do not terminate normally
  * <tr><th scope="row">{@code identity}             <td>use of a value-based class where an identity class is expected
- * <tr><th scope="row">{@code incubating}           <td>use of incubating modules
  * <tr><th scope="row">{@code lossy-conversions}    <td>possible lossy conversions in compound assignment
  * <tr><th scope="row">{@code missing-explicit-ctor} <td>missing explicit constructors in public and protected classes
  *                                                      in exported packages
@@ -173,13 +172,12 @@
  * <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 restricted}           <td>use of restricted methods
  * <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 restricted}           <td>use of restricted methods
  * <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
@@ -187,11 +185,9 @@
  *                                                      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;
- *                                                      this key is a deprecated alias for {@code identity}, which has
- *                                                      the same uses and effects. Users are encouraged to use the
- *                                                      {@code identity} category for all future and existing uses of
- *                                                      {@code synchronization}
+ * <tr><th scope="row">{@code synchronization}      <td>deprecated alias for {@code identity} with an identical effect.
+ *                                                      Users are encouraged to use {@code identity} instead of
+ *                                                      {@code synchronization} for all current and future uses.
  * <tr><th scope="row">{@code text-blocks}          <td>inconsistent white space characters in text block indentation
  * <tr><th scope="row">{@code this-escape}          <td>superclass constructor leaking {@code this} before subclass initialized
  * <tr><th scope="row">{@code try}                  <td>issues relating to use of {@code try} blocks
@@ -207,6 +203,25 @@
  * </tbody>
  * </table>
  *
+ * All of the non-{@code docllint:} strings listed above may also be used with the {@code -Xlint} command line flag.
+ * The {@code -Xlint} flag also supports these strings not supported by {@code @SuppressWarnings}:
+ *
+ * <table class="striped">
+ *     <caption>Strings supported by {@code -Xlint} but not {@code SuppressWarnings}</caption>
+ * <thead>
+ * <tr><th>String<th>Warnings Related To ...
+ * </thead>
+ * <tbody>
+ * <tr><th scope="row">{@code classfile}            <td>issues related to classfile contents
+ * <tr><th scope="row">{@code incubating}           <td>use of incubating modules
+ * <tr><th scope="row">{@code options}              <td>issues relating to use of command line options
+ * <tr><th scope="row">{@code output-file-clash}    <td>output files being overwritten due to filename clashes
+ * <tr><th scope="row">{@code path}                 <td>invalid path elements on the command line
+ * <tr><th scope="row">{@code processing}           <td>issues regarding annotation processing
+ * <tr><th scope="row">{@code restricted}           <td>use of restricted methods
+ * </tbody>
+ * </table>
+ *
  * @toolGuide javac
  *
  * @provides java.util.spi.ToolProvider

Changes to the javac(1) man page:

diff --git a/src/jdk.compiler/share/man/javac.md b/src/jdk.compiler/share/man/javac.md
index 997023487b0..b8243cc78fb 100644
--- a/src/jdk.compiler/share/man/javac.md
+++ b/src/jdk.compiler/share/man/javac.md
@@ -208,8 +208,8 @@ ### Standard Options
     `-deprecation` option is shorthand for `-Xlint:deprecation`.

 <a id="option-enable-preview">`--enable-preview`</a>
-:   Enables preview language features. Used in conjunction with either
-    [`-source`](#option-source) or [`--release`](#option-release).
+:   Enables preview language features. Also disables the `preview` lint category.
+    Used in conjunction with either [`-source`](#option-source) or [`--release`](#option-release).

 <a id="option-encoding">`-encoding` *encoding*</a>
 :   Specifies character encoding used by source files, such as EUC-JP and
@@ -557,11 +557,11 @@ ### Extra Options
     section of the `javadoc` command documentation.

 <a id="option-Xlint">`-Xlint`</a>
-:   Enables all recommended warnings. In this release, enabling all available
-    warnings is recommended.
+:   Enables recommended lint warning categories. In this release, all available
+    lint warning categories are recommended.

 <a id="option-Xlint-custom">`-Xlint:`\[`-`\]*key*(`,`\[`-`\]*key*)\*</a>
-:   Enables and/or disables warning categories using the one or more of the keys described
+:   Enables and/or disables lint warning categories using the one or more of the keys described
     below separated by commas. The keys `all` and `none` enable or disable all categories
     (respectively); other keys enable the corresponding category, or disable it if preceded
     by a hyphen (`-`).
@@ -648,10 +648,9 @@ ### Extra Options

     -   `strictfp`: Warns about unnecessary use of the `strictfp` modifier.

-    -   `synchronization`: Warns about synchronization attempts on instances
-        of value-based classes. This key is a deprecated alias for `identity`,
-        which has the same uses and effects. Users are encouraged to use the
-        `identity` category for all future and existing uses of `synchronization`.
+    -   `synchronization`: Deprecated alias for `identity` with an identical
+        effect. Users are encouraged to use `identity` instead of `synchronization`
+        for all current and future uses.

     -   `text-blocks`: Warns about inconsistent white space characters in text
         block indentation.
@@ -667,9 +666,13 @@ ### Extra Options

     -   `none`: Disables all warning categories.

-    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.
+    The keys listed above may be used in `@SuppressWarnings` annotations to suppress
+    warnings within the annotated declaration, with the exception of: `all`, `none`,
+    `classfile`, `incubating`, `options`, `output-file-clash`, `processing`, and `path`.
+
+    By default, the following lint warning categories are enabled: `dep-ann`, `identity`,
+    `incubating`, `module`, `opens`, `preview`, `removal`, `requires-transitive-automatic`,
+    and `strictfp`.

     See [Examples of Using -Xlint keys].