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&pr=18527&range=08 - incr: https://webrevs.openjdk.org/?repo=jdk&pr=18527&range=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