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

[Jonathan Gibbons]

On Wed, 6 Nov 2024 23:18:01 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

>> 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 keyword is present.
>
> Number 3 seems to be the cleanest. I'll try it; thanks.

OK, but since we're not testing the files here with JBang, all that matters is the recognition of the overall comment, regardless of its content. But #3 is OK too.  The main thing is to have the keyword present so that any checkers scripts have explicit evidence that no comment is intended in these files.

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

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