From 9ba8a12cfbb3d7d17be454e29ee6ff476c8690c2 Mon Sep 17 00:00:00 2001
From: Jonathan Gibbons <jjg@openjdk.org>
Date: Wed, 11 Aug 2021 18:04:29 +0000
Subject: [PATCH] 8269774: doclint reports missing javadoc comments for JavaFX
properties if the docs are on the property method
Reviewed-by: kcr, hannesw
---
.../builders/MemberSummaryBuilder.java | 2 +-
.../TestJavaFXMissingPropComments.java | 159 ++++++++++++++++++
2 files changed, 160 insertions(+), 1 deletion(-)
create mode 100644 test/langtools/jdk/javadoc/doclet/testJavaFX/TestJavaFXMissingPropComments.java
diff --git a/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/builders/MemberSummaryBuilder.java b/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/builders/MemberSummaryBuilder.java
index 7aa0d29c8d2..a61119ed6e1 100644
--- a/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/builders/MemberSummaryBuilder.java
+++ b/src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/builders/MemberSummaryBuilder.java
@@ -486,7 +486,7 @@ public abstract class MemberSummaryBuilder extends AbstractMemberBuilder {
VariableElement field,
ExecutableElement getter,
ExecutableElement setter) {
- if (field == null || builder.utils.getDocCommentTree(field) == null) {
+ if (field == null || !builder.utils.hasDocCommentTree(field)) {
addToPropertiesMap(propertyMethod, propertyMethod);
addToPropertiesMap(getter, propertyMethod);
addToPropertiesMap(setter, propertyMethod);
diff --git a/test/langtools/jdk/javadoc/doclet/testJavaFX/TestJavaFXMissingPropComments.java b/test/langtools/jdk/javadoc/doclet/testJavaFX/TestJavaFXMissingPropComments.java
new file mode 100644
index 00000000000..ae6b50827c2
--- /dev/null
+++ b/test/langtools/jdk/javadoc/doclet/testJavaFX/TestJavaFXMissingPropComments.java
@@ -0,0 +1,159 @@
+/*
+ * Copyright (c) 2021, 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.
+ */
+
+/*
+ * @test
+ * @bug 8269774
+ * @summary doclint reports missing javadoc comments for JavaFX properties if the docs are on the property method
+ * @library /tools/lib ../../lib
+ * @modules jdk.javadoc/jdk.javadoc.internal.tool
+ * @build toolbox.ToolBox javadoc.tester.*
+ * @run main TestJavaFXMissingPropComments
+ */
+
+import java.nio.file.Path;
+
+import javadoc.tester.JavadocTester;
+import toolbox.ToolBox;
+
+public class TestJavaFXMissingPropComments extends JavadocTester {
+
+ public static void main(String... args) throws Exception {
+ TestJavaFXMissingPropComments tester = new TestJavaFXMissingPropComments();
+ tester.runTests(m -> new Object[] { Path.of(m.getName()) });
+ }
+
+ ToolBox tb = new ToolBox();
+
+ @Test
+ public void testMissingFieldComments(Path base) throws Exception {
+ Path src = base.resolve("src");
+ tb.writeJavaFiles(src, """
+ package p;
+ /** Class comment. */
+ public class C {
+ /** Dummy class. */
+ public static class BooleanProperty { }
+
+ // no comment
+ private BooleanProperty value;
+
+ /**
+ * The value property (property method comment).
+ * @return the property object
+ */
+ public BooleanProperty valueProperty() {
+ return value;
+ }
+
+ // no comment
+ public boolean getValue() {
+ return true;
+ }
+ }
+ """);
+
+ javadoc("-d", base.resolve("api").toString(),
+ "--javafx",
+ "--disable-javafx-strict-checks",
+ "-sourcepath", src.toString(),
+ "p"
+ );
+ checkExit(Exit.OK);
+
+ // no warnings for any missing comments
+ checkOutput(Output.OUT, false,
+ "warning: no comment");
+
+ checkOutput("p/C.html", true,
+ """
+ <section class="detail" id="getValue()">
+ <h3>getValue</h3>
+ <div class="member-signature"><span class="modifiers">public</span> <span c\
+ lass="return-type">boolean</span> <span class="element-name">getValue</span\
+ >()</div>
+ <div class="block">Gets the value of the property value.</div>
+ <dl class="notes">
+ <dt>Property description:</dt>
+ <dd>The value property (property method comment).</dd>
+ </dl>
+ </section>"""
+ );
+ }
+
+ @Test
+ public void testWithFieldComments(Path base) throws Exception {
+ Path src = base.resolve("src");
+ tb.writeJavaFiles(src, """
+ package p;
+ /** Class comment. */
+ public class C {
+ /** Dummy class. */
+ public static class BooleanProperty { }
+
+ /** The value property (field comment). */
+ private BooleanProperty value;
+
+ /**
+ * The value property (property method comment).
+ * @return the property object
+ */
+ public BooleanProperty valueProperty() {
+ return value;
+ }
+
+ // no comment
+ public boolean getValue() {
+ return true;
+ }
+ }
+ """);
+
+ javadoc("-d", base.resolve("api").toString(),
+ "--javafx",
+ "--disable-javafx-strict-checks",
+ "-sourcepath", src.toString(),
+ "p"
+ );
+ checkExit(Exit.OK);
+
+ // no warnings for any missing comments
+ checkOutput(Output.OUT, false,
+ "warning: no comment");
+
+ checkOutput("p/C.html", true,
+ """
+ <section class="detail" id="getValue()">
+ <h3>getValue</h3>
+ <div class="member-signature"><span class="modifiers">public</span> <span c\
+ lass="return-type">boolean</span> <span class="element-name">getValue</span\
+ >()</div>
+ <div class="block">Gets the value of the property value.</div>
+ <dl class="notes">
+ <dt>Property description:</dt>
+ <dd>The value property (field comment).</dd>
+ </dl>
+ </section>"""
+ );
+ }
+}