I can open a bug for that Max.
On Wed, Oct 9, 2024 at 12:40 PM Max Rydahl Andersen <mande...@redhat.com>
wrote:
> Hi,
>
> I noticed that Java 23 javac -Xlint:dangling-doc-comments test.java
> where test.java is:
>
> ///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
>
--
- DML • he/him
