RFR: 8366561: Improve documentation for how the -Xlint flag works

Archie Cobbs acobbs at openjdk.org
Mon Sep 8 16:58:44 UTC 2025


This is a documentation-only change to improve compiler documentation around the `-Xlint` flag and lint categories.

* Changes to `--help` output:
  * Note that `--enable-preview` disables the `preview` lint category as a side-effect

* Changes to `--help-extra` output:
  * Refer to "lint warning categories" instead of "warning categories" when appropriate (not all warnings are lint warnings)
  * Note that `-Xlint` enables all lint categories (sync with man page)
  * Note that some categories are enabled by default even without any `-Xlint` flags

* Changes to `--help-lint` output:
  * Refer to "lint warning categories" instead of "warning categories" when appropriate (not all warnings are lint warnings)
  * Sort lint categories and aliases alphabetically together
  * Indicate which lint categories are enabled by default with an asterisk
  * Tighten up "alias" verbiage and generalize it to work with future possible category aliases
  * Add a footer blurb clarifying that aliases are fully interchangeable with their primary keys

* Changes to `module-info.java` javadoc:
  * Clarify that `@SuppressWarnings` ignores unrecognized strings
  * Remove lint categories not actually supported by `@SuppressWarnings` from the list of such

* Changes to the `javac(1)` man page:
  * Sync with the above changes to `--help`, `--help-extra`, and `--help-lint`

-------------

Commit messages:
 - Minor code cleanup.
 - Clarify that "processing" is not supported by @SuppressWarnings.
 - Synchronize --help-extra and man page descriptions of the "-Xlint" flag.
 - Minor refactoring creating method Lint.getDefaults().
 - Update man page with the same improvements applied to help output.
 - Note that unrecognized strings in @SuppressWarnings annotations are ignored.
 - Documentation improvements relating to -Xlint and lint categories.

Changes: https://git.openjdk.org/jdk/pull/27129/files
  Webrev: https://webrevs.openjdk.org/?repo=jdk&pr=27129&range=00
  Issue: https://bugs.openjdk.org/browse/JDK-8366561
  Stats: 140 lines in 5 files changed: 55 ins; 31 del; 54 mod
  Patch: https://git.openjdk.org/jdk/pull/27129.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/27129/head:pull/27129

PR: https://git.openjdk.org/jdk/pull/27129


More information about the compiler-dev mailing list