On Wed, 27 Mar 2024 22:04:30 GMT, Jonathan Gibbons <j...@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 <j...@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