From a920af233a11592af113f456f7608cb59dd1617e Mon Sep 17 00:00:00 2001 From: Jonathan Gibbons Date: Fri, 26 Apr 2024 19:47:06 +0000 Subject: [PATCH] 8303689: javac -Xlint could/should report on "dangling" doc comments Reviewed-by: vromero, ihse, prr --- make/CompileDemos.gmk | 2 +- make/CompileToolsJdk.gmk | 4 +- make/GenerateLinkOptData.gmk | 3 +- make/modules/java.desktop/Java.gmk | 4 +- make/modules/java.management/Java.gmk | 4 +- make/modules/java.naming/Java.gmk | 4 +- make/modules/java.security.jgss/Java.gmk | 4 +- make/modules/java.security.sasl/Java.gmk | 4 +- make/modules/java.sql.rowset/Java.gmk | 4 +- make/modules/java.sql/Java.gmk | 4 +- make/modules/java.xml.crypto/Java.gmk | 4 +- make/modules/java.xml/Java.gmk | 4 +- make/modules/jdk.accessibility/Java.gmk | 26 +++ make/modules/jdk.crypto.cryptoki/Java.gmk | 26 +++ make/modules/jdk.hotspot.agent/Java.gmk | 4 +- make/modules/jdk.internal.le/Java.gmk | 4 +- make/modules/jdk.internal.vm.ci/Java.gmk | 4 +- make/modules/jdk.jdi/Java.gmk | 4 +- make/modules/jdk.jfr/Java.gmk | 4 +- make/modules/jdk.security.auth/Java.gmk | 26 +++ make/modules/jdk.zipfs/Java.gmk | 27 ++++ make/test/BuildTestLib.gmk | 2 +- .../com/sun/tools/javac/api/JavacTrees.java | 7 +- .../tools/javac/code/DeferredLintHandler.java | 18 ++- .../com/sun/tools/javac/code/Lint.java | 8 +- .../com/sun/tools/javac/comp/Annotate.java | 4 +- .../com/sun/tools/javac/comp/Attr.java | 10 +- .../com/sun/tools/javac/comp/Check.java | 28 ++-- .../com/sun/tools/javac/comp/TypeEnter.java | 4 +- .../sun/tools/javac/parser/JavaTokenizer.java | 14 ++ .../sun/tools/javac/parser/JavacParser.java | 150 +++++++++++++++++- .../com/sun/tools/javac/parser/Lexer.java | 16 +- .../sun/tools/javac/parser/ParserFactory.java | 6 +- .../com/sun/tools/javac/parser/Scanner.java | 23 ++- .../com/sun/tools/javac/parser/Tokens.java | 3 +- .../sun/tools/javac/parser/VirtualParser.java | 8 +- .../tools/javac/resources/compiler.properties | 3 + .../tools/javac/resources/javac.properties | 5 +- .../sun/tools/javac/tree/DocTreeMaker.java | 7 +- .../share/classes/module-info.java | 4 +- src/jdk.compiler/share/man/javac.1 | 3 + .../internal/tool/JavadocMemberEnter.java | 4 +- src/jdk.javadoc/share/man/javadoc.1 | 16 ++ .../OverrideChecks/6199153/T6199153.java | 2 +- .../DanglingDocCommentsClass.enabled.out | 7 + .../DanglingDocCommentsClass.java | 46 ++++++ .../DanglingDocCommentsEnum.enabled.out | 8 + .../DanglingDocCommentsEnum.java | 37 +++++ .../tools/javac/danglingDocComments/empty.out | 0 .../depDocComment/DeprecatedDocComment3.java | 6 +- .../DanglingDocCommentWarning.java | 29 ++++ .../platform/PreviewAPIsWithRelease.java | 2 +- .../tools/javac/warnings/DepAnn.java | 2 +- .../tools/javac/warnings/Deprecation.java | 2 +- .../NestedDeprecation/NestedDeprecation.java | 2 +- .../tools/javac/warnings/Unchecked.java | 2 +- .../warnings/VerifyLintDescriptions.java | 4 +- .../javac/warnings/suppress/T6480588.java | 2 +- 58 files changed, 575 insertions(+), 89 deletions(-) create mode 100644 make/modules/jdk.accessibility/Java.gmk create mode 100644 make/modules/jdk.crypto.cryptoki/Java.gmk create mode 100644 make/modules/jdk.security.auth/Java.gmk create mode 100644 make/modules/jdk.zipfs/Java.gmk create mode 100644 test/langtools/tools/javac/danglingDocComments/DanglingDocCommentsClass.enabled.out create mode 100644 test/langtools/tools/javac/danglingDocComments/DanglingDocCommentsClass.java create mode 100644 test/langtools/tools/javac/danglingDocComments/DanglingDocCommentsEnum.enabled.out create mode 100644 test/langtools/tools/javac/danglingDocComments/DanglingDocCommentsEnum.java create mode 100644 test/langtools/tools/javac/danglingDocComments/empty.out create mode 100644 test/langtools/tools/javac/diags/examples/DanglingDocCommentWarning/DanglingDocCommentWarning.java diff --git a/make/CompileDemos.gmk b/make/CompileDemos.gmk index 9339250c4fb..599ce9842e4 100644 --- a/make/CompileDemos.gmk +++ b/make/CompileDemos.gmk @@ -216,7 +216,7 @@ $(eval $(call SetupBuildDemo, SampleTree, \ )) $(eval $(call SetupBuildDemo, TableExample, \ - DISABLED_WARNINGS := rawtypes unchecked deprecation this-escape, \ + DISABLED_WARNINGS := rawtypes unchecked deprecation this-escape dangling-doc-comments, \ DEMO_SUBDIR := jfc, \ )) diff --git a/make/CompileToolsJdk.gmk b/make/CompileToolsJdk.gmk index 50ffe73a096..feba5d8a902 100644 --- a/make/CompileToolsJdk.gmk +++ b/make/CompileToolsJdk.gmk @@ -1,5 +1,5 @@ # -# Copyright (c) 2011, 2023, Oracle and/or its affiliates. All rights reserved. +# Copyright (c) 2011, 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 @@ -55,7 +55,7 @@ $(eval $(call SetupJavaCompilation, BUILD_TOOLS_JDK, \ build/tools/depend \ , \ BIN := $(BUILDTOOLS_OUTPUTDIR)/jdk_tools_classes, \ - DISABLED_WARNINGS := options, \ + DISABLED_WARNINGS := dangling-doc-comments options, \ JAVAC_FLAGS := \ --add-exports java.desktop/sun.awt=ALL-UNNAMED \ --add-exports java.base/sun.text=ALL-UNNAMED \ diff --git a/make/GenerateLinkOptData.gmk b/make/GenerateLinkOptData.gmk index e7d6962fb79..576bc4190b9 100644 --- a/make/GenerateLinkOptData.gmk +++ b/make/GenerateLinkOptData.gmk @@ -1,5 +1,5 @@ # -# Copyright (c) 2016, 2021, Oracle and/or its affiliates. All rights reserved. +# Copyright (c) 2016, 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 @@ -43,6 +43,7 @@ $(eval $(call SetupJavaCompilation, CLASSLIST_JAR, \ SMALL_JAVA := false, \ SRC := $(TOPDIR)/make/jdk/src/classes, \ INCLUDES := build/tools/classlist, \ + DISABLED_WARNINGS := dangling-doc-comments, \ BIN := $(BUILDTOOLS_OUTPUTDIR)/classlist_classes, \ JAR := $(SUPPORT_OUTPUTDIR)/classlist.jar, \ )) diff --git a/make/modules/java.desktop/Java.gmk b/make/modules/java.desktop/Java.gmk index 66ef88dcf14..7cc9cf47034 100644 --- a/make/modules/java.desktop/Java.gmk +++ b/make/modules/java.desktop/Java.gmk @@ -1,5 +1,5 @@ # -# Copyright (c) 2020, 2023, Oracle and/or its affiliates. All rights reserved. +# Copyright (c) 2020, 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 @@ -23,7 +23,7 @@ # questions. # -DISABLED_WARNINGS_java += lossy-conversions this-escape +DISABLED_WARNINGS_java += dangling-doc-comments lossy-conversions this-escape DOCLINT += -Xdoclint:all/protected \ '-Xdoclint/package:java.*,javax.*' COPY += .gif .png .wav .txt .xml .css .pf diff --git a/make/modules/java.management/Java.gmk b/make/modules/java.management/Java.gmk index 781370b2e18..7a337946cd7 100644 --- a/make/modules/java.management/Java.gmk +++ b/make/modules/java.management/Java.gmk @@ -1,5 +1,5 @@ # -# Copyright (c) 2020, 2023, Oracle and/or its affiliates. All rights reserved. +# Copyright (c) 2020, 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 @@ -23,7 +23,7 @@ # questions. # -DISABLED_WARNINGS_java += this-escape +DISABLED_WARNINGS_java += dangling-doc-comments this-escape DOCLINT += -Xdoclint:all/protected \ '-Xdoclint/package:java.*,javax.*' diff --git a/make/modules/java.naming/Java.gmk b/make/modules/java.naming/Java.gmk index a7ade637af5..207329f5944 100644 --- a/make/modules/java.naming/Java.gmk +++ b/make/modules/java.naming/Java.gmk @@ -1,5 +1,5 @@ # -# Copyright (c) 2020, 2023, Oracle and/or its affiliates. All rights reserved. +# Copyright (c) 2020, 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 @@ -23,7 +23,7 @@ # questions. # -DISABLED_WARNINGS_java += this-escape +DISABLED_WARNINGS_java += dangling-doc-comments this-escape DOCLINT += -Xdoclint:all/protected \ '-Xdoclint/package:java.*,javax.*' diff --git a/make/modules/java.security.jgss/Java.gmk b/make/modules/java.security.jgss/Java.gmk index 781370b2e18..7a337946cd7 100644 --- a/make/modules/java.security.jgss/Java.gmk +++ b/make/modules/java.security.jgss/Java.gmk @@ -1,5 +1,5 @@ # -# Copyright (c) 2020, 2023, Oracle and/or its affiliates. All rights reserved. +# Copyright (c) 2020, 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 @@ -23,7 +23,7 @@ # questions. # -DISABLED_WARNINGS_java += this-escape +DISABLED_WARNINGS_java += dangling-doc-comments this-escape DOCLINT += -Xdoclint:all/protected \ '-Xdoclint/package:java.*,javax.*' diff --git a/make/modules/java.security.sasl/Java.gmk b/make/modules/java.security.sasl/Java.gmk index 269a1195b6a..136b311a827 100644 --- a/make/modules/java.security.sasl/Java.gmk +++ b/make/modules/java.security.sasl/Java.gmk @@ -1,5 +1,5 @@ # -# Copyright (c) 2023, Oracle and/or its affiliates. All rights reserved. +# Copyright (c) 2023, 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 @@ -23,4 +23,4 @@ # questions. # -DISABLED_WARNINGS_java += this-escape +DISABLED_WARNINGS_java += dangling-doc-comments this-escape diff --git a/make/modules/java.sql.rowset/Java.gmk b/make/modules/java.sql.rowset/Java.gmk index 2dc60515a1b..9f430a7121b 100644 --- a/make/modules/java.sql.rowset/Java.gmk +++ b/make/modules/java.sql.rowset/Java.gmk @@ -1,5 +1,5 @@ # -# Copyright (c) 2020, 2023, Oracle and/or its affiliates. All rights reserved. +# Copyright (c) 2020, 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 @@ -23,6 +23,8 @@ # questions. # +DISABLED_WARNINGS_java += dangling-doc-comments this-escape + DOCLINT += -Xdoclint:all/protected \ '-Xdoclint/package:java.*,javax.*' CLEAN_FILES += $(wildcard \ diff --git a/make/modules/java.sql/Java.gmk b/make/modules/java.sql/Java.gmk index 781370b2e18..7a337946cd7 100644 --- a/make/modules/java.sql/Java.gmk +++ b/make/modules/java.sql/Java.gmk @@ -1,5 +1,5 @@ # -# Copyright (c) 2020, 2023, Oracle and/or its affiliates. All rights reserved. +# Copyright (c) 2020, 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 @@ -23,7 +23,7 @@ # questions. # -DISABLED_WARNINGS_java += this-escape +DISABLED_WARNINGS_java += dangling-doc-comments this-escape DOCLINT += -Xdoclint:all/protected \ '-Xdoclint/package:java.*,javax.*' diff --git a/make/modules/java.xml.crypto/Java.gmk b/make/modules/java.xml.crypto/Java.gmk index 53e282aca27..9ee19c8c302 100644 --- a/make/modules/java.xml.crypto/Java.gmk +++ b/make/modules/java.xml.crypto/Java.gmk @@ -1,5 +1,5 @@ # -# Copyright (c) 2020, 2023, Oracle and/or its affiliates. All rights reserved. +# Copyright (c) 2020, 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 @@ -23,7 +23,7 @@ # questions. # -DISABLED_WARNINGS_java += this-escape +DISABLED_WARNINGS_java += dangling-doc-comments this-escape DOCLINT += -Xdoclint:all/protected \ '-Xdoclint/package:java.*,javax.*' diff --git a/make/modules/java.xml/Java.gmk b/make/modules/java.xml/Java.gmk index cf6f1753f1c..22c1dde2c2b 100644 --- a/make/modules/java.xml/Java.gmk +++ b/make/modules/java.xml/Java.gmk @@ -1,5 +1,5 @@ # -# Copyright (c) 2020, 2023, Oracle and/or its affiliates. All rights reserved. +# Copyright (c) 2020, 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 @@ -23,7 +23,7 @@ # questions. # -DISABLED_WARNINGS_java += lossy-conversions this-escape +DISABLED_WARNINGS_java += dangling-doc-comments lossy-conversions this-escape DOCLINT += -Xdoclint:all/protected \ '-Xdoclint/package:$(call CommaList, javax.xml.catalog javax.xml.datatype \ javax.xml.transform javax.xml.validation javax.xml.xpath)' diff --git a/make/modules/jdk.accessibility/Java.gmk b/make/modules/jdk.accessibility/Java.gmk new file mode 100644 index 00000000000..fc8b2f832d7 --- /dev/null +++ b/make/modules/jdk.accessibility/Java.gmk @@ -0,0 +1,26 @@ +# +# 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. Oracle designates this +# particular file as subject to the "Classpath" exception as provided +# by Oracle in the LICENSE file that accompanied this code. +# +# 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. +# + +DISABLED_WARNINGS_java += dangling-doc-comments diff --git a/make/modules/jdk.crypto.cryptoki/Java.gmk b/make/modules/jdk.crypto.cryptoki/Java.gmk new file mode 100644 index 00000000000..fc8b2f832d7 --- /dev/null +++ b/make/modules/jdk.crypto.cryptoki/Java.gmk @@ -0,0 +1,26 @@ +# +# 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. Oracle designates this +# particular file as subject to the "Classpath" exception as provided +# by Oracle in the LICENSE file that accompanied this code. +# +# 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. +# + +DISABLED_WARNINGS_java += dangling-doc-comments diff --git a/make/modules/jdk.hotspot.agent/Java.gmk b/make/modules/jdk.hotspot.agent/Java.gmk index 52cb0c8d91a..333d28a5aa0 100644 --- a/make/modules/jdk.hotspot.agent/Java.gmk +++ b/make/modules/jdk.hotspot.agent/Java.gmk @@ -1,5 +1,5 @@ # -# Copyright (c) 2020, 2023, Oracle and/or its affiliates. All rights reserved. +# Copyright (c) 2020, 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 @@ -24,5 +24,5 @@ # DISABLED_WARNINGS_java += rawtypes serial cast static overrides \ - fallthrough this-escape + dangling-doc-comments fallthrough this-escape COPY += .gif .png .properties diff --git a/make/modules/jdk.internal.le/Java.gmk b/make/modules/jdk.internal.le/Java.gmk index 75d99b8d2bb..4c952b63574 100644 --- a/make/modules/jdk.internal.le/Java.gmk +++ b/make/modules/jdk.internal.le/Java.gmk @@ -1,5 +1,5 @@ # -# Copyright (c) 2020, 2023, Oracle and/or its affiliates. All rights reserved. +# Copyright (c) 2020, 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 @@ -23,6 +23,6 @@ # questions. # -DISABLED_WARNINGS_java += this-escape +DISABLED_WARNINGS_java += dangling-doc-comments this-escape COPY += .properties .caps .txt diff --git a/make/modules/jdk.internal.vm.ci/Java.gmk b/make/modules/jdk.internal.vm.ci/Java.gmk index 0dd5af1f3ea..6bf8ad5e74c 100644 --- a/make/modules/jdk.internal.vm.ci/Java.gmk +++ b/make/modules/jdk.internal.vm.ci/Java.gmk @@ -1,5 +1,5 @@ # -# Copyright (c) 2020, 2023, Oracle and/or its affiliates. All rights reserved. +# Copyright (c) 2020, 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 @@ -23,7 +23,7 @@ # questions. # -DISABLED_WARNINGS_java += this-escape +DISABLED_WARNINGS_java += dangling-doc-comments this-escape # -parameters provides method's parameters information in class file, # JVMCI compilers make use of that information for various sanity checks. diff --git a/make/modules/jdk.jdi/Java.gmk b/make/modules/jdk.jdi/Java.gmk index 2e7cf805bc0..12ec29986b9 100644 --- a/make/modules/jdk.jdi/Java.gmk +++ b/make/modules/jdk.jdi/Java.gmk @@ -1,5 +1,5 @@ # -# Copyright (c) 2020, 2023, Oracle and/or its affiliates. All rights reserved. +# Copyright (c) 2020, 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 @@ -23,6 +23,8 @@ # questions. # +DISABLED_WARNINGS_java += dangling-doc-comments this-escape + EXCLUDES += \ com/sun/tools/example/debug/bdi \ com/sun/tools/example/debug/event \ diff --git a/make/modules/jdk.jfr/Java.gmk b/make/modules/jdk.jfr/Java.gmk index 207256fde20..d07f9117c2d 100644 --- a/make/modules/jdk.jfr/Java.gmk +++ b/make/modules/jdk.jfr/Java.gmk @@ -1,5 +1,5 @@ # -# Copyright (c) 2020, 2023, Oracle and/or its affiliates. All rights reserved. +# Copyright (c) 2020, 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 @@ -23,6 +23,6 @@ # questions. # -DISABLED_WARNINGS_java += exports +DISABLED_WARNINGS_java += dangling-doc-comments exports COPY := .xsd .xml .dtd .ini JAVAC_FLAGS := -XDstringConcat=inline diff --git a/make/modules/jdk.security.auth/Java.gmk b/make/modules/jdk.security.auth/Java.gmk new file mode 100644 index 00000000000..fc8b2f832d7 --- /dev/null +++ b/make/modules/jdk.security.auth/Java.gmk @@ -0,0 +1,26 @@ +# +# 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. Oracle designates this +# particular file as subject to the "Classpath" exception as provided +# by Oracle in the LICENSE file that accompanied this code. +# +# 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. +# + +DISABLED_WARNINGS_java += dangling-doc-comments diff --git a/make/modules/jdk.zipfs/Java.gmk b/make/modules/jdk.zipfs/Java.gmk new file mode 100644 index 00000000000..0771884172f --- /dev/null +++ b/make/modules/jdk.zipfs/Java.gmk @@ -0,0 +1,27 @@ +# +# 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. Oracle designates this +# particular file as subject to the "Classpath" exception as provided +# by Oracle in the LICENSE file that accompanied this code. +# +# 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. +# + +DISABLED_WARNINGS_java += dangling-doc-comments + diff --git a/make/test/BuildTestLib.gmk b/make/test/BuildTestLib.gmk index 00642a1e7cf..d48f263f6f9 100644 --- a/make/test/BuildTestLib.gmk +++ b/make/test/BuildTestLib.gmk @@ -64,7 +64,7 @@ $(eval $(call SetupJavaCompilation, BUILD_TEST_LIB_JAR, \ BIN := $(TEST_LIB_SUPPORT)/test-lib_classes, \ HEADERS := $(TEST_LIB_SUPPORT)/test-lib_headers, \ JAR := $(TEST_LIB_SUPPORT)/test-lib.jar, \ - DISABLED_WARNINGS := try deprecation rawtypes unchecked serial cast removal preview, \ + DISABLED_WARNINGS := try deprecation rawtypes unchecked serial cast removal preview dangling-doc-comments, \ JAVAC_FLAGS := --add-exports java.base/sun.security.util=ALL-UNNAMED \ --add-exports java.base/jdk.internal.classfile=ALL-UNNAMED \ --add-exports java.base/jdk.internal.classfile.attribute=ALL-UNNAMED \ diff --git a/src/jdk.compiler/share/classes/com/sun/tools/javac/api/JavacTrees.java b/src/jdk.compiler/share/classes/com/sun/tools/javac/api/JavacTrees.java index 081367fa26a..45c76071f8b 100644 --- a/src/jdk.compiler/share/classes/com/sun/tools/javac/api/JavacTrees.java +++ b/src/jdk.compiler/share/classes/com/sun/tools/javac/api/JavacTrees.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2005, 2023, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2005, 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 @@ -1059,6 +1059,11 @@ public class JavacTrees extends DocTrees { return ""; } + @Override + public JCDiagnostic.DiagnosticPosition getPos() { + return null; + } + @Override public int getSourcePos(int index) { return offset + index; diff --git a/src/jdk.compiler/share/classes/com/sun/tools/javac/code/DeferredLintHandler.java b/src/jdk.compiler/share/classes/com/sun/tools/javac/code/DeferredLintHandler.java index 94d121ad04d..9fba9b5318b 100644 --- a/src/jdk.compiler/share/classes/com/sun/tools/javac/code/DeferredLintHandler.java +++ b/src/jdk.compiler/share/classes/com/sun/tools/javac/code/DeferredLintHandler.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2011, 2013, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2011, 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 @@ -52,10 +52,15 @@ public class DeferredLintHandler { return instance; } + /** The Lint to use when {@link #immediate(Lint)} is used, + * instead of {@link #setPos(DiagnosticPosition)}. */ + private Lint immediateLint; + @SuppressWarnings("this-escape") protected DeferredLintHandler(Context context) { context.put(deferredLintHandlerKey, this); this.currentPos = IMMEDIATE_POSITION; + immediateLint = Lint.instance(context); } /**An interface for deferred lint reporting - loggers passed to @@ -63,7 +68,7 @@ public class DeferredLintHandler { * {@link #flush(DiagnosticPosition) } is invoked. */ public interface LintLogger { - void report(); + void report(Lint lint); } private DiagnosticPosition currentPos; @@ -77,7 +82,7 @@ public class DeferredLintHandler { */ public void report(LintLogger logger) { if (currentPos == IMMEDIATE_POSITION) { - logger.report(); + logger.report(immediateLint); } else { ListBuffer loggers = loggersQueue.get(currentPos); if (loggers == null) { @@ -89,11 +94,11 @@ public class DeferredLintHandler { /**Invoke all {@link LintLogger}s that were associated with the provided {@code pos}. */ - public void flush(DiagnosticPosition pos) { + public void flush(DiagnosticPosition pos, Lint lint) { ListBuffer loggers = loggersQueue.get(pos); if (loggers != null) { for (LintLogger lintLogger : loggers) { - lintLogger.report(); + lintLogger.report(lint); } loggersQueue.remove(pos); } @@ -112,7 +117,8 @@ public class DeferredLintHandler { /**{@link LintLogger}s passed to subsequent invocations of * {@link #report(LintLogger) } will be invoked immediately. */ - public DiagnosticPosition immediate() { + public DiagnosticPosition immediate(Lint lint) { + immediateLint = lint; return setPos(IMMEDIATE_POSITION); } 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 92b2a773ffa..d024dc75225 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 @@ -1,5 +1,5 @@ /* - * Copyright (c) 2005, 2023, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2005, 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 @@ -180,6 +180,12 @@ public class Lint */ CLASSFILE("classfile"), + /** + * Warn about"dangling" documentation comments, + * not attached to any declaration. + */ + DANGLING_DOC_COMMENTS("dangling-doc-comments"), + /** * Warn about use of deprecated items. */ diff --git a/src/jdk.compiler/share/classes/com/sun/tools/javac/comp/Annotate.java b/src/jdk.compiler/share/classes/com/sun/tools/javac/comp/Annotate.java index 71c9d59cb27..40a2da35488 100644 --- a/src/jdk.compiler/share/classes/com/sun/tools/javac/comp/Annotate.java +++ b/src/jdk.compiler/share/classes/com/sun/tools/javac/comp/Annotate.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2003, 2022, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2003, 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 @@ -254,7 +254,7 @@ public class Annotate { DiagnosticPosition prevLintPos = deferPos != null ? deferredLintHandler.setPos(deferPos) - : deferredLintHandler.immediate(); + : deferredLintHandler.immediate(lint); Lint prevLint = deferPos != null ? null : chk.setLint(lint); try { if (s.hasAnnotations() && annotations.nonEmpty()) diff --git a/src/jdk.compiler/share/classes/com/sun/tools/javac/comp/Attr.java b/src/jdk.compiler/share/classes/com/sun/tools/javac/comp/Attr.java index 0d6e39c8b06..d0f3ae7464a 100644 --- a/src/jdk.compiler/share/classes/com/sun/tools/javac/comp/Attr.java +++ b/src/jdk.compiler/share/classes/com/sun/tools/javac/comp/Attr.java @@ -979,7 +979,7 @@ public class Attr extends JCTree.Visitor { env.info.ctorPrologue = false; MethodSymbol prevMethod = chk.setMethod(m); try { - deferredLintHandler.flush(tree.pos()); + deferredLintHandler.flush(tree.pos(), lint); chk.checkDeprecatedAnnotation(tree.pos(), m); @@ -1280,7 +1280,7 @@ public class Attr extends JCTree.Visitor { try { v.getConstValue(); // ensure compile-time constant initializer is evaluated - deferredLintHandler.flush(tree.pos()); + deferredLintHandler.flush(tree.pos(), lint); chk.checkDeprecatedAnnotation(tree.pos(), v); if (tree.init != null) { @@ -5297,7 +5297,7 @@ public class Attr extends JCTree.Visitor { JavaFileObject prev = log.useSource(env.toplevel.sourcefile); try { - deferredLintHandler.flush(env.tree.pos()); + deferredLintHandler.flush(env.tree.pos(), lint); attrib.accept(env); } finally { log.useSource(prev); @@ -5472,7 +5472,7 @@ public class Attr extends JCTree.Visitor { } } - deferredLintHandler.flush(env.tree); + deferredLintHandler.flush(env.tree, env.info.lint); env.info.returnResult = null; // java.lang.Enum may not be subclassed by a non-enum if (st.tsym == syms.enumSym && @@ -5522,7 +5522,7 @@ public class Attr extends JCTree.Visitor { chk.checkDeprecatedAnnotation(tree, msym); try { - deferredLintHandler.flush(tree.pos()); + deferredLintHandler.flush(tree.pos(), lint); } finally { chk.setLint(prevLint); } diff --git a/src/jdk.compiler/share/classes/com/sun/tools/javac/comp/Check.java b/src/jdk.compiler/share/classes/com/sun/tools/javac/comp/Check.java index 1e717b2b034..e909afc0bdf 100644 --- a/src/jdk.compiler/share/classes/com/sun/tools/javac/comp/Check.java +++ b/src/jdk.compiler/share/classes/com/sun/tools/javac/comp/Check.java @@ -673,7 +673,7 @@ public class Check { && types.isSameType(tree.expr.type, tree.clazz.type) && !(ignoreAnnotatedCasts && TreeInfo.containsTypeAnnotation(tree.clazz)) && !is292targetTypeCast(tree)) { - deferredLintHandler.report(() -> { + deferredLintHandler.report(_l -> { if (lint.isEnabled(LintCategory.CAST)) log.warning(LintCategory.CAST, tree.pos(), Warnings.RedundantCast(tree.clazz.type)); @@ -1350,7 +1350,7 @@ public class Check { private void warnOnExplicitStrictfp(DiagnosticPosition pos) { DiagnosticPosition prevLintPos = deferredLintHandler.setPos(pos); try { - deferredLintHandler.report(() -> { + deferredLintHandler.report(_l -> { if (lint.isEnabled(LintCategory.STRICTFP)) { log.warning(LintCategory.STRICTFP, pos, Warnings.Strictfp); } @@ -3809,13 +3809,13 @@ public class Check { || s.isDeprecated() && !other.isDeprecated()) && (s.outermostClass() != other.outermostClass() || s.outermostClass() == null) && s.kind != Kind.PCK) { - deferredLintHandler.report(() -> warnDeprecated(pos.get(), s)); + deferredLintHandler.report(_l -> warnDeprecated(pos.get(), s)); } } void checkSunAPI(final DiagnosticPosition pos, final Symbol s) { if ((s.flags() & PROPRIETARY) != 0) { - deferredLintHandler.report(() -> { + deferredLintHandler.report(_l -> { log.mandatoryWarning(pos, Warnings.SunProprietary(s)); }); } @@ -3834,10 +3834,10 @@ public class Check { log.error(pos, Errors.IsPreview(s)); } else { preview.markUsesPreview(pos); - deferredLintHandler.report(() -> warnPreviewAPI(pos, Warnings.IsPreview(s))); + deferredLintHandler.report(_l -> warnPreviewAPI(pos, Warnings.IsPreview(s))); } } else { - deferredLintHandler.report(() -> warnPreviewAPI(pos, Warnings.IsPreviewReflective(s))); + deferredLintHandler.report(_l -> warnPreviewAPI(pos, Warnings.IsPreviewReflective(s))); } } if (preview.declaredUsingPreviewFeature(s)) { @@ -3846,14 +3846,14 @@ public class Check { //If "s" is compiled from source, then there was an error for it already; //if "s" is from classfile, there already was an error for the classfile. preview.markUsesPreview(pos); - deferredLintHandler.report(() -> warnDeclaredUsingPreview(pos, s)); + deferredLintHandler.report(_l -> warnDeclaredUsingPreview(pos, s)); } } } void checkRestricted(DiagnosticPosition pos, Symbol s) { if (s.kind == MTH && (s.flags() & RESTRICTED) != 0) { - deferredLintHandler.report(() -> warnRestrictedAPI(pos, s)); + deferredLintHandler.report(_l -> warnRestrictedAPI(pos, s)); } } @@ -4102,7 +4102,7 @@ public class Check { int opc = ((OperatorSymbol)operator).opcode; if (opc == ByteCodes.idiv || opc == ByteCodes.imod || opc == ByteCodes.ldiv || opc == ByteCodes.lmod) { - deferredLintHandler.report(() -> warnDivZero(pos)); + deferredLintHandler.report(_l -> warnDivZero(pos)); } } } @@ -4115,7 +4115,7 @@ public class Check { */ void checkLossOfPrecision(final DiagnosticPosition pos, Type found, Type req) { if (found.isNumeric() && req.isNumeric() && !types.isAssignable(found, req)) { - deferredLintHandler.report(() -> { + deferredLintHandler.report(_l -> { if (lint.isEnabled(LintCategory.LOSSY_CONVERSIONS)) log.warning(LintCategory.LOSSY_CONVERSIONS, pos, Warnings.PossibleLossOfPrecision(found, req)); @@ -4319,7 +4319,7 @@ public class Check { // Warning may be suppressed by // annotations; check again for being // enabled in the deferred context. - deferredLintHandler.report(() -> { + deferredLintHandler.report(_l -> { if (lint.isEnabled(LintCategory.MISSING_EXPLICIT_CTOR)) log.warning(LintCategory.MISSING_EXPLICIT_CTOR, pos, Warnings.MissingExplicitCtor(c, pkg, modle)); @@ -4654,7 +4654,7 @@ public class Check { void checkModuleExists(final DiagnosticPosition pos, ModuleSymbol msym) { if (msym.kind != MDL) { - deferredLintHandler.report(() -> { + deferredLintHandler.report(_l -> { if (lint.isEnabled(LintCategory.MODULE)) log.warning(LintCategory.MODULE, pos, Warnings.ModuleNotFound(msym)); }); @@ -4664,7 +4664,7 @@ public class Check { void checkPackageExistsForOpens(final DiagnosticPosition pos, PackageSymbol packge) { if (packge.members().isEmpty() && ((packge.flags() & Flags.HAS_RESOURCE) == 0)) { - deferredLintHandler.report(() -> { + deferredLintHandler.report(_l -> { if (lint.isEnabled(LintCategory.OPENS)) log.warning(pos, Warnings.PackageEmptyOrNotFound(packge)); }); @@ -4673,7 +4673,7 @@ public class Check { void checkModuleRequires(final DiagnosticPosition pos, final RequiresDirective rd) { if ((rd.module.flags() & Flags.AUTOMATIC_MODULE) != 0) { - deferredLintHandler.report(() -> { + deferredLintHandler.report(_l -> { if (rd.isTransitive() && lint.isEnabled(LintCategory.REQUIRES_TRANSITIVE_AUTOMATIC)) { log.warning(pos, Warnings.RequiresTransitiveAutomatic); } else if (lint.isEnabled(LintCategory.REQUIRES_AUTOMATIC)) { diff --git a/src/jdk.compiler/share/classes/com/sun/tools/javac/comp/TypeEnter.java b/src/jdk.compiler/share/classes/com/sun/tools/javac/comp/TypeEnter.java index af5f3dccdd6..9366e802b16 100644 --- a/src/jdk.compiler/share/classes/com/sun/tools/javac/comp/TypeEnter.java +++ b/src/jdk.compiler/share/classes/com/sun/tools/javac/comp/TypeEnter.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2003, 2022, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2003, 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 @@ -348,7 +348,7 @@ public class TypeEnter implements Completer { ImportFilter prevStaticImportFilter = staticImportFilter; ImportFilter prevTypeImportFilter = typeImportFilter; - DiagnosticPosition prevLintPos = deferredLintHandler.immediate(); + DiagnosticPosition prevLintPos = deferredLintHandler.immediate(lint); Lint prevLint = chk.setLint(lint); Env prevEnv = this.env; try { diff --git a/src/jdk.compiler/share/classes/com/sun/tools/javac/parser/JavaTokenizer.java b/src/jdk.compiler/share/classes/com/sun/tools/javac/parser/JavaTokenizer.java index 88de2333069..403cb30921a 100644 --- a/src/jdk.compiler/share/classes/com/sun/tools/javac/parser/JavaTokenizer.java +++ b/src/jdk.compiler/share/classes/com/sun/tools/javac/parser/JavaTokenizer.java @@ -34,6 +34,8 @@ import com.sun.tools.javac.file.JavacFileManager; import com.sun.tools.javac.parser.Tokens.Comment.CommentStyle; import com.sun.tools.javac.resources.CompilerProperties.Errors; import com.sun.tools.javac.resources.CompilerProperties.Warnings; +import com.sun.tools.javac.tree.EndPosTable; +import com.sun.tools.javac.tree.JCTree; import com.sun.tools.javac.util.*; import com.sun.tools.javac.util.JCDiagnostic.*; @@ -1207,6 +1209,8 @@ public class JavaTokenizer extends UnicodeReader { */ CommentStyle cs; + DiagnosticPosition pos; + /** * true if comment contains @deprecated at beginning of a line. */ @@ -1228,6 +1232,12 @@ public class JavaTokenizer extends UnicodeReader { protected BasicComment(CommentStyle cs, UnicodeReader reader, int pos, int endPos) { super(reader, pos, endPos); this.cs = cs; + this.pos = new SimpleDiagnosticPosition(pos) { + @Override + public int getEndPosition(EndPosTable endPosTable) { + return endPos; + } + }; } /** @@ -1239,6 +1249,10 @@ public class JavaTokenizer extends UnicodeReader { return null; } + public DiagnosticPosition getPos() { + return pos; + } + /** * Return buffer position in original buffer mapped from buffer position in comment. * 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 bc53b18b3a5..4eb7aa7c17d 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 @@ -111,6 +111,12 @@ public class JavacParser implements Parser { /** End position mappings container */ protected final AbstractEndPosTable endPosTable; + /** A map associating "other nearby documentation comments" + * with the preferred documentation comment for a declaration. */ + protected Map> danglingComments = new HashMap<>(); + /** Handler for deferred diagnostics. */ + protected final DeferredLintHandler deferredLintHandler; + // Because of javac's limited lookahead, some contexts are ambiguous in // the presence of type annotations even though they are not ambiguous // in the absence of type annotations. Consider this code: @@ -181,6 +187,7 @@ public class JavacParser implements Parser { this.names = fac.names; this.source = fac.source; this.preview = fac.preview; + this.deferredLintHandler = fac.deferredLintHandler; this.allowStringFolding = fac.options.getBoolean("allowStringFolding", true); this.keepDocComments = keepDocComments; this.parseModuleInfo = parseModuleInfo; @@ -205,6 +212,7 @@ public class JavacParser implements Parser { this.names = parser.names; this.source = parser.source; this.preview = parser.preview; + this.deferredLintHandler = parser.deferredLintHandler; this.allowStringFolding = parser.allowStringFolding; this.keepDocComments = parser.keepDocComments; this.parseModuleInfo = false; @@ -551,16 +559,119 @@ public class JavacParser implements Parser { */ private final DocCommentTable docComments; + /** Record nearby documentation comments against the + * primary documentation comment for a declaration. + * + * Dangling documentation comments are handled as follows. + * 1. {@code Scanner} adds all doc comments to a queue of + * recent doc comments. The queue is flushed whenever + * it is known that the recent doc comments should be + * ignored and should not cause any warnings. + * 2. The primary documentation comment is the one obtained + * from the first token of any declaration. + * (using {@code token.getDocComment()}. + * 3. At the end of the "signature" of the declaration + * (that is, before any initialization or body for the + * declaration) any other "recent" comments are saved + * in a map using the primary comment as a key, + * using this method, {@code saveDanglingComments}. + * 4. When the tree node for the declaration is finally + * available, and the primary comment, if any, + * is "attached", (in {@link #attach}) any related + * dangling comments are also attached to the tree node + * by registering them using the {@link #deferredLintHandler}. + * 5. (Later) Warnings may be generated for the dangling + * comments, subject to the {@code -Xlint} and + * {@code @SuppressWarnings}. + * + * @param dc the primary documentation comment + */ + private void saveDanglingDocComments(Comment dc) { + var recentComments = S.getDocComments(); + + switch (recentComments.size()) { + case 0: + // no recent comments + return; + + case 1: + if (recentComments.peek() == dc) { + // no other recent comments + recentComments.remove(); + return; + } + } + + var lb = new ListBuffer(); + while (!recentComments.isEmpty()) { + var c = recentComments.remove(); + if (c != dc) { + lb.add(c); + } + } + danglingComments.put(dc, lb.toList()); + } + /** Make an entry into docComments hashtable, * provided flag keepDocComments is set and given doc comment is non-null. + * If there are any related "dangling comments", register + * diagnostics to be handled later, when @SuppressWarnings + * can be taken into account. + * * @param tree The tree to be used as index in the hashtable * @param dc The doc comment to associate with the tree, or null. */ protected void attach(JCTree tree, Comment dc) { if (keepDocComments && dc != null) { -// System.out.println("doc comment = ");System.out.println(dc);//DEBUG docComments.putComment(tree, dc); } + reportDanglingComments(tree, dc); + } + + /** Reports all dangling comments associated with the + * primary comment for a declaration against the position + * of the tree node for a declaration. + * + * @param tree the tree node for the declaration + * @param dc the primary comment for the declaration + */ + void reportDanglingComments(JCTree tree, Comment dc) { + var list = danglingComments.remove(dc); + if (list != null) { + var prevPos = deferredLintHandler.setPos(tree); + try { + list.forEach(this::reportDanglingDocComment); + } finally { + deferredLintHandler.setPos(prevPos); + } + } + } + + /** + * Reports an individual dangling comment using the {@link #deferredLintHandler}. + * The comment may or not may generate an actual diagnostic, depending on + * the settings for {@code -Xlint} and/or {@code @SuppressWarnings}. + * + * @param c the comment + */ + void reportDanglingDocComment(Comment c) { + var pos = c.getPos(); + if (pos != null) { + deferredLintHandler.report(lint -> { + if (lint.isEnabled(Lint.LintCategory.DANGLING_DOC_COMMENTS)) { + log.warning(Lint.LintCategory.DANGLING_DOC_COMMENTS, + pos, Warnings.DanglingDocComment); + } + }); + } + } + + /** + * Ignores any recent documentation comments found by the scanner, + * such as those that cannot be associated with a nearby declaration. + */ + private void ignoreDanglingComments() { + S.getDocComments().clear(); } /* -------- source positions ------- */ @@ -2626,6 +2737,7 @@ public class JavacParser implements Parser { List args = arguments(); JCClassDecl body = null; if (token.kind == LBRACE) { + ignoreDanglingComments(); // ignore any comments from before the '{' int pos = token.pos; List defs = classInterfaceOrRecordBody(names.empty, false, false); JCModifiers mods = F.at(Position.NOPOS).Modifiers(0); @@ -2678,6 +2790,7 @@ public class JavacParser implements Parser { */ JCBlock block(int pos, long flags) { accept(LBRACE); + ignoreDanglingComments(); // ignore any comments from before the '{' List stats = blockStatements(); JCBlock t = F.at(pos).Block(flags, stats); while (token.kind == CASE || token.kind == DEFAULT) { @@ -2709,6 +2822,7 @@ public class JavacParser implements Parser { ListBuffer stats = new ListBuffer<>(); while (true) { List stat = blockStatement(); + ignoreDanglingComments(); // ignore comments not consumed by the statement if (stat.isEmpty()) { return stats.toList(); } else { @@ -2780,7 +2894,7 @@ public class JavacParser implements Parser { return List.of(classOrRecordOrInterfaceOrEnumDeclaration(mods, dc)); } else { JCExpression t = parseType(true); - return localVariableDeclarations(mods, t); + return localVariableDeclarations(mods, t, dc); } } case ABSTRACT: case STRICTFP: { @@ -2866,8 +2980,8 @@ public class JavacParser implements Parser { } } } + dc = token.docComment(); if (isRecordStart() && allowRecords) { - dc = token.docComment(); return List.of(recordDeclaration(F.at(pos).Modifiers(0), dc)); } else { Token prevToken = token; @@ -2880,7 +2994,7 @@ public class JavacParser implements Parser { pos = token.pos; JCModifiers mods = F.at(Position.NOPOS).Modifiers(0); F.at(pos); - return localVariableDeclarations(mods, t); + return localVariableDeclarations(mods, t, dc); } else { // This Exec is an "ExpressionStatement"; it subsumes the terminating semicolon t = checkExprStat(t); @@ -2891,7 +3005,11 @@ public class JavacParser implements Parser { } } //where - private List localVariableDeclarations(JCModifiers mods, JCExpression type) { + private List localVariableDeclarations(JCModifiers mods, JCExpression type, Comment dc) { + if (dc != null) { + // ignore a well-placed doc comment, but save any misplaced ones + saveDanglingDocComments(dc); + } ListBuffer stats = variableDeclarators(mods, type, new ListBuffer<>(), true); // A "LocalVariableDeclarationStatement" subsumes the terminating semicolon @@ -2919,6 +3037,7 @@ public class JavacParser implements Parser { * | ";" */ public JCStatement parseSimpleStatement() { + ignoreDanglingComments(); // ignore comments before statement int pos = token.pos; switch (token.kind) { case LBRACE: @@ -3649,6 +3768,8 @@ public class JavacParser implements Parser { name = names.empty; } + saveDanglingDocComments(dc); + if (token.kind == EQ) { nextToken(); init = variableInitializer(); @@ -4221,6 +4342,9 @@ public class JavacParser implements Parser { implementing = typeList(); } List permitting = permitsClause(mods, "class"); + + saveDanglingDocComments(dc); + List defs = classInterfaceOrRecordBody(name, false, false); JCClassDecl result = toP(F.at(pos).ClassDef( mods, name, typarams, extending, implementing, permitting, defs)); @@ -4243,6 +4367,9 @@ public class JavacParser implements Parser { nextToken(); implementing = typeList(); } + + saveDanglingDocComments(dc); + List defs = classInterfaceOrRecordBody(name, false, true); java.util.List fields = new ArrayList<>(); for (JCVariableDecl field : headerFields) { @@ -4302,6 +4429,9 @@ public class JavacParser implements Parser { extending = typeList(); } List permitting = permitsClause(mods, "interface"); + + saveDanglingDocComments(dc); + List defs; defs = classInterfaceOrRecordBody(name, true, false); JCClassDecl result = toP(F.at(pos).ClassDef( @@ -4347,6 +4477,8 @@ public class JavacParser implements Parser { implementing = typeList(); } + saveDanglingDocComments(dc); + List defs = enumBody(name); mods.flags |= Flags.ENUM; JCClassDecl result = toP(F.at(pos). @@ -4474,8 +4606,12 @@ public class JavacParser implements Parser { int identPos = token.pos; Name name = ident(); int createPos = token.pos; + + saveDanglingDocComments(dc); + List args = (token.kind == LPAREN) ? arguments() : List.nil(); + JCClassDecl body = null; if (token.kind == LBRACE) { JCModifiers mods1 = F.at(Position.NOPOS).Modifiers(Flags.ENUM); @@ -4580,6 +4716,7 @@ public class JavacParser implements Parser { } else if (isRecord && (mods.flags & Flags.STATIC) == 0) { log.error(DiagnosticFlag.SYNTAX, token.pos, Errors.InstanceInitializerNotAllowedInRecords); } + ignoreDanglingComments(); // no declaration with which dangling comments can be associated return List.of(block(pos, mods.flags)); } else { return constructorOrMethodOrFieldDeclaration(mods, className, isInterface, isRecord, dc); @@ -4857,6 +4994,9 @@ public class JavacParser implements Parser { thrown = qualidentList(true); } } + + saveDanglingDocComments(dc); + JCBlock body = null; JCExpression defaultValue; if (token.kind == LBRACE) { diff --git a/src/jdk.compiler/share/classes/com/sun/tools/javac/parser/Lexer.java b/src/jdk.compiler/share/classes/com/sun/tools/javac/parser/Lexer.java index 2223999bebe..bff4e027db7 100644 --- a/src/jdk.compiler/share/classes/com/sun/tools/javac/parser/Lexer.java +++ b/src/jdk.compiler/share/classes/com/sun/tools/javac/parser/Lexer.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2005, 2023, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2005, 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 @@ -25,6 +25,8 @@ package com.sun.tools.javac.parser; +import java.util.Queue; + import com.sun.tools.javac.parser.Tokens.*; import com.sun.tools.javac.util.Position.LineMap; @@ -89,4 +91,16 @@ public interface Lexer { * @return a LineMap */ LineMap getLineMap(); + + /** + * Returns a queue for the documentation comments encountered + * in a compilation unit. + * + * Comments may be added to this queue by the implementation; + * clients may remove them from the queue as they are analyzed. + * + * Note: all comments may also be associated with the following + * token. + */ + Queue getDocComments(); } diff --git a/src/jdk.compiler/share/classes/com/sun/tools/javac/parser/ParserFactory.java b/src/jdk.compiler/share/classes/com/sun/tools/javac/parser/ParserFactory.java index d27a785e363..3c07c382aa3 100644 --- a/src/jdk.compiler/share/classes/com/sun/tools/javac/parser/ParserFactory.java +++ b/src/jdk.compiler/share/classes/com/sun/tools/javac/parser/ParserFactory.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 1999, 2018, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 1999, 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 @@ -27,6 +27,8 @@ package com.sun.tools.javac.parser; import java.util.Locale; +import com.sun.tools.javac.code.DeferredLintHandler; +import com.sun.tools.javac.code.Lint; import com.sun.tools.javac.code.Preview; import com.sun.tools.javac.code.Source; import com.sun.tools.javac.tree.DocTreeMaker; @@ -68,6 +70,7 @@ public class ParserFactory { final Options options; final ScannerFactory scannerFactory; final Locale locale; + final DeferredLintHandler deferredLintHandler; @SuppressWarnings("this-escape") protected ParserFactory(Context context) { @@ -83,6 +86,7 @@ public class ParserFactory { this.options = Options.instance(context); this.scannerFactory = ScannerFactory.instance(context); this.locale = context.get(Locale.class); + this.deferredLintHandler = DeferredLintHandler.instance(context); } public JavacParser newParser(CharSequence input, boolean keepDocComments, boolean keepEndPos, boolean keepLineMap) { diff --git a/src/jdk.compiler/share/classes/com/sun/tools/javac/parser/Scanner.java b/src/jdk.compiler/share/classes/com/sun/tools/javac/parser/Scanner.java index 3cfb8b9ddbe..a182c74b07b 100644 --- a/src/jdk.compiler/share/classes/com/sun/tools/javac/parser/Scanner.java +++ b/src/jdk.compiler/share/classes/com/sun/tools/javac/parser/Scanner.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 1999, 2023, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 1999, 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 @@ -26,8 +26,10 @@ package com.sun.tools.javac.parser; import java.nio.*; +import java.util.ArrayDeque; import java.util.List; import java.util.ArrayList; +import java.util.Queue; import com.sun.tools.javac.util.Position.LineMap; import static com.sun.tools.javac.parser.Tokens.*; @@ -58,6 +60,11 @@ public class Scanner implements Lexer { private final JavaTokenizer tokenizer; + /** Queue of recently seen documentation comments. + * It is assumed the queue will typically be small. + */ + private final Queue docComments = new ArrayDeque<>(); + /** * Create a scanner from the input array. This method might * modify the array. To avoid copying the input array, ensure @@ -115,6 +122,15 @@ public class Scanner implements Lexer { token = savedTokens.remove(0); } else { token = tokenizer.readToken(); + if (token.comments != null) { + for (var c : token.comments) { + switch (c.getStyle()) { + case JAVADOC -> { + docComments.add(c); + } + } + } + } } } @@ -129,6 +145,11 @@ public class Scanner implements Lexer { return tokenizer.getLineMap(); } + @Override + public Queue getDocComments() { + return docComments; + } + public int errPos() { return tokenizer.errPos(); } diff --git a/src/jdk.compiler/share/classes/com/sun/tools/javac/parser/Tokens.java b/src/jdk.compiler/share/classes/com/sun/tools/javac/parser/Tokens.java index b6be0a84b7d..a05d48d320b 100644 --- a/src/jdk.compiler/share/classes/com/sun/tools/javac/parser/Tokens.java +++ b/src/jdk.compiler/share/classes/com/sun/tools/javac/parser/Tokens.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 1999, 2023, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 1999, 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 @@ -280,6 +280,7 @@ public class Tokens { } String getText(); + JCDiagnostic.DiagnosticPosition getPos(); int getSourcePos(int index); CommentStyle getStyle(); boolean isDeprecated(); diff --git a/src/jdk.compiler/share/classes/com/sun/tools/javac/parser/VirtualParser.java b/src/jdk.compiler/share/classes/com/sun/tools/javac/parser/VirtualParser.java index 1d716f75a90..f32c1bf4756 100644 --- a/src/jdk.compiler/share/classes/com/sun/tools/javac/parser/VirtualParser.java +++ b/src/jdk.compiler/share/classes/com/sun/tools/javac/parser/VirtualParser.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2023, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2023, 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 @@ -34,6 +34,7 @@ import com.sun.tools.javac.util.List; import com.sun.tools.javac.util.Position.LineMap; import java.util.Optional; +import java.util.Queue; import java.util.function.Consumer; import java.util.function.Function; @@ -146,6 +147,11 @@ public class VirtualParser extends JavacParser { return token; } + @Override + public Queue getDocComments() { + return S.getDocComments(); + } + @Override public int errPos() { return S.errPos(); diff --git a/src/jdk.compiler/share/classes/com/sun/tools/javac/resources/compiler.properties b/src/jdk.compiler/share/classes/com/sun/tools/javac/resources/compiler.properties index 273c5bef7b4..26c16ebdc2c 100644 --- a/src/jdk.compiler/share/classes/com/sun/tools/javac/resources/compiler.properties +++ b/src/jdk.compiler/share/classes/com/sun/tools/javac/resources/compiler.properties @@ -1869,6 +1869,9 @@ compiler.warn.lintOption=\ compiler.warn.constant.SVUID=\ serialVersionUID must be constant in class {0} +compiler.warn.dangling.doc.comment=\ + documentation comment is not attached to any declaration + # 0: path compiler.warn.dir.path.element.not.found=\ bad path element "{0}": no such directory diff --git a/src/jdk.compiler/share/classes/com/sun/tools/javac/resources/javac.properties b/src/jdk.compiler/share/classes/com/sun/tools/javac/resources/javac.properties index 7893d328afa..0566272ca1b 100644 --- a/src/jdk.compiler/share/classes/com/sun/tools/javac/resources/javac.properties +++ b/src/jdk.compiler/share/classes/com/sun/tools/javac/resources/javac.properties @@ -1,5 +1,5 @@ # -# Copyright (c) 1999, 2022, Oracle and/or its affiliates. All rights reserved. +# Copyright (c) 1999, 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 @@ -189,6 +189,9 @@ javac.opt.Xlint.desc.cast=\ javac.opt.Xlint.desc.classfile=\ Warn about issues related to classfile contents. +javac.opt.Xlint.desc.dangling-doc-comments=\ + Warn about dangling documentation comments, not attached to any declaration. + javac.opt.Xlint.desc.missing-explicit-ctor=\ Warn about missing explicit constructors in public and protected classes in exported packages. diff --git a/src/jdk.compiler/share/classes/com/sun/tools/javac/tree/DocTreeMaker.java b/src/jdk.compiler/share/classes/com/sun/tools/javac/tree/DocTreeMaker.java index afa590240e2..c729b6ff832 100644 --- a/src/jdk.compiler/share/classes/com/sun/tools/javac/tree/DocTreeMaker.java +++ b/src/jdk.compiler/share/classes/com/sun/tools/javac/tree/DocTreeMaker.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2011, 2023, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2011, 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 @@ -218,6 +218,11 @@ public class DocTreeMaker implements DocTreeFactory { return null; } + @Override + public JCDiagnostic.DiagnosticPosition getPos() { + return null; + } + @Override public int getSourcePos(int index) { return Position.NOPOS; diff --git a/src/jdk.compiler/share/classes/module-info.java b/src/jdk.compiler/share/classes/module-info.java index 9826b3f576b..9b12171ef6d 100644 --- a/src/jdk.compiler/share/classes/module-info.java +++ b/src/jdk.compiler/share/classes/module-info.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2014, 2023, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2014, 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 @@ -153,6 +153,8 @@ import javax.tools.StandardLocation; * from other files * {@code cast} use of unnecessary casts * {@code classfile} issues related to classfile contents + * {@code dangling-doc-comments} issues related to "dangling" documentation comments, + * not attached to a declaration * {@code deprecation} use of deprecated items * {@code dep-ann} items marked as deprecated in a documentation comment but not * using the {@code @Deprecated} annotation diff --git a/src/jdk.compiler/share/man/javac.1 b/src/jdk.compiler/share/man/javac.1 index ab429ab7d9a..6586bcaf83f 100644 --- a/src/jdk.compiler/share/man/javac.1 +++ b/src/jdk.compiler/share/man/javac.1 @@ -708,6 +708,9 @@ in a source file, and is used from other files. \f[V]classfile\f[R]: Warns about the issues related to classfile contents. .IP \[bu] 2 +\f[V]dangling-doc-comments\f[R]: Warns about extra or misplaced +documentation comments near the beginning of a declaration. +.IP \[bu] 2 \f[V]deprecation\f[R]: Warns about the use of deprecated items. .IP \[bu] 2 \f[V]dep-ann\f[R]: Warns about the items marked as deprecated in diff --git a/src/jdk.javadoc/share/classes/jdk/javadoc/internal/tool/JavadocMemberEnter.java b/src/jdk.javadoc/share/classes/jdk/javadoc/internal/tool/JavadocMemberEnter.java index 51f45627f31..4628d851ab0 100644 --- a/src/jdk.javadoc/share/classes/jdk/javadoc/internal/tool/JavadocMemberEnter.java +++ b/src/jdk.javadoc/share/classes/jdk/javadoc/internal/tool/JavadocMemberEnter.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2003, 2022, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2003, 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 @@ -132,8 +132,8 @@ public class JavadocMemberEnter extends MemberEnter { tree.accept(this); } - @Override /** default for any non-overridden visit method. */ + @Override public void visitTree(JCTree tree) { maybeConstantExpr = false; } diff --git a/src/jdk.javadoc/share/man/javadoc.1 b/src/jdk.javadoc/share/man/javadoc.1 index 30256207b3e..d42d7137657 100644 --- a/src/jdk.javadoc/share/man/javadoc.1 +++ b/src/jdk.javadoc/share/man/javadoc.1 @@ -96,6 +96,22 @@ option either to recursively traverse a directory and its subdirectories, or to pass in an explicit list of package names. When you document individual source files, pass in a list of Java source file names. +.SS Documentation Comments +.PP +The \f[V]javadoc\f[R] tool uses the documentation comment, if any, that +immediately precedes the beginning of the declaration, whether that is +an annotation, modifier, or the name being declared. +If there are multiple documentation comments before the declaration, +only the last one (closest to the declaration) will be used. +If there are any documentation comments after the beginning of the +declaration, they will be ignored. +To check for any extra or misplaced documentation comments, compile your +source code with the \f[V]javac\f[R] option \f[V]-Xlint\f[R], or more +specifically, \f[V]-Xlint:dangling-doc-comments\f[R]. +Within a source file, you may use suppress any warnings generated by +these options by using +\f[V]\[at]SuppressWarnings(\[dq]dangling-doc-comments\[dq])\f[R] on a +suitable enclosing declaration. .SS Conformance .PP The standard doclet does not validate the content of documentation diff --git a/test/langtools/tools/javac/OverrideChecks/6199153/T6199153.java b/test/langtools/tools/javac/OverrideChecks/6199153/T6199153.java index 4a800d1f415..d696301f6d2 100644 --- a/test/langtools/tools/javac/OverrideChecks/6199153/T6199153.java +++ b/test/langtools/tools/javac/OverrideChecks/6199153/T6199153.java @@ -1,4 +1,4 @@ -/** +/* * @test /nodynamiccopyright/ * @bug 6199153 * @summary Generic throws and overriding diff --git a/test/langtools/tools/javac/danglingDocComments/DanglingDocCommentsClass.enabled.out b/test/langtools/tools/javac/danglingDocComments/DanglingDocCommentsClass.enabled.out new file mode 100644 index 00000000000..76082537ed9 --- /dev/null +++ b/test/langtools/tools/javac/danglingDocComments/DanglingDocCommentsClass.enabled.out @@ -0,0 +1,7 @@ +DanglingDocCommentsClass.java:8:1: compiler.warn.dangling.doc.comment +DanglingDocCommentsClass.java:11:1: compiler.warn.dangling.doc.comment +DanglingDocCommentsClass.java:12:8: compiler.warn.dangling.doc.comment +DanglingDocCommentsClass.java:12:69: compiler.warn.dangling.doc.comment +DanglingDocCommentsClass.java:13:5: compiler.warn.dangling.doc.comment +DanglingDocCommentsClass.java:17:5: compiler.warn.dangling.doc.comment +6 warnings diff --git a/test/langtools/tools/javac/danglingDocComments/DanglingDocCommentsClass.java b/test/langtools/tools/javac/danglingDocComments/DanglingDocCommentsClass.java new file mode 100644 index 00000000000..2075bf4495a --- /dev/null +++ b/test/langtools/tools/javac/danglingDocComments/DanglingDocCommentsClass.java @@ -0,0 +1,46 @@ +/* + * @test /nodynamiccopyright/ + * @compile -Xlint:dangling-doc-comments DanglingDocCommentsClass.java + * @compile/ref=empty.out -XDrawDiagnostics DanglingDocCommentsClass.java + * @compile/ref=DanglingDocCommentsClass.enabled.out -XDrawDiagnostics -Xlint:dangling-doc-comments DanglingDocCommentsClass.java + */ + +/** Bad/Extra Class Comment. */ +/** Good Class Comment. */ +@Deprecated +/** Misplaced: after anno. */ +public /** Misplaced: after mods. */ class DanglingDocCommentsClass /** Misplaced: after ident */ { + /** Bad/Extra Field Comment. */ + /** Good Field Comment. */ + public int i; + + /** Bad/Extra Method Comment. */ + /** Good Method Comment. */ + public void m1() { } + + @SuppressWarnings("dangling-doc-comments") + /** Bad/misplaced/suppressed comment. */ + public void m2() { } + + public void m3(boolean b) { + /**************** + * Box comment * + ***************/ + if (b) return; + } + + public void m4a() { + /** Not a doc comment. */ + System.out.println(); + /** Not a doc comment; not dangling for m4b */ + } + + /** Good comment for m4b; no dangling comments. */ + public void m4b() { } + + /** Comment ignored here: does not affect decls in block */ + static { + /** Good comment. */ + int i = 0; + } +} \ No newline at end of file diff --git a/test/langtools/tools/javac/danglingDocComments/DanglingDocCommentsEnum.enabled.out b/test/langtools/tools/javac/danglingDocComments/DanglingDocCommentsEnum.enabled.out new file mode 100644 index 00000000000..78dfd6e9633 --- /dev/null +++ b/test/langtools/tools/javac/danglingDocComments/DanglingDocCommentsEnum.enabled.out @@ -0,0 +1,8 @@ +DanglingDocCommentsEnum.java:8:1: compiler.warn.dangling.doc.comment +DanglingDocCommentsEnum.java:11:1: compiler.warn.dangling.doc.comment +DanglingDocCommentsEnum.java:12:8: compiler.warn.dangling.doc.comment +DanglingDocCommentsEnum.java:12:67: compiler.warn.dangling.doc.comment +DanglingDocCommentsEnum.java:14:5: compiler.warn.dangling.doc.comment +DanglingDocCommentsEnum.java:20:5: compiler.warn.dangling.doc.comment +DanglingDocCommentsEnum.java:26:5: compiler.warn.dangling.doc.comment +7 warnings diff --git a/test/langtools/tools/javac/danglingDocComments/DanglingDocCommentsEnum.java b/test/langtools/tools/javac/danglingDocComments/DanglingDocCommentsEnum.java new file mode 100644 index 00000000000..eae98433b70 --- /dev/null +++ b/test/langtools/tools/javac/danglingDocComments/DanglingDocCommentsEnum.java @@ -0,0 +1,37 @@ +/* + * @test /nodynamiccopyright/ + * @compile -Xlint:dangling-doc-comments DanglingDocCommentsEnum.java + * @compile/ref=empty.out -XDrawDiagnostics DanglingDocCommentsEnum.java + * @compile/ref=DanglingDocCommentsEnum.enabled.out -XDrawDiagnostics -Xlint:dangling-doc-comments DanglingDocCommentsEnum.java + */ + +/** Bad/Extra Enum Comment. */ +/** Good Enum Comment. */ +@Deprecated +/** Misplaced: after anno. */ +public /** Misplaced: after mods. */ enum DanglingDocCommentsEnum /** Misplaced: after ident */ +{ + /** Bad/Extra enum-member Comment. */ + /** + * Good enum-member Comment. + */ + E1; + + /** Bad/Extra Field Comment. */ + /** + * Good Field Comment. + */ + public int i; + + /** Bad/Extra Method Comment. */ + /** + * Good Method Comment. + */ + public void m1() { + } + + @SuppressWarnings("dangling-doc-comments") + /** Bad/misplaced/suppressed comment. */ + public void m2() { + } +} \ No newline at end of file diff --git a/test/langtools/tools/javac/danglingDocComments/empty.out b/test/langtools/tools/javac/danglingDocComments/empty.out new file mode 100644 index 00000000000..e69de29bb2d diff --git a/test/langtools/tools/javac/depDocComment/DeprecatedDocComment3.java b/test/langtools/tools/javac/depDocComment/DeprecatedDocComment3.java index d7f4dbc0f2c..4765444f069 100644 --- a/test/langtools/tools/javac/depDocComment/DeprecatedDocComment3.java +++ b/test/langtools/tools/javac/depDocComment/DeprecatedDocComment3.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2011, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2011, 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 @@ -21,11 +21,11 @@ * questions. */ -/** +/* * @test * @bug 7096014 * @summary Javac tokens should retain state - * @compile -Xlint -Werror DeprecatedDocComment3.java + * @compile -Xlint:-dangling-doc-comments -Werror DeprecatedDocComment3.java */ class DeprecatedDocComment3 { diff --git a/test/langtools/tools/javac/diags/examples/DanglingDocCommentWarning/DanglingDocCommentWarning.java b/test/langtools/tools/javac/diags/examples/DanglingDocCommentWarning/DanglingDocCommentWarning.java new file mode 100644 index 00000000000..9e87c2d0482 --- /dev/null +++ b/test/langtools/tools/javac/diags/examples/DanglingDocCommentWarning/DanglingDocCommentWarning.java @@ -0,0 +1,29 @@ +/* + * 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. + */ + +// key: compiler.warn.dangling.doc.comment +// options: -Xlint:dangling-doc-comments + +/** Comment 1. */ +/** Comment 2. */ +class DanglingDocCommentWarning { } diff --git a/test/langtools/tools/javac/platform/PreviewAPIsWithRelease.java b/test/langtools/tools/javac/platform/PreviewAPIsWithRelease.java index 155dd5335d9..a9167fc34df 100644 --- a/test/langtools/tools/javac/platform/PreviewAPIsWithRelease.java +++ b/test/langtools/tools/javac/platform/PreviewAPIsWithRelease.java @@ -1,4 +1,4 @@ -/** +/* * @test /nodynamiccopyright/ * @bug 8246704 * @summary Verify preview APIs are reported correctly when using --release. diff --git a/test/langtools/tools/javac/warnings/DepAnn.java b/test/langtools/tools/javac/warnings/DepAnn.java index 4f25d290e7b..d725258cf3a 100644 --- a/test/langtools/tools/javac/warnings/DepAnn.java +++ b/test/langtools/tools/javac/warnings/DepAnn.java @@ -1,7 +1,7 @@ /* * @test /nodynamiccopyright/ * @bug 4986256 - * @compile/ref=DepAnn.out -XDrawDiagnostics -Xlint:all DepAnn.java + * @compile/ref=DepAnn.out -XDrawDiagnostics -Xlint:all,-dangling-doc-comments DepAnn.java */ // control: this class should generate warnings diff --git a/test/langtools/tools/javac/warnings/Deprecation.java b/test/langtools/tools/javac/warnings/Deprecation.java index 4a9d4fb2b3a..551ce6dc13e 100644 --- a/test/langtools/tools/javac/warnings/Deprecation.java +++ b/test/langtools/tools/javac/warnings/Deprecation.java @@ -1,4 +1,4 @@ -/** +/* * @test /nodynamiccopyright/ * @bug 4986256 6598104 8032211 8194764 * @compile/ref=Deprecation.noLint.out -XDrawDiagnostics Deprecation.java diff --git a/test/langtools/tools/javac/warnings/NestedDeprecation/NestedDeprecation.java b/test/langtools/tools/javac/warnings/NestedDeprecation/NestedDeprecation.java index 2e41f72b58b..0e4d19826ee 100644 --- a/test/langtools/tools/javac/warnings/NestedDeprecation/NestedDeprecation.java +++ b/test/langtools/tools/javac/warnings/NestedDeprecation/NestedDeprecation.java @@ -1,4 +1,4 @@ -/** +/* * @test /nodynamiccopyright/ * @bug 6598104 8032211 * @build p.Dep1 p.Dep2 diff --git a/test/langtools/tools/javac/warnings/Unchecked.java b/test/langtools/tools/javac/warnings/Unchecked.java index 7d5e4aa83a4..e64fd760a07 100644 --- a/test/langtools/tools/javac/warnings/Unchecked.java +++ b/test/langtools/tools/javac/warnings/Unchecked.java @@ -1,4 +1,4 @@ -/** +/* * @test /nodynamiccopyright/ * @bug 4986256 * @compile/ref=Unchecked.noLint.out -XDrawDiagnostics Unchecked.java diff --git a/test/langtools/tools/javac/warnings/VerifyLintDescriptions.java b/test/langtools/tools/javac/warnings/VerifyLintDescriptions.java index 54472a3b682..4a025ca497f 100644 --- a/test/langtools/tools/javac/warnings/VerifyLintDescriptions.java +++ b/test/langtools/tools/javac/warnings/VerifyLintDescriptions.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2014, 2016, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2014, 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 @@ -21,7 +21,7 @@ * questions. */ -/** +/* * @test * @bug 8033961 * @summary Verify that all LintCategories have their descriptions filled. diff --git a/test/langtools/tools/javac/warnings/suppress/T6480588.java b/test/langtools/tools/javac/warnings/suppress/T6480588.java index 84454d251a1..da9513709d9 100644 --- a/test/langtools/tools/javac/warnings/suppress/T6480588.java +++ b/test/langtools/tools/javac/warnings/suppress/T6480588.java @@ -1,4 +1,4 @@ -/** +/* * @test /nodynamiccopyright/ * @bug 6470588 * @summary Verify that \\@SuppressWarnings("deprecation") works OK for all parts