> 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:

  adjust call for `saveDanglingDocComments` for enum members

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

Changes:
  - all: https://git.openjdk.org/jdk/pull/18527/files
  - new: https://git.openjdk.org/jdk/pull/18527/files/3d6f1f95..56d6dcac

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jdk&pr=18527&range=01
 - incr: https://webrevs.openjdk.org/?repo=jdk&pr=18527&range=00-01

  Stats: 5 lines in 1 file changed: 3 ins; 2 del; 0 mod
  Patch: https://git.openjdk.org/jdk/pull/18527.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/18527/head:pull/18527

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

Reply via email to