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

[Pavel Rappo]

On Wed, 6 Nov 2024 21:06:46 GMT, Jonathan Gibbons <jjg 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.

I admit, I thought about it initially, but couldn't quickly come up with a simple and robust way to figure out if a comment tree spans a single line. I'm not yet comfortable working with compiler coordinate system (incl. source positions). If you propose such a way, I'd happily incorporate it.

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

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