<!DOCTYPE html>
<html>
<head>
<meta http-equiv="Content-Type" content="text/xhtml; charset=utf-8">
</head>
<body><div style="font-family: sans-serif;"><div class="markdown" style="white-space: normal;">
<p dir="auto">Hi,</p>
<p dir="auto">I noticed that Java 23 <code style="margin: 0 0; padding: 0 0.25em; border-radius: 3px; background-color: #F7F7F7;">javac -Xlint:dangling-doc-comments test.java</code><br>
where <code style="margin: 0 0; padding: 0 0.25em; border-radius: 3px; background-color: #F7F7F7;">test.java</code> is:</p>
<pre class="highlighted" style="margin-left: 15px; margin-right: 15px; padding: 5px; background-color: #F7F7F7; border-radius: 5px 5px 5px 5px; overflow-x: auto; max-width: 90vw; color: black;"><code style="margin: 0 0; border-radius: 3px; background-color: #F7F7F7; padding: 0px;"><span class="token comment" style="color: slategray;">///usr/bin/env jbang "$0" "$@" ; exit $?</span>
<span class="token comment" style="color: slategray;">/**
* test
*/</span>
<span class="token keyword" style="color: #07a;">public</span> <span class="token keyword" style="color: #07a;">class</span> test <span class="token punctuation" style="color: #999;">{</span>
<span class="token keyword" style="color: #07a;">public</span> <span class="token keyword" style="color: #07a;">static</span> <span class="token keyword" style="color: #07a;">void</span> <span class="token function" style="color: #DD4A68;">main</span><span class="token punctuation" style="color: #999;">(</span><span class="token class-name" style="color: #DD4A68;">String</span><span class="token punctuation" style="color: #999;">[</span><span class="token punctuation" style="color: #999;">]</span> args<span class="token punctuation" style="color: #999;">)</span> <span class="token punctuation" style="color: #999;">{</span>
<span class="token class-name" style="color: #DD4A68;">System</span><span class="token punctuation" style="color: #999;">.</span>out<span class="token punctuation" style="color: #999;">.</span><span class="token function" style="color: #DD4A68;">println</span><span class="token punctuation" style="color: #999;">(</span><span class="token string" style="color: #690;">"Javadoc should not complain about the 1st line"</span><span class="token punctuation" style="color: #999;">)</span><span class="token punctuation" style="color: #999;">;</span>
<span class="token punctuation" style="color: #999;">}</span>
<span class="token punctuation" style="color: #999;">}</span>
</code></pre>
<p dir="auto">Now result in:</p>
<pre style="margin-left: 15px; margin-right: 15px; padding: 5px; background-color: #F7F7F7; border-radius: 5px 5px 5px 5px; overflow-x: auto; max-width: 90vw;"><code style="margin: 0 0; border-radius: 3px; background-color: #F7F7F7; padding: 0px;">test.java:1: warning: [dangling-doc-comments] documentation comment is not attached to any declaration
///usr/bin/env jbang "$0" "$@" ; exit $?
^
1 warning
</code></pre>
<p dir="auto">which is unfortunate given that this top-line construct is a common thing in unix based shells to use for<br>
enabling scripts to run.</p>
<p dir="auto">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.</p>
<p dir="auto">Thus, it is unfortunate that this is flagged by the linter which IDE's are enabling and you end up with bug reports<br>
for something that is not actually a bug.</p>
<p dir="auto">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.</p>
<p dir="auto">i.e. it should let this pass:</p>
<pre style="margin-left: 15px; margin-right: 15px; padding: 5px; background-color: #F7F7F7; border-radius: 5px 5px 5px 5px; overflow-x: auto; max-width: 90vw;"><code style="margin: 0 0; border-radius: 3px; background-color: #F7F7F7; padding: 0px;">///usr/bin/env jbang "$0" "$@" ; exit $?
public class test
</code></pre>
<p dir="auto">but complain about</p>
<pre style="margin-left: 15px; margin-right: 15px; padding: 5px; background-color: #F7F7F7; border-radius: 5px 5px 5px 5px; overflow-x: auto; max-width: 90vw;"><code style="margin: 0 0; border-radius: 3px; background-color: #F7F7F7; padding: 0px;">/// An actual comment
public class test
</code></pre>
<p dir="auto">and</p>
<pre style="margin-left: 15px; margin-right: 15px; padding: 5px; background-color: #F7F7F7; border-radius: 5px 5px 5px 5px; overflow-x: auto; max-width: 90vw;"><code style="margin: 0 0; border-radius: 3px; background-color: #F7F7F7; padding: 0px;">package org.acme;
/// An actual comment
/**
* test
*/
public class test
</code></pre>
<p dir="auto">I'm happy to look into a PR for it but wanted to start with getting it recognized as bug/issue first.</p>
<p dir="auto">Could someone with the right powers open a bug for it?</p>
<p dir="auto">Thank you,<br>
/max<br>
<a href="https://xam.dk/about" style="color: #3983C4;">https://xam.dk/about</a></p>
</div>
</div>
</body>
</html>