Summary

Add a new sub-option to javac -Xlint to report on issues related to documentation comments.

Problem

Documentation comments are those beginning /** and can be provided for use with the javadoc tool to generate API documentation.

It can be easy to put a documentation comment in the wrong place, and any such comments may be silently ignored. For example, a documentation comment may be placed near the top of a file, before a package declaration or import statement, instead of before the class or interface to which the comment applies. Or, an annotation may be added to a declaration before its documentation comment, so that the documentation comment no longer immediately precedes the beginning of the declaration, and will subsequently be missed.

Solution

A new sub-option for the -Xlint option is provided: -Xlint:dangling-doc-comments. As part of the -Xlint family, it can be enabled as part of -Xlint:all, or listed in a series of sub-options, such as -Xlint:dangling-doc-comments,rawtypes,this-escape. Within a source file, warnings can be suppressed by using @SuppressWarnings("dangling-doc-comments").

Some developers may use a style using comments beginning /**... to indicate "important" comments within a series of statements, some going as far as using /******** ... ********/ to provide a "boxed comment". To reduce the chance of false positive warnings, documentation comments on statements within a block of statements are ignored.

Specification

The javac man page is updated with a summary of the new -Xlint sub-option, and cross-referenced from the javadoc man page:

diff --git a/.../src/jdk.compiler/share/man/javac.md b/.../src/jdk.compiler/share/man/javac.md
index 514579b8c0..6a7fa454ee 100644
--- a/.../src/jdk.compiler/share/man/javac.md
+++ b/.../src/jdk.compiler/share/man/javac.md
@@ -546,6 +546,9 @@ file system locations may be directories, JAR files or JMOD files.

     -   `classfile`: Warns about the issues related to classfile contents.

+    -   `dangling-doc-comments`: Warns about extra or misplaced documentation
+         comments near the beginning of a declaration.
+
     -   `deprecation`: Warns about the use of deprecated items.

     -   `dep-ann`: Warns about the items marked as deprecated in `javadoc` but
diff --git a/.../src/jdk.javadoc/share/man/javadoc.md b/.../src/jdk.javadoc/share/man/javadoc.md
index af0b37eb17..64b91deaaf 100644
--- a/.../src/jdk.javadoc/share/man/javadoc.md
+++ b/.../src/jdk.javadoc/share/man/javadoc.md
@@ -57,6 +57,20 @@ either to recursively traverse a directory and its subdirectories, or to pass
 in an explicit list of package names. When you document individual source
 files, pass in a list of Java source file names.

+### Documentation Comments
+
+The `javadoc` tool uses the documentation comment, if any, that immediately 
+precedes the beginning of the declaration, whether that is an annotation, 
+modifier, or the name being declared. If there are multiple documentation 
+comments before the declaration, only the last one (closest to the declaration) 
+will be used.  If there are any documentation comments after the beginning of 
+the declaration, they will be ignored.  To check for any extra or misplaced
+documentation comments, compile your source code with the `javac` option
+`-Xlint`, or more specifically, `-Xlint:dangling-doc-comments`. Within a
+source file, you may suppress any warnings generated by these options
+by using `@SuppressWarnings("dangling-doc-comments")` on a suitable enclosing
+declaration.
+
 ### Conformance

 The standard doclet does not validate the content of documentation comments for

In addition, the jdk.compiler module-info.java file contains a table of values that may be used with @SuppressWarnings. The table is updated with a new row, for dancing-doc-comments.

@@ -153,6 +153,8 @@
  *                                                      from other files
  * <tr><th scope="row">{@code cast}                 <td>use of unnecessary casts
  * <tr><th scope="row">{@code classfile}            <td>issues related to classfile contents
+ * <tr><th scope="row">{@code dangling-doc-comments} <td>issues related to "dangling" documentation comments,
+ *                                                       not attached to a declaration
  * <tr><th scope="row">{@code deprecation}          <td>use of deprecated items
  * <tr><th scope="row">{@code dep-ann}              <td>items marked as deprecated in a documentation comment but not
  *                                                      using the {@code @Deprecated} annotation