RFR: JDK-8303689: javac -Xlint could/should report on "dangling" doc comments
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. ------------- Commit messages: - JDK-8303689: javac -Xlint could/should report on "dangling" doc comments Changes: https://git.openjdk.org/jdk/pull/18527/files Webrev: https://webrevs.openjdk.org/?repo=jdk&pr=18527&range=00 Issue: https://bugs.openjdk.org/browse/JDK-8303689 Stats: 477 lines in 60 files changed: 368 ins; 5 del; 104 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
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.
Would this be the first lint -- not doclint -- warning related to comments, let alone doc comments? ------------- PR Comment: https://git.openjdk.org/jdk/pull/18527#issuecomment-2024106466
On Wed, 27 Mar 2024 22:41:33 GMT, Pavel Rappo <prappo@openjdk.org> wrote:
Would this be the first lint -- not doclint -- warning related to comments, let alone doc comments?
No. `-Xlint:dep-ann` correlates `@Deprecated` annotations with `@deprecated` tags in doc comments.
src/jdk.javadoc/share/man/javadoc.1 line 111:
109: source code with the \f[V]javac\f[R] option \f[V]-Xlint\f[R], or more 110: specifically, \f[V]-Xlint:dangling-doc-comments\f[R]. 111: Within a source file, you may use suppress any warnings generated by
Typo? Suggestion:
Within a source file, you may suppress any warnings generated by
Thanks; I'll check the underlying original. ------------- PR Comment: https://git.openjdk.org/jdk/pull/18527#issuecomment-2024162355 PR Review Comment: https://git.openjdk.org/jdk/pull/18527#discussion_r1542157047
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.
Javadoc changes look trivially good. I only note that the javadoc man page diff contains some unrelated changes. ------------- PR Comment: https://git.openjdk.org/jdk/pull/18527#issuecomment-2024116236
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.
src/jdk.javadoc/share/man/javadoc.1 line 111:
109: source code with the \f[V]javac\f[R] option \f[V]-Xlint\f[R], or more 110: specifically, \f[V]-Xlint:dangling-doc-comments\f[R]. 111: Within a source file, you may use suppress any warnings generated by
Typo? Suggestion: Within a source file, you may suppress any warnings generated by ------------- PR Review Comment: https://git.openjdk.org/jdk/pull/18527#discussion_r1542131487
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.
lgtm ------------- Marked as reviewed by vromero (Reviewer). PR Review: https://git.openjdk.org/jdk/pull/18527#pullrequestreview-1967750057
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.
The build changes look okay. Do you have any plan of going through all the Java modules and fixing the issues, or opening JBS issues to have them fixed? Or will these lint warnings remain disabled for the foreseeable future? ------------- Marked as reviewed by ihse (Reviewer). PR Review: https://git.openjdk.org/jdk/pull/18527#pullrequestreview-1976255818
On Wed, 3 Apr 2024 10:01:37 GMT, Magnus Ihse Bursie <ihse@openjdk.org> wrote:
Jonathan Gibbons has updated the pull request incrementally with one additional commit since the last revision:
adjust call for `saveDanglingDocComments` for enum members
The build changes look okay.
Do you have any plan of going through all the Java modules and fixing the issues, or opening JBS issues to have them fixed? Or will these lint warnings remain disabled for the foreseeable future?
@magicus
The build changes look okay.
Do you have any plan of going through all the Java modules and fixing the issues, or opening JBS issues to have them fixed? Or will these lint warnings remain disabled for the foreseeable future?
The plan is to create an umbrella bug to clean up the individual modules. There is interest to clean up `java.base`, to keep that one free of any warnings, and I can see that the lang tools modules will get cleaner up as well. It will be up to other component teams to decide if and when to clean up other parts of the system. Once this work has been integrated, it is relatively easy to enable the warnings for a module and to fix the ensuing issues. Since any changes "only" involve comments, it should be reasonably easy to fix them, unlike some pervasive other warnings, like `this-escape`. ------------- PR Comment: https://git.openjdk.org/jdk/pull/18527#issuecomment-2052174696
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
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: call `saveDanglingDocComments` for local variable declarations ------------- Changes: - all: https://git.openjdk.org/jdk/pull/18527/files - new: https://git.openjdk.org/jdk/pull/18527/files/56d6dcac..3f745431 Webrevs: - full: https://webrevs.openjdk.org/?repo=jdk&pr=18527&range=02 - incr: https://webrevs.openjdk.org/?repo=jdk&pr=18527&range=01-02 Stats: 10 lines in 1 file changed: 5 ins; 2 del; 3 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
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 with a new target base due to a merge or a rebase. The incremental webrev excludes the unrelated changes brought in by the merge/rebase. The pull request contains five additional commits since the last revision: - improve handling of ignorable doc comments suppress warning when building test code - Merge remote-tracking branch 'upstream/master' into 8303689.dangling-comments - call `saveDanglingDocComments` for local variable declarations - adjust call for `saveDanglingDocComments` for enum members - JDK-8303689: javac -Xlint could/should report on "dangling" doc comments ------------- Changes: - all: https://git.openjdk.org/jdk/pull/18527/files - new: https://git.openjdk.org/jdk/pull/18527/files/3f745431..f3670e7a Webrevs: - full: https://webrevs.openjdk.org/?repo=jdk&pr=18527&range=03 - incr: https://webrevs.openjdk.org/?repo=jdk&pr=18527&range=02-03 Stats: 42074 lines in 1058 files changed: 18282 ins; 15937 del; 7855 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
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: update test ------------- Changes: - all: https://git.openjdk.org/jdk/pull/18527/files - new: https://git.openjdk.org/jdk/pull/18527/files/f3670e7a..8ad8b818 Webrevs: - full: https://webrevs.openjdk.org/?repo=jdk&pr=18527&range=04 - incr: https://webrevs.openjdk.org/?repo=jdk&pr=18527&range=03-04 Stats: 6 lines in 1 file changed: 6 ins; 0 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
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 with a new target base due to a merge or a rebase. The pull request now contains seven commits: - Merge with upstream/master - update test - improve handling of ignorable doc comments suppress warning when building test code - Merge remote-tracking branch 'upstream/master' into 8303689.dangling-comments - call `saveDanglingDocComments` for local variable declarations - adjust call for `saveDanglingDocComments` for enum members - JDK-8303689: javac -Xlint could/should report on "dangling" doc comments ------------- Changes: https://git.openjdk.org/jdk/pull/18527/files Webrev: https://webrevs.openjdk.org/?repo=jdk&pr=18527&range=05 Stats: 488 lines in 61 files changed: 389 ins; 3 del; 96 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
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 with a new target base due to a merge or a rebase. The pull request now contains 10 commits: - Merge with upstream/master - Merge remote-tracking branch 'upstream/master' into 8303689.dangling-comments - Merge remote-tracking branch 'upstream/master' into 8303689.dangling-comments - Merge with upstream/master - update test - improve handling of ignorable doc comments suppress warning when building test code - Merge remote-tracking branch 'upstream/master' into 8303689.dangling-comments - call `saveDanglingDocComments` for local variable declarations - adjust call for `saveDanglingDocComments` for enum members - JDK-8303689: javac -Xlint could/should report on "dangling" doc comments ------------- Changes: https://git.openjdk.org/jdk/pull/18527/files Webrev: https://webrevs.openjdk.org/?repo=jdk&pr=18527&range=06 Stats: 485 lines in 59 files changed: 387 ins; 3 del; 95 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
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 with a new target base due to a merge or a rebase. The pull request now contains 11 commits: - Merge remote-tracking branch 'upstream/master' into 8303689.dangling-comments # Please enter a commit message to explain why this merge is necessary, # especially if it merges an updated upstream into a topic branch. # # Lines starting with '#' will be ignored, and an empty message aborts # the commit. - Merge with upstream/master - Merge remote-tracking branch 'upstream/master' into 8303689.dangling-comments - Merge remote-tracking branch 'upstream/master' into 8303689.dangling-comments - Merge with upstream/master - update test - improve handling of ignorable doc comments suppress warning when building test code - Merge remote-tracking branch 'upstream/master' into 8303689.dangling-comments - call `saveDanglingDocComments` for local variable declarations - adjust call for `saveDanglingDocComments` for enum members - ... and 1 more: https://git.openjdk.org/jdk/compare/1c238d43...16a265a2 ------------- Changes: https://git.openjdk.org/jdk/pull/18527/files Webrev: https://webrevs.openjdk.org/?repo=jdk&pr=18527&range=07 Stats: 485 lines in 59 files changed: 387 ins; 3 del; 95 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
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
On Thu, 25 Apr 2024 23:24:07 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:
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
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 ------------- Changes: - all: https://git.openjdk.org/jdk/pull/18527/files - new: https://git.openjdk.org/jdk/pull/18527/files/39689a52..48e8b0a2 Webrevs: - full: https://webrevs.openjdk.org/?repo=jdk&pr=18527&range=09 - incr: https://webrevs.openjdk.org/?repo=jdk&pr=18527&range=08-09 Stats: 1 line in 1 file changed: 0 ins; 0 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
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
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
participants (5)
-
Jonathan Gibbons
-
Magnus Ihse Bursie
-
Pavel Rappo
-
Phil Race
-
Vicente Romero