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