dangling-doc-comments being a bit too picky

[Max Rydahl Andersen]

Hi,

I noticed that Java 23 `javac -Xlint:dangling-doc-comments test.java`
where `test.java` is:

```java
///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");
     }
}
```

Now result in:

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

which is unfortunate given that this top-line construct is a common 
thing in unix based shells to use for
enabling scripts to run.

In this case I'm using jbang, but it is also common for others - kotlin 
script, go script, scala and others use it; been valid for longer than 
Java existed.

Thus, it is unfortunate that this is flagged by the linter which IDE's 
are enabling and you end up with bug reports
for something that is not actually a bug.

My suggestion is that the linter would not complain if the line is the 
very first line in the file, and there is no space.

i.e. it should let this pass:


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

public class test
```

but complain about

```
/// An actual comment

public class test
```

and

```
package org.acme;
/// An actual comment

/**
  * test
  */
public class test
```

I'm happy to look into a PR for it but wanted to start with getting it 
recognized as bug/issue first.

Could someone with the right powers open a bug for it?

Thank you,
/max
https://xam.dk/about
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.openjdk.org/pipermail/javadoc-dev/attachments/20241004/0ebc2270/attachment.htm>