dangling-doc-comments being a bit too picky

[David Lloyd]

The bug is at https://bugs.openjdk.org/browse/JDK-8341907 - sorry about the
formatting, I'm not sure how to switch it to "text" mode from "visual" mode
(it seems like some fields/bug types enter in text mode and some are stuck
in visual mode?).

On Thu, Oct 10, 2024 at 9:14 AM Pavel Rappo <pavel.rappo at oracle.com> wrote:

> 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
>
>

-- 
- DML • he/him
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.openjdk.org/pipermail/javadoc-dev/attachments/20241010/551a0b6e/attachment.htm>