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

8284994: -Xdoclint:all returns warning for records, even when documented properly

Browse Source 
Reviewed-by: vromero
This commit is contained in:
Jonathan Gibbons 2022-04-26 15:42:18 +00:00
parent a3b788144e
commit 20a132d460
5 changed files with 87 additions and 19 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

60
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclint/Checker.java
View File

@ -187,7 +187,7 @@ public class Checker extends DocTreePathScanner<Void, Void> {
if (isNormalClass(p.getParentPath())) {
reportMissing("dc.default.constructor");
}
} else if (!isOverridingMethod && !isSynthetic() && !isAnonymous()) {
} else if (!isOverridingMethod && !isSynthetic() && !isAnonymous() && !isRecordComponentOrField()) {
reportMissing("dc.missing.comment");
}
return null;
@ -248,26 +248,28 @@ public class Checker extends DocTreePathScanner<Void, Void> {
scan(new DocTreePath(p, tree), null);
if (!isOverridingMethod) {
switch (env.currElement.getKind()) {
case METHOD:
case CONSTRUCTOR: {
ExecutableElement ee = (ExecutableElement) env.currElement;
checkParamsDocumented(ee.getTypeParameters());
checkParamsDocumented(ee.getParameters());
switch (ee.getReturnType().getKind()) {
case VOID:
case NONE:
break;
default:
if (!foundReturn
&& !foundInheritDoc
&& !env.types.isSameType(ee.getReturnType(), env.java_lang_Void)) {
reportMissing("dc.missing.return");
}
// the following checks are made after the scan, which will record @param tags
if (isDeclaredType()) {
TypeElement te = (TypeElement) env.currElement;
// checkParamsDocumented(te.getTypeParameters()); // See JDK-8285496
checkParamsDocumented(te.getRecordComponents());
} else if (isExecutable()) {
if (!isOverridingMethod) {
ExecutableElement ee = (ExecutableElement) env.currElement;
checkParamsDocumented(ee.getTypeParameters());
checkParamsDocumented(ee.getParameters());
switch (ee.getReturnType().getKind()) {
case VOID, NONE -> {
}
default -> {
if (!foundReturn
&& !foundInheritDoc
&& !env.types.isSameType(ee.getReturnType(), env.java_lang_Void)) {
reportMissing("dc.missing.return");
}
}
checkThrowsDocumented(ee.getThrownTypes());
}
checkThrowsDocumented(ee.getThrownTypes());
}
}
@ -1207,6 +1209,26 @@ public class Checker extends DocTreePathScanner<Void, Void> {
return false;
}
private boolean isDeclaredType() {
ElementKind ek = env.currElement.getKind();
return ek.isClass() || ek.isInterface();
}
private boolean isExecutable() {
ElementKind ek = env.currElement.getKind();
return switch (ek) {
case CONSTRUCTOR, METHOD -> true;
default -> false;
};
}
private boolean isRecordComponentOrField() {
return env.currElement.getKind() == ElementKind.RECORD_COMPONENT
|| env.currElement.getEnclosingElement() != null
&& env.currElement.getEnclosingElement().getKind() == ElementKind.RECORD
&& env.currElement.getKind() == ElementKind.FIELD;
}
private boolean isNormalClass(TreePath p) {
return switch (p.getLeaf().getKind()) {
case ENUM, RECORD -> false;

12
test/langtools/tools/doclint/MissingRecordParamsTest.java Normal file
View File

@ -0,0 +1,12 @@
/*
* @test /nodynamiccopyright/
* @bug 8004832 8284994
* @summary Add new doclint package
* @modules jdk.javadoc/jdk.javadoc.internal.doclint
* @build DocLintTester
* @run main DocLintTester -Xmsgs:-missing MissingRecordParamsTest.java
* @run main DocLintTester -Xmsgs:missing -ref MissingRecordParamsTest.out MissingRecordParamsTest.java
*/
/** . */
public record MissingRecordParamsTest(int x) { }

4
test/langtools/tools/doclint/MissingRecordParamsTest.out Normal file
View File

@ -0,0 +1,4 @@
MissingRecordParamsTest.java:12: warning: no @param for x
public record MissingRecordParamsTest(int x) { }
^
1 warning

16
test/langtools/tools/doclint/RecordParamsTest.java Normal file
View File

@ -0,0 +1,16 @@
/*
* @test /nodynamiccopyright/
* @bug 8004832 8284994
* @summary Add new doclint package
* @modules jdk.javadoc/jdk.javadoc.internal.doclint
* @build DocLintTester
* @run main DocLintTester -Xmsgs:all -ref RecordParamsTest.out RecordParamsTest.java
*/
/**
* Comment.
* @param a aaa
* @param a aaa
* @param z zzz
*/
public record RecordParamsTest(int a, int b, int c) { }

14
test/langtools/tools/doclint/RecordParamsTest.out Normal file
View File

@ -0,0 +1,14 @@
RecordParamsTest.java:13: warning: @param "a" has already been specified
* @param a aaa
^
RecordParamsTest.java:14: error: invalid use of @param
* @param z zzz
^
RecordParamsTest.java:16: warning: no @param for b
public record RecordParamsTest(int a, int b, int c) { }
^
RecordParamsTest.java:16: warning: no @param for c
public record RecordParamsTest(int a, int b, int c) { }
^
1 error
3 warnings