dangling-doc-comments being a bit too picky

[David Lloyd]

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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.openjdk.org/pipermail/javadoc-dev/attachments/20241010/8950c90b/attachment-0001.htm>