stan/jdk-24
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source 
Reviewed-by: vromero, ihse, prr
This commit is contained in:
Jonathan Gibbons 2024-04-26 19:47:06 +00:00
parent f3bb3e2170
commit a920af233a
58 changed files with 575 additions and 89 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
make/CompileDemos.gmk
View File

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

4
make/CompileToolsJdk.gmk
View File

@ -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 \

3
make/GenerateLinkOptData.gmk
View File

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

4
make/modules/java.desktop/Java.gmk
View File

@ -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

4
make/modules/java.management/Java.gmk
View File

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

4
make/modules/java.naming/Java.gmk
View File

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

4
make/modules/java.security.jgss/Java.gmk
View File

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

4
make/modules/java.security.sasl/Java.gmk
View File

@ -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

4
make/modules/java.sql.rowset/Java.gmk
View File

@ -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 \

4
make/modules/java.sql/Java.gmk
View File

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

4
make/modules/java.xml.crypto/Java.gmk
View File

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

4
make/modules/java.xml/Java.gmk
View File

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

26
make/modules/jdk.accessibility/Java.gmk Normal file
View File

@ -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

26
make/modules/jdk.crypto.cryptoki/Java.gmk Normal file
View File

@ -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

4
make/modules/jdk.hotspot.agent/Java.gmk
View File

@ -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

4
make/modules/jdk.internal.le/Java.gmk
View File

@ -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

4
make/modules/jdk.internal.vm.ci/Java.gmk
View File

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

4
make/modules/jdk.jdi/Java.gmk
View File

@ -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 \

4
make/modules/jdk.jfr/Java.gmk
View File

@ -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

26
make/modules/jdk.security.auth/Java.gmk Normal file
View File

@ -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

27
make/modules/jdk.zipfs/Java.gmk Normal file
View File

@ -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

2
make/test/BuildTestLib.gmk
View File

@ -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 \

7
src/jdk.compiler/share/classes/com/sun/tools/javac/api/JavacTrees.java
View File

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

18
src/jdk.compiler/share/classes/com/sun/tools/javac/code/DeferredLintHandler.java
View File

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

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

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

4
src/jdk.compiler/share/classes/com/sun/tools/javac/comp/Annotate.java
View File

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

10
src/jdk.compiler/share/classes/com/sun/tools/javac/comp/Attr.java
View File

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

28
src/jdk.compiler/share/classes/com/sun/tools/javac/comp/Check.java
View File

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

4
src/jdk.compiler/share/classes/com/sun/tools/javac/comp/TypeEnter.java
View File

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

14
src/jdk.compiler/share/classes/com/sun/tools/javac/parser/JavaTokenizer.java
View File

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

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

@ -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 {
}
}
}
if (isRecordStart() && allowRecords) {
dc = token.docComment();
if (isRecordStart() && allowRecords) {
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) {

16
src/jdk.compiler/share/classes/com/sun/tools/javac/parser/Lexer.java
View File

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

6
src/jdk.compiler/share/classes/com/sun/tools/javac/parser/ParserFactory.java
View File

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

23
src/jdk.compiler/share/classes/com/sun/tools/javac/parser/Scanner.java
View File

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

3
src/jdk.compiler/share/classes/com/sun/tools/javac/parser/Tokens.java
View File

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

8
src/jdk.compiler/share/classes/com/sun/tools/javac/parser/VirtualParser.java
View File

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

3
src/jdk.compiler/share/classes/com/sun/tools/javac/resources/compiler.properties
View File

@ -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

5
src/jdk.compiler/share/classes/com/sun/tools/javac/resources/javac.properties
View File

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

7
src/jdk.compiler/share/classes/com/sun/tools/javac/tree/DocTreeMaker.java
View File

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

4
src/jdk.compiler/share/classes/module-info.java
View File

@ -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

3
src/jdk.compiler/share/man/javac.1
View File

@ -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

4
src/jdk.javadoc/share/classes/jdk/javadoc/internal/tool/JavadocMemberEnter.java
View File

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

16
src/jdk.javadoc/share/man/javadoc.1
View File

@ -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

2
test/langtools/tools/javac/OverrideChecks/6199153/T6199153.java
View File

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

7
test/langtools/tools/javac/danglingDocComments/DanglingDocCommentsClass.enabled.out Normal file
View File

@ -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

46
test/langtools/tools/javac/danglingDocComments/DanglingDocCommentsClass.java Normal file
View File

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

8
test/langtools/tools/javac/danglingDocComments/DanglingDocCommentsEnum.enabled.out Normal file
View File

@ -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

37
test/langtools/tools/javac/danglingDocComments/DanglingDocCommentsEnum.java Normal file
View File

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

0
test/langtools/tools/javac/danglingDocComments/empty.out Normal file
View File

6
test/langtools/tools/javac/depDocComment/DeprecatedDocComment3.java
View File

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

29
test/langtools/tools/javac/diags/examples/DanglingDocCommentWarning/DanglingDocCommentWarning.java Normal file
View File

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

2
test/langtools/tools/javac/platform/PreviewAPIsWithRelease.java
View File

@ -1,4 +1,4 @@
/**
/*
* @test /nodynamiccopyright/
* @bug 8246704
* @summary Verify preview APIs are reported correctly when using --release.

2
test/langtools/tools/javac/warnings/DepAnn.java
View File

@ -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

2
test/langtools/tools/javac/warnings/Deprecation.java
View File

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

2
test/langtools/tools/javac/warnings/NestedDeprecation/NestedDeprecation.java
View File

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

2
test/langtools/tools/javac/warnings/Unchecked.java
View File

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

4
test/langtools/tools/javac/warnings/VerifyLintDescriptions.java
View File

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

2
test/langtools/tools/javac/warnings/suppress/T6480588.java
View File

@ -1,4 +1,4 @@
/**
/*
* @test /nodynamiccopyright/
* @bug 6470588
* @summary Verify that \\@SuppressWarnings("deprecation") works OK for all parts