dangling-doc-comments being a bit too picky

[Max Rydahl Andersen]

Appreciated. Thanks.

/max
https://about.me/maxandersen


On Thu, Oct 10, 2024 at 16.27 David Lloyd <david.lloyd at redhat.com> wrote:

> 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/20241011/7b5bf6f8/attachment-0001.htm>