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

[Archie Cobbs]

On Fri, 5 Sep 2025 22:12:52 GMT, Archie Cobbs <acobbs at openjdk.org> wrote:

> 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
>   * 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
>   * Put them in a separate table instead
> 
> * Changes to the `javac(1)` man page:
>   * Sync with the above changes to `--help`, `--help-extra`, and `--help-lint`

This pull request has now been integrated.

Changeset: 5b1ebbb2
Author:    Archie Cobbs <acobbs at openjdk.org>
URL:       https://git.openjdk.org/jdk/commit/5b1ebbb2713e54511cb695d1d6f7f6b7f827b2a7
Stats:     171 lines in 5 files changed: 96 ins; 31 del; 44 mod

8366561: Improve documentation for how the -Xlint flag works

Reviewed-by: vromero

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

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