diff --git a/src/jdk.compiler/share/classes/com/sun/tools/javac/code/Lint.java b/src/jdk.compiler/share/classes/com/sun/tools/javac/code/Lint.java index d024dc75225fa..622c13d8b4797 100644 --- a/src/jdk.compiler/share/classes/com/sun/tools/javac/code/Lint.java +++ b/src/jdk.compiler/share/classes/com/sun/tools/javac/code/Lint.java @@ -181,7 +181,7 @@ public enum LintCategory { CLASSFILE("classfile"), /** - * Warn about"dangling" documentation comments, + * Warn about "dangling" documentation comments, * not attached to any declaration. */ DANGLING_DOC_COMMENTS("dangling-doc-comments"), diff --git a/src/jdk.compiler/share/classes/com/sun/tools/javac/parser/JavacParser.java b/src/jdk.compiler/share/classes/com/sun/tools/javac/parser/JavacParser.java index a93f5a9a794b3..0bbcd56293f47 100644 --- a/src/jdk.compiler/share/classes/com/sun/tools/javac/parser/JavacParser.java +++ b/src/jdk.compiler/share/classes/com/sun/tools/javac/parser/JavacParser.java @@ -667,7 +667,8 @@ void reportDanglingDocComment(Comment c) { 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 @@ void reportDanglingDocComment(Comment c) { } } + /** 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. diff --git a/test/langtools/tools/javac/danglingDocComments/JBangException1.java b/test/langtools/tools/javac/danglingDocComments/JBangException1.java new file mode 100644 index 0000000000000..123451aff7c22 --- /dev/null +++ b/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]); + } + } +} \ No newline at end of file diff --git a/test/langtools/tools/javac/danglingDocComments/JBangException2.enabled.out b/test/langtools/tools/javac/danglingDocComments/JBangException2.enabled.out new file mode 100644 index 0000000000000..8934c449e3b46 --- /dev/null +++ b/test/langtools/tools/javac/danglingDocComments/JBangException2.enabled.out @@ -0,0 +1,2 @@ +JBangException2.java:1:1: compiler.warn.dangling.doc.comment +1 warning diff --git a/test/langtools/tools/javac/danglingDocComments/JBangException2.java b/test/langtools/tools/javac/danglingDocComments/JBangException2.java new file mode 100644 index 0000000000000..1514542f3fc2b --- /dev/null +++ b/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]); + } + } +} \ No newline at end of file diff --git a/test/langtools/tools/javac/danglingDocComments/JBangException3.enabled.out b/test/langtools/tools/javac/danglingDocComments/JBangException3.enabled.out new file mode 100644 index 0000000000000..9b08300a7c007 --- /dev/null +++ b/test/langtools/tools/javac/danglingDocComments/JBangException3.enabled.out @@ -0,0 +1,2 @@ +JBangException3.java:1:1: compiler.warn.dangling.doc.comment +1 warning diff --git a/test/langtools/tools/javac/danglingDocComments/JBangException3.java b/test/langtools/tools/javac/danglingDocComments/JBangException3.java new file mode 100644 index 0000000000000..9e14dfc0b553e --- /dev/null +++ b/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]); + } + } +} \ No newline at end of file diff --git a/test/langtools/tools/javac/danglingDocComments/JBangExceptionTest.java b/test/langtools/tools/javac/danglingDocComments/JBangExceptionTest.java new file mode 100644 index 0000000000000..4308335f4c56d --- /dev/null +++ b/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.