Summary

DocLint should not report a dangling comment warning for a /// comment that starts the source file.

Problem

javac/javadoc has recently introduced two features. The first one is a DocLint warning for dangling doc comments. The second one is a new style of doc comments, ///.

Combined, these features might clash with the JBang feature that uses the first line of a file to provide a command line to start the script that the file represents. Such a line starts with /// and is seen by javac/javadoc as a comment.

If there are other comments in between that line and the next documentable declaration, that line would be considered a dangling comment, which will be warned about. Although such a warning could be avoided by placing @SuppressWarnings("dangling-doc-comments") on the declaration in question, it's annoying enough to warrant special treatment proposed below.

Solution

Do not warn about a single-line /// dangling comment if it starts the file.

Specification

Here are the current specifications for the affected option. Given the level of detail of those specifications, it makes sense NOT to change them:

• src/jdk.compiler/share/man/javac.md

  -   `dangling-doc-comments`: Warns about extra or misplaced documentation
       comments near the beginning of a declaration.

• src/jdk.javadoc/share/man/javadoc.md

  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.