8303689: javac -Xlint could/should report on "dangling" doc comments

Reviewed-by: vromero, ihse, prr

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, \
 ))
 

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 \

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, \
 ))

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

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.*'

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.*'

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.*'

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

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 \

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.*'

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.*'

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)'

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

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

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

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

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.

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 \

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

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

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
+

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 \

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;

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<LintLogger> 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<LintLogger> 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);
     }
 

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.
          */

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())

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);
         }

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)) {

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<AttrContext> prevEnv = this.env;
             try {

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.
          *

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<Comment, List<Comment>> 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<Comment>();
+        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<JCExpression> args = arguments();
         JCClassDecl body = null;
         if (token.kind == LBRACE) {
+            ignoreDanglingComments(); // ignore any comments from before the '{'
             int pos = token.pos;
             List<JCTree> 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<JCStatement> 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<JCStatement> stats = new ListBuffer<>();
         while (true) {
             List<JCStatement> 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<JCStatement> localVariableDeclarations(JCModifiers mods, JCExpression type) {
+        private List<JCStatement> localVariableDeclarations(JCModifiers mods, JCExpression type, Comment dc) {
+            if (dc != null) {
+                // ignore a well-placed doc comment, but save any misplaced ones
+                saveDanglingDocComments(dc);
+            }
             ListBuffer<JCStatement> 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<JCExpression> permitting = permitsClause(mods, "class");
+
+        saveDanglingDocComments(dc);
+
         List<JCTree> 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<JCTree> defs = classInterfaceOrRecordBody(name, false, true);
         java.util.List<JCVariableDecl> fields = new ArrayList<>();
         for (JCVariableDecl field : headerFields) {
@@ -4302,6 +4429,9 @@ public class JavacParser implements Parser {
             extending = typeList();
         }
         List<JCExpression> permitting = permitsClause(mods, "interface");
+
+        saveDanglingDocComments(dc);
+
         List<JCTree> 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<JCTree> 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<JCExpression> 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) {

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<Comment> getDocComments();
 }

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) {

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<Comment> 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<Comment> getDocComments() {
+        return docComments;
+    }
+
     public int errPos() {
         return tokenizer.errPos();
     }

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();

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<Tokens.Comment> getDocComments() {
+            return S.getDocComments();
+        }
+
         @Override
         public int errPos() {
             return S.errPos();

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

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.
 

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;

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
  * <tr><th scope="row">{@code cast}                 <td>use of unnecessary casts
  * <tr><th scope="row">{@code classfile}            <td>issues related to classfile contents
+ * <tr><th scope="row">{@code dangling-doc-comments} <td>issues related to "dangling" documentation comments,
+ *                                                       not attached to a declaration
  * <tr><th scope="row">{@code deprecation}          <td>use of deprecated items
  * <tr><th scope="row">{@code dep-ann}              <td>items marked as deprecated in a documentation comment but not
  *                                                      using the {@code @Deprecated} annotation

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

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;
         }

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

test/langtools/tools/javac/OverrideChecks/6199153/T6199153.java

@@ -1,4 +1,4 @@
-/**
+/*
  * @test /nodynamiccopyright/
  * @bug 6199153
  * @summary Generic throws and overriding

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

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;
+    }
+}

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

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() {
+    }
+}

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 {

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 { }

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.

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

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

test/langtools/tools/javac/warnings/NestedDeprecation/NestedDeprecation.java

@@ -1,4 +1,4 @@
-/**
+/*
  * @test  /nodynamiccopyright/
  * @bug 6598104 8032211
  * @build p.Dep1 p.Dep2

test/langtools/tools/javac/warnings/Unchecked.java

@@ -1,4 +1,4 @@
-/**
+/*
  * @test  /nodynamiccopyright/
  * @bug 4986256
  * @compile/ref=Unchecked.noLint.out                         -XDrawDiagnostics Unchecked.java

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.

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