8341907: javac -Xlint should ignore /// on first line of source file

Reviewed-by: jjg

src/jdk.compiler/share/classes/com/sun/tools/javac/code/Lint.java

@@ -181,7 +181,7 @@ public class Lint
         CLASSFILE("classfile"),
 
         /**
-         * Warn about"dangling" documentation comments,
+         * Warn about "dangling" documentation comments,
          * not attached to any declaration.
          */
         DANGLING_DOC_COMMENTS("dangling-doc-comments"),

src/jdk.compiler/share/classes/com/sun/tools/javac/parser/JavacParser.java

@@ -667,7 +667,8 @@ public class JavacParser implements Parser {
         var pos = c.getPos();
         if (pos != null) {
             deferredLintHandler.report(lint -> {
-                if (lint.isEnabled(Lint.LintCategory.DANGLING_DOC_COMMENTS)) {
+                if (lint.isEnabled(Lint.LintCategory.DANGLING_DOC_COMMENTS) &&
+                        !shebang(c, pos)) {
                     log.warning(Lint.LintCategory.DANGLING_DOC_COMMENTS,
                             pos, Warnings.DanglingDocComment);
                 }
@@ -675,6 +676,14 @@ public class JavacParser implements Parser {
         }
     }
 
+    /** Returns true for a comment that acts similarly to shebang in UNIX */
+    private boolean shebang(Comment c, JCDiagnostic.DiagnosticPosition pos) {
+        var src = log.currentSource();
+        return c.getStyle() == Comment.CommentStyle.JAVADOC_LINE &&
+                c.getPos().getStartPosition() == 0 &&
+                src.getLineNumber(pos.getEndPosition(src.getEndPosTable())) == 1;
+    }
+
     /**
      * Ignores any recent documentation comments found by the scanner,
      * such as those that cannot be associated with a nearby declaration.

test/langtools/tools/javac/danglingDocComments/JBangException1.java

@@ -0,0 +1,19 @@
+///usr/bin/env jbang "$0" "$@" ; exit $?
+// /nodynamiccopyright/
+
+/** A class comment */
+public class JBangException1 {
+
+    /**
+     * A method comment
+     *
+     * @param args a parameter comment
+     */
+    public static void main(String[] args) {
+        if (args.length == 0) {
+            System.out.println("Hello World!");
+        } else {
+            System.out.println("Hello " + args[0]);
+        }
+    }
+}

test/langtools/tools/javac/danglingDocComments/JBangException2.enabled.out

@@ -0,0 +1,2 @@
+JBangException2.java:1:1: compiler.warn.dangling.doc.comment
+1 warning

test/langtools/tools/javac/danglingDocComments/JBangException2.java

@@ -0,0 +1,19 @@
+/** /usr/bin/env jbang "$0" "$@" ; exit $? */
+// /nodynamiccopyright/
+
+/** A class comment */
+public class JBangException2 {
+
+    /**
+     * A method comment
+     *
+     * @param args a parameter comment
+     */
+    public static void main(String[] args) {
+        if (args.length == 0) {
+            System.out.println("Hello World!");
+        } else {
+            System.out.println("Hello " + args[0]);
+        }
+    }
+}

test/langtools/tools/javac/danglingDocComments/JBangException3.enabled.out

@@ -0,0 +1,2 @@
+JBangException3.java:1:1: compiler.warn.dangling.doc.comment
+1 warning

test/langtools/tools/javac/danglingDocComments/JBangException3.java

@@ -0,0 +1,22 @@
+/// A
+///  multiline
+///   dangling
+///    comment
+// /nodynamiccopyright/
+
+/** A class comment */
+public class JBangException3 {
+
+    /**
+     * A method comment
+     *
+     * @param args a parameter comment
+     */
+    public static void main(String[] args) {
+        if (args.length == 0) {
+            System.out.println("Hello World!");
+        } else {
+            System.out.println("Hello " + args[0]);
+        }
+    }
+}

test/langtools/tools/javac/danglingDocComments/JBangExceptionTest.java

@@ -0,0 +1,40 @@
+/*
+ * Copyright (c) 2024, Oracle and/or its affiliates. All rights reserved.
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ *
+ * This code is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
+ * or visit www.oracle.com if you need additional information or have any
+ * questions.
+ */
+
+/*
+ * @test
+ *
+ * @compile/ref=empty.out -XDrawDiagnostics JBangException1.java
+ * @compile/ref=empty.out -XDrawDiagnostics -Xlint:dangling-doc-comments JBangException1.java
+ *
+ * @compile/ref=empty.out -XDrawDiagnostics JBangException2.java
+ * @compile/ref=JBangException2.enabled.out -XDrawDiagnostics -Xlint:dangling-doc-comments JBangException2.java
+ *
+ * @compile/ref=empty.out -XDrawDiagnostics JBangException3.java
+ * @compile/ref=JBangException3.enabled.out -XDrawDiagnostics -Xlint:dangling-doc-comments JBangException3.java
+ */
+
+// The classes being tested reside in files separate from this one because
+// the classes need to provide the initial dangling comment, which would
+// otherwise interfere with the JTReg test comment. For similar reasons,
+// the files with test classes do __NOT__ have a copyright header.