-
Sub-task
-
Resolution: Delivered
-
P4
-
23
A new suboption is provided for the `javac` `-Xlint` option, to detect issues related to the placement of documentation comments in source code.
The name for the new suboption is `dangling-doc-comments`. The suboption can be specified explicitly (for example, `-Xlint:dangling-doc-comments`) or implicitly, as one of all the suboptions (for example, `-Xlint` or `-Xlint:all`).
When the suboption is enabled, `javac` will report any unexpected or misplaced documentation comments in the vicinity of a declaration, such as in the following situations:
* a documentation comment for a top-level class before any `package` or `import` declaration;
* a documentation comment for a declaration that appears after the first token of that declaration, such as after any annotations or other modifiers for the declaration; or
* any additional documentation comments before a declaration, which `javac` would otherwise ignore.
As with any suboption for `-Xlint`, warnings can be suppressed locally, using an `@SuppressWarnings` annotation on an enclosing declaration, specifying the names of the suboptions for the warnings to be suppressed.
Note: it is possible that when the suboption is enabled, `javac` may report some "false positives" if there are any decorative comments that begin with `/**` and thus may resemble a documentation comment. For example, comments using a line of asterisks before and after the rest of the comment text, to help make the comment "stand out". The remedy in such cases is to change the comment so that it does not begin with `/**` -- perhaps by changing at least the second asterisk to some other character.
The name for the new suboption is `dangling-doc-comments`. The suboption can be specified explicitly (for example, `-Xlint:dangling-doc-comments`) or implicitly, as one of all the suboptions (for example, `-Xlint` or `-Xlint:all`).
When the suboption is enabled, `javac` will report any unexpected or misplaced documentation comments in the vicinity of a declaration, such as in the following situations:
* a documentation comment for a top-level class before any `package` or `import` declaration;
* a documentation comment for a declaration that appears after the first token of that declaration, such as after any annotations or other modifiers for the declaration; or
* any additional documentation comments before a declaration, which `javac` would otherwise ignore.
As with any suboption for `-Xlint`, warnings can be suppressed locally, using an `@SuppressWarnings` annotation on an enclosing declaration, specifying the names of the suboptions for the warnings to be suppressed.
Note: it is possible that when the suboption is enabled, `javac` may report some "false positives" if there are any decorative comments that begin with `/**` and thus may resemble a documentation comment. For example, comments using a line of asterisks before and after the rest of the comment text, to help make the comment "stand out". The remedy in such cases is to change the comment so that it does not begin with `/**` -- perhaps by changing at least the second asterisk to some other character.