RFR: 8303689: javac -Xlint could/should report on "dangling" doc comments [v9]

[Vicente Romero]

On Thu, 25 Apr 2024 23:24:07 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> Please review the updates to support a proposed new `-Xlint:dangling-doc-comments` option.
>> 
>> The work can be thought of as in 3 parts:
>> 
>> 1. An update to the `javac` internal class `DeferredLintHandler` so that it is possible to specify the appropriately configured `Lint` object when it is time to consider whether to generate the diagnostic or not.
>> 
>> 2. Updates to the `javac` front end to record "dangling docs comments" found near the beginning of a declaration, and to report them using an instance of `DeferredLintHandler`. This allows the warnings to be enabled or disabled using the standard mechanisms for `-Xlint` and `@SuppressWarnings`.  The procedure for handling dangling doc comments is described in this comment in `JavacParser`.
>> 
>>      *  Dangling documentation comments are handled as follows.
>>      *  1. {@code Scanner} adds all doc comments to a queue of
>>      *     recent doc comments. The queue is flushed whenever
>>      *     it is known that the recent doc comments should be
>>      *     ignored and should not cause any warnings.
>>      *  2. The primary documentation comment is the one obtained
>>      *     from the first token of any declaration.
>>      *     (using {@code token.getDocComment()}.
>>      *  3. At the end of the "signature" of the declaration
>>      *     (that is, before any initialization or body for the
>>      *     declaration) any other "recent" comments are saved
>>      *     in a map using the primary comment as a key,
>>      *     using this method, {@code saveDanglingComments}.
>>      *  4. When the tree node for the declaration is finally
>>      *     available, and the primary comment, if any,
>>      *     is "attached", (in {@link #attach}) any related
>>      *     dangling comments are also attached to the tree node
>>      *     by registering them using the {@link #deferredLintHandler}.
>>      *  5. (Later) Warnings may be genereated for the dangling
>>      *     comments, subject to the {@code -Xlint} and
>>      *     {@code @SuppressWarnings}.
>> 
>> 
>> 3.  Updates to the make files to disable the warnings in modules for which the 
>> warning is generated.  This is often because of the confusing use of `/**` to
>> create box or other standout comments.
>
> Jonathan Gibbons has updated the pull request incrementally with one additional commit since the last revision:
> 
>   revert need to disable warning

looks good

src/jdk.compiler/share/classes/com/sun/tools/javac/parser/JavacParser.java line 583:

> 581:      *     dangling comments are also attached to the tree node
> 582:      *     by registering them using the {@link #deferredLintHandler}.
> 583:      *  5. (Later) Warnings may be genereated for the dangling

typo: generated

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

Marked as reviewed by vromero (Reviewer).

PR Review: https://git.openjdk.org/jdk/pull/18527#pullrequestreview-2023792395
PR Review Comment: https://git.openjdk.org/jdk/pull/18527#discussion_r1580263826