dangling-doc-comments being a bit too picky

[Pavel Rappo]

I would appreciate it if you could submit a bug, David.

> On 10 Oct 2024, at 15:08, David Lloyd <david.lloyd at redhat.com> wrote:
> 
> I can open a bug for that Max.
> 
> On Wed, Oct 9, 2024 at 12:40 PM Max Rydahl Andersen <manderse at 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