From 3eece6e941035e091e8ece7dd44a1837417c9b87 Mon Sep 17 00:00:00 2001 From: Pavel Rappo Date: Fri, 15 Nov 2024 10:20:08 +0000 Subject: [PATCH] 8341907: javac -Xlint should ignore /// on first line of source file Reviewed-by: jjg --- .../com/sun/tools/javac/code/Lint.java | 2 +- .../sun/tools/javac/parser/JavacParser.java | 11 ++++- .../danglingDocComments/JBangException1.java | 19 +++++++++ .../JBangException2.enabled.out | 2 + .../danglingDocComments/JBangException2.java | 19 +++++++++ .../JBangException3.enabled.out | 2 + .../danglingDocComments/JBangException3.java | 22 ++++++++++ .../JBangExceptionTest.java | 40 +++++++++++++++++++ 8 files changed, 115 insertions(+), 2 deletions(-) create mode 100644 test/langtools/tools/javac/danglingDocComments/JBangException1.java create mode 100644 test/langtools/tools/javac/danglingDocComments/JBangException2.enabled.out create mode 100644 test/langtools/tools/javac/danglingDocComments/JBangException2.java create mode 100644 test/langtools/tools/javac/danglingDocComments/JBangException3.enabled.out create mode 100644 test/langtools/tools/javac/danglingDocComments/JBangException3.java create mode 100644 test/langtools/tools/javac/danglingDocComments/JBangExceptionTest.java 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 d024dc75225..622c13d8b47 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 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"), 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 a93f5a9a794..0bbcd56293f 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 @@ 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. diff --git a/test/langtools/tools/javac/danglingDocComments/JBangException1.java b/test/langtools/tools/javac/danglingDocComments/JBangException1.java new file mode 100644 index 00000000000..123451aff7c --- /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 00000000000..8934c449e3b --- /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 00000000000..1514542f3fc --- /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 00000000000..9b08300a7c0 --- /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 00000000000..9e14dfc0b55 --- /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 00000000000..4308335f4c5 --- /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.