java 23 java doc linter reports [dangling-doc-comments] documentation comment is not attached to any declaration

[maxandersen]

code like this :

///usr/bin/env jbang "$0" "$@" ; exit $?

/**
 * test
 */
public class test {

    public static void main(String[] args) {
        System.out.println("Javadoc should not complain about the 1st line");
    }
}

when compiled with: javac -Xlint:dangling-doc-comments test.java
gets flagged with:

test.java:1: warning: [dangling-doc-comments] documentation comment is not attached to any declaration
///usr/bin/env jbang "$0" "$@" ; exit $?
^
1 warning

this can/will show up in IDE's too and is annoying as its otherwise completely valid :)

I'm opening this issue to document and explain - and hopefully find a way to tweak the javac linter to be less critical.

There are multiple ways to deal with it:

0. Ignore the warning as it is incorrect. But you will have to explain it a 1000 times (this issue helps)
1. make it two slashes instead of three - //usr/bin/env jbang ... but then /.test.java wont work on Windows where the 3rd slash makes it recognized as a UNC path.
2. remove the line completely - but then you cannot do ./test.java on any OS
3. try get javac lint fix to not complain about this syntax that been valid for longer than Java been around.

if anyone up for helping with #3 lets try make that happen :)