[prev in list] [next in list] [prev in thread] [next in thread] 

List:       openjdk-2d-dev
Subject:    Integrated: 8303689: javac -Xlint could/should report on "dangling" doc comments
From:       Jonathan Gibbons <jjg () openjdk ! org>
Date:       2024-04-26 19:49:56
Message-ID: jz5iSs8rS6B9ZP2l3HbT7UR9gdQiXvxyQFGqikRLN7U=.584799e9-55c0-4a22-b62f-e30406cfe8ea () github ! com
[Download RAW message or body]

On Wed, 27 Mar 2024 22:04:30 GMT, Jonathan Gibbons <jjg@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.

This pull request has now been integrated.

Changeset: a920af23
Author:    Jonathan Gibbons <jjg@openjdk.org>
URL:       https://git.openjdk.org/jdk/commit/a920af233a11592af113f456f7608cb59dd1617e
                
Stats:     482 lines in 58 files changed: 385 ins; 3 del; 94 mod

8303689: javac -Xlint could/should report on "dangling" doc comments

Reviewed-by: vromero, ihse, prr

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

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


[prev in list] [next in list] [prev in thread] [next in thread] 

Configure | About | News | Add a list | Sponsored by KoreLogic