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

[Vicente Romero]

On Tue, 23 Sep 2025 17:18:45 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`
>
> Archie Cobbs has updated the pull request with a new target base due to a merge or a rebase. The incremental webrev excludes the unrelated changes brought in by the merge/rebase. The pull request contains nine additional commits since the last revision:
> 
>  - Merge branch 'master' into JDK-8366561 to get recent build fixes.
>  - Changes based on CSR review suggestions.
>  - 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.

lgtm

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

Marked as reviewed by vromero (Reviewer).

PR Review: https://git.openjdk.org/jdk/pull/27129#pullrequestreview-3274059729