From 20a132d460bc34fbf59774bc7493d93472b7d52a Mon Sep 17 00:00:00 2001 From: Jonathan Gibbons Date: Tue, 26 Apr 2022 15:42:18 +0000 Subject: [PATCH] 8284994: -Xdoclint:all returns warning for records, even when documented properly Reviewed-by: vromero --- .../jdk/javadoc/internal/doclint/Checker.java | 60 +++++++++++++------ .../doclint/MissingRecordParamsTest.java | 12 ++++ .../tools/doclint/MissingRecordParamsTest.out | 4 ++ .../tools/doclint/RecordParamsTest.java | 16 +++++ .../tools/doclint/RecordParamsTest.out | 14 +++++ 5 files changed, 87 insertions(+), 19 deletions(-) create mode 100644 test/langtools/tools/doclint/MissingRecordParamsTest.java create mode 100644 test/langtools/tools/doclint/MissingRecordParamsTest.out create mode 100644 test/langtools/tools/doclint/RecordParamsTest.java create mode 100644 test/langtools/tools/doclint/RecordParamsTest.out diff --git a/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclint/Checker.java b/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclint/Checker.java index e92d3a6ce0c..ed39cdb73dc 100644 --- a/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclint/Checker.java +++ b/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclint/Checker.java @@ -187,7 +187,7 @@ public class Checker extends DocTreePathScanner { 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 { 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 { 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; diff --git a/test/langtools/tools/doclint/MissingRecordParamsTest.java b/test/langtools/tools/doclint/MissingRecordParamsTest.java new file mode 100644 index 00000000000..07dbbe72ee8 --- /dev/null +++ b/test/langtools/tools/doclint/MissingRecordParamsTest.java @@ -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) { } diff --git a/test/langtools/tools/doclint/MissingRecordParamsTest.out b/test/langtools/tools/doclint/MissingRecordParamsTest.out new file mode 100644 index 00000000000..15e7e9df748 --- /dev/null +++ b/test/langtools/tools/doclint/MissingRecordParamsTest.out @@ -0,0 +1,4 @@ +MissingRecordParamsTest.java:12: warning: no @param for x +public record MissingRecordParamsTest(int x) { } + ^ +1 warning diff --git a/test/langtools/tools/doclint/RecordParamsTest.java b/test/langtools/tools/doclint/RecordParamsTest.java new file mode 100644 index 00000000000..19e3b3639d1 --- /dev/null +++ b/test/langtools/tools/doclint/RecordParamsTest.java @@ -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) { } diff --git a/test/langtools/tools/doclint/RecordParamsTest.out b/test/langtools/tools/doclint/RecordParamsTest.out new file mode 100644 index 00000000000..8c3929919d0 --- /dev/null +++ b/test/langtools/tools/doclint/RecordParamsTest.out @@ -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