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
