[prev in list] [next in list] [prev in thread] [next in thread]
List: openjdk-2d-dev
Subject: Re: RFR: 8303689: javac -Xlint could/should report on "dangling" doc comments [v10]
From: Phil Race <prr () openjdk ! org>
Date: 2024-04-26 19:34:00
Message-ID: SD0S716mdRSViTfaViQgFYEkmR7WmBalQQe3_FI7VQc=.b83407a8-0c84-4ed9-8b56-adf6db1a2e0c () github ! com
[Download RAW message or body]
On Fri, 26 Apr 2024 16:04:09 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.
>
> Jonathan Gibbons has updated the pull request incrementally with one additional \
> commit since the last revision:
> fix typo
Marked as reviewed by prr (Reviewer).
-------------
PR Review: https://git.openjdk.org/jdk/pull/18527#pullrequestreview-2025744069
[prev in list] [next in list] [prev in thread] [next in thread]
Configure |
About |
News |
Add a list |
Sponsored by KoreLogic