RFR: 8341907: javac -Xlint should ignore /// on first line of source file

[Jonathan Gibbons]

On Wed, 6 Nov 2024 11:31:02 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

> Please review this PR to exempt the [trick that JBang uses][] from the "dangling comment" lint introduced in JDK 23. For more information see this PR's JBS issue and its comment section.
> 
> The fix makes sure that the warning is not issued if it relates to a leading `///` comment. For simplicity and similarity with the shebang construct, the comment should start from the first character of the file, and not a more permissive first non-whitespace character of the file.
> 
> Since I'm not an expert in `java.compiler`, I'm unsure if my code intercepts warning in the most appropriate layer. Please double-check that.
> 
> Skimming through the tests which I used for inspiration, `test/langtools/tools/javac/danglingDocComments`, I was unsure why they compile itself first without any `/ref=` construct. The test I introduced here does not do this; am I missing something?
> 
> [trick that JBang uses]: https://www.jbang.dev/documentation/guide/latest/usage.html

src/jdk.compiler/share/classes/com/sun/tools/javac/parser/JavacParser.java line 672:

> 670:                 if (lint.isEnabled(Lint.LintCategory.DANGLING_DOC_COMMENTS) &&
> 671:                         (c.getStyle() != Comment.CommentStyle.JAVADOC_LINE ||
> 672:                                 c.getPos().getStartPosition() != 0)) {

For consideration, you could further refine the test by making sure it is a single line comment (perhaps optionally terminated by a newline).  In other words, maybe the warning should be given if the leading comment is a multi-line comment -- which would unlikely be a JBang-style comment.

test/langtools/tools/javac/danglingDocComments/JBangExceptionTest.java line 14:

> 12: // the classes need to provide the initial dangling comment, which would
> 13: // otherwise interfere with the JTReg test comment. For similar reasons,
> 14: // the files with test classes do __NOT__ have a copyright header.

FYI, the normal guidance for source files that cannot follow standard stylistic guidance (such as files with tabs etc) is to dynamically generate the files, which is medium easy these days using text blocks.   That being said, that advice does not work well in this case because the `jtreg` infrastructure for `@compile` tags does not work for generated files.

In this case, I would recommend working the text string `nodynamiccopyright` into the head of the two JBang files.  There are two or three possibilities.

1. Just put the word `nodynamiccopyright` at the end of the first line. Syntactically, it would be a command name, but such a command would never be executed after the `exit` statement.
2. Put a comment `#nodynamiccopyright` at the end of the first line.
3. Put a separate Java comment on the second line, using either an end-of-line comment or traditional comment. It might then be reasonably detected and taken into account by any automated scripts that ensure copyright headers are present unless that work is present.

-------------

PR Review Comment: https://git.openjdk.org/jdk/pull/21923#discussion_r1831708608
PR Review Comment: https://git.openjdk.org/jdk/pull/21923#discussion_r1831706267