Re: RFR: 8303689: javac -Xlint could/should report on "dangling" doc comments [v9]
On Thu, 25 Apr 2024 23:24:07 GMT, Jonathan Gibbons 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
Re: RFR: 8303689: javac -Xlint could/should report on "dangling" doc comments [v9]
> 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
-
Changes:
- all: https://git.openjdk.org/jdk/pull/18527/files
- new: https://git.openjdk.org/jdk/pull/18527/files/16a265a2..39689a52
Webrevs:
- full: https://webrevs.openjdk.org/?repo=jdk=18527=08
- incr: https://webrevs.openjdk.org/?repo=jdk=18527=07-08
Stats: 3 lines in 1 file changed: 0 ins; 2 del; 1 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
