8251200: False positive messages about missing comments for serializa…

…tion

Reviewed-by: hannesw

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/builders/SerializedFormBuilder.java

@@ -550,7 +550,7 @@ private static boolean serialClassInclude(Utils utils, TypeElement te) {
             return false;
         }
         if (utils.isSerializable(te)) {
-            if (!utils.getSerialTrees(te).isEmpty()) {
+            if (utils.hasDocCommentTree(te) && !utils.getSerialTrees(te).isEmpty()) {
                 return serialDocInclude(utils, te);
             } else if (utils.isPublic(te) || utils.isProtected(te)) {
                 return true;

src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/Utils.java

@@ -2685,35 +2685,24 @@ public TreePath getTreePath(Element e) {
      */
     private final Map<Element, DocCommentInfo> dcTreeCache = new LinkedHashMap<>();
 
+    /**
+     * Checks whether an element has an associated doc comment.
+     * @param element the element
+     * @return {@code true} if the element has a comment, and false otherwise
+     */
+    public boolean hasDocCommentTree(Element element) {
+        DocCommentInfo info = getDocCommentInfo(element);
+        return info != null && info.dcTree != null;
+    }
+
     /**
      * Retrieves the doc comments for a given element.
      * @param element
      * @return DocCommentTree for the Element
      */
     public DocCommentTree getDocCommentTree0(Element element) {
 
-        DocCommentInfo info = null;
-
-        ElementKind kind = element.getKind();
-        if (kind == ElementKind.PACKAGE || kind == ElementKind.OTHER) {
-            info = dcTreeCache.get(element); // local cache
-            if (info == null && kind == ElementKind.PACKAGE) {
-                // package-info.java
-                info = getDocCommentInfo(element);
-            }
-            if (info == null) {
-                // package.html or overview.html
-                info = configuration.cmtUtils.getHtmlCommentInfo(element); // html source
-            }
-        } else {
-            info = configuration.cmtUtils.getSyntheticCommentInfo(element);
-            if (info == null) {
-                info = dcTreeCache.get(element); // local cache
-            }
-            if (info == null) {
-                info = getDocCommentInfo(element); // get the real mccoy
-            }
-        }
+        DocCommentInfo info = getDocCommentInfo(element);
 
         DocCommentTree docCommentTree = info == null ? null : info.dcTree;
         if (!dcTreeCache.containsKey(element)) {
@@ -2738,6 +2727,33 @@ public DocCommentTree getDocCommentTree0(Element element) {
     }
 
     private DocCommentInfo getDocCommentInfo(Element element) {
+        DocCommentInfo info = null;
+
+        ElementKind kind = element.getKind();
+        if (kind == ElementKind.PACKAGE || kind == ElementKind.OTHER) {
+            info = dcTreeCache.get(element); // local cache
+            if (info == null && kind == ElementKind.PACKAGE) {
+                // package-info.java
+                info = getDocCommentInfo0(element);
+            }
+            if (info == null) {
+                // package.html or overview.html
+                info = configuration.cmtUtils.getHtmlCommentInfo(element); // html source
+            }
+        } else {
+            info = configuration.cmtUtils.getSyntheticCommentInfo(element);
+            if (info == null) {
+                info = dcTreeCache.get(element); // local cache
+            }
+            if (info == null) {
+                info = getDocCommentInfo0(element); // get the real mccoy
+            }
+        }
+
+        return info;
+    }
+
+    private DocCommentInfo getDocCommentInfo0(Element element) {
         // prevent nasty things downstream with overview element
         if (element.getKind() != ElementKind.OTHER) {
             TreePath path = getTreePath(element);

test/langtools/jdk/javadoc/doclet/testSerialMissing/TestSerialMissing.java

@@ -0,0 +1,78 @@
+/*
+ * Copyright (c) 2018, 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 8251200
+ * @summary False positive messages about missing comments for serialization
+ * @library /tools/lib ../../lib/
+ * @modules jdk.javadoc/jdk.javadoc.internal.api
+ *          jdk.javadoc/jdk.javadoc.internal.tool
+ * @build javadoc.tester.*
+ * @build toolbox.ToolBox javadoc.tester.*
+ * @run main TestSerialMissing
+ */
+
+import java.io.IOException;
+import java.nio.file.Path;
+
+import javadoc.tester.JavadocTester;
+import toolbox.ToolBox;
+
+public class TestSerialMissing extends JavadocTester {
+    public static void main(String... args) throws Exception {
+        TestSerialMissing tester = new TestSerialMissing();
+        tester.runTests(m -> new Object[] { Path.of(m.getName()) } );
+    }
+
+    ToolBox tb = new ToolBox();
+
+    @Test
+    public void testPackagePrivate(Path base) throws IOException {
+        Path src = base.resolve("src");
+        tb.writeJavaFiles(src,
+                """
+                    /** Module m. */
+                    module m { exports p; }
+                    """,
+                """
+                    package p;
+                    /** PUBLIC class. */
+                    public class PUBLIC extends Exception { }
+                    """,
+                """
+                    package p;
+                    // no comment: class should not be documented
+                    class PACKAGE_PRIVATE extends Exception { }
+                    """);
+
+        javadoc("-d", base.resolve("api").toString(),
+                "-sourcepath", src.toString(),
+                "--module", "m");
+        checkExit(Exit.OK);
+
+        // should not be any reference to PACKAGE_PRIVATE.java, such as for no comment
+        checkOutput(Output.OUT, false,
+                "PACKAGE_PRIVATE");
+    }
+}