8275199: Bogus warning generated for serializable records

Reviewed-by: hannesw

Author: jonathan-gibbons

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

@@ -86,13 +86,8 @@ private ClassBuilder(Context context, TypeElement typeElement, ClassWriter write
         this.writer = writer;
         this.utils = configuration.utils;
         switch (typeElement.getKind()) {
-            case ENUM:
-                setEnumDocumentation(typeElement);
-                break;
-
-            case RECORD:
-                setRecordDocumentation(typeElement);
-                break;
+            case ENUM   -> setEnumDocumentation(typeElement);
+            case RECORD -> setRecordDocumentation(typeElement);
         }
     }
 
@@ -119,27 +114,15 @@ public void build() throws DocletException {
       * @throws DocletException if there is a problem while building the documentation
       */
      protected void buildClassDoc() throws DocletException {
-        String key;
-         switch (typeElement.getKind()) {
-             case INTERFACE:
-                 key = "doclet.Interface";
-                 break;
-             case ENUM:
-                 key = "doclet.Enum";
-                 break;
-             case RECORD:
-                 key = "doclet.RecordClass";
-                 break;
-             case ANNOTATION_TYPE:
-                 key = "doclet.AnnotationType";
-                 break;
-             case CLASS:
-                 key = "doclet.Class";
-                 break;
-             default:
-                 throw new IllegalStateException(typeElement.getKind() + " " + typeElement);
-         }
-        Content contentTree = writer.getHeader(resources.getText(key) + " "
+        String key = switch (typeElement.getKind()) {
+            case INTERFACE       -> "doclet.Interface";
+            case ENUM            -> "doclet.Enum";
+            case RECORD          -> "doclet.RecordClass";
+            case ANNOTATION_TYPE -> "doclet.AnnotationType";
+            case CLASS           -> "doclet.Class";
+            default -> throw new IllegalStateException(typeElement.getKind() + " " + typeElement);
+        };
+         Content contentTree = writer.getHeader(resources.getText(key) + " "
                 + utils.getSimpleName(typeElement));
         Content classContentTree = writer.getClassContentHeader();
 
@@ -467,7 +450,10 @@ private void setRecordDocumentation(TypeElement elem) {
             }
         }
 
-        for (VariableElement ve : utils.getFields(elem)) {
+        var fields = utils.isSerializable(elem)
+                ? utils.getFieldsUnfiltered(elem)
+                : utils.getFields(elem);
+        for (VariableElement ve : fields) {
             // The fields for the record component cannot be declared by the
             // user and so cannot have any pre-existing comment.
             Name name = ve.getSimpleName();

test/langtools/jdk/javadoc/doclet/testRecordTypes/TestRecordTypes.java

@@ -23,7 +23,7 @@
 
 /*
  * @test
- * @bug      8225055 8239804 8246774 8258338 8261976
+ * @bug      8225055 8239804 8246774 8258338 8261976 8275199
  * @summary  Record types
  * @library  /tools/lib ../../lib
  * @modules jdk.javadoc/jdk.javadoc.internal.tool
@@ -51,13 +51,11 @@ public static void main(String... args) throws Exception {
 
     private final ToolBox tb = new ToolBox();
 
-    // The following constants are set up for use with -linkoffline
-    // (but note: JDK 11 does not include java.lang.Record, so expect
-    // some 404 broken links until we can update this to a stable version.)
+    // The following constants are set up for use with -linkoffline.
     private static final String externalDocs =
-        "https://docs.oracle.com/en/java/javase/11/docs/api";
+        "https://docs.oracle.com/en/java/javase/17/docs/api";
     private static final String localDocs =
-        Path.of(testSrc).resolve("jdk11").toUri().toString();
+        Path.of(testSrc).resolve("jdk17").toUri().toString();
 
     @Test
     public void testRecordKeywordUnnamedPackage(Path base) throws IOException {
@@ -391,17 +389,17 @@ public record R(int r1) {
     }
 
     @Test
-    public void testExamples(Path base) throws IOException {
+    public void testExamples(Path base) {
         javadoc("-d", base.resolve("out-no-link").toString(),
                 "-quiet", "-noindex",
-                "-sourcepath", testSrc.toString(),
+                "-sourcepath", testSrc,
                 "-linksource",
                 "examples");
 
         checkExit(Exit.OK);
         javadoc("-d", base.resolve("out-with-link").toString(),
                 "-quiet", "-noindex",
-                "-sourcepath", testSrc.toString(),
+                "-sourcepath", testSrc,
                 "-linksource",
                 "-linkoffline", externalDocs, localDocs,
                 "examples");
@@ -560,4 +558,51 @@ public record R(@Deprecated int r1) { }""");
                     <div class="col-last even-row-color"></div>
                     </div>""");
     }
+
+    @Test
+    public void testSerializableType(Path base) throws IOException {
+        Path src = base.resolve("src");
+        tb.writeJavaFiles(src,
+                """
+                    /**
+                     * A point,
+                     * @param x the x coord
+                     * @param y the y coord
+                     */
+                    public record Point(int x, int y) implements java.io.Serializable { }""");
+
+        javadoc("-d", base.resolve("out").toString(),
+                "-quiet", "-noindex", "--no-platform-links",
+                src.resolve("Point.java").toString());
+        checkExit(Exit.OK);
+
+        checkOutput(Output.OUT, false,
+                "warning: no comment");
+
+        checkOutput("serialized-form.html", true,
+                """
+                    <section class="serialized-class-details" id="Point">
+                    <h3>Record Class&nbsp;<a href="Point.html" title="class in Unnamed Package">Point</a></h3>
+                    <div class="type-signature">class Point extends java.lang.Record implements java.io.Serializable</div>
+                    <ul class="block-list">
+                    <li>
+                    <section class="detail">
+                    <h4>Serialized Fields</h4>
+                    <ul class="block-list">
+                    <li class="block-list">
+                    <h5>x</h5>
+                    <pre>int x</pre>
+                    <div class="block">The field for the <a href="./Point.html#param-x"><code>x</code></a> record component.</div>
+                    </li>
+                    <li class="block-list">
+                    <h5>y</h5>
+                    <pre>int y</pre>
+                    <div class="block">The field for the <a href="./Point.html#param-y"><code>y</code></a> record component.</div>
+                    </li>
+                    </ul>
+                    </section>
+                    </li>
+                    </ul>
+                    </section>""");
+    }
 }

test/langtools/jdk/javadoc/doclet/testRecordTypes/jdk11/element-list test/langtools/jdk/javadoc/doclet/testRecordTypes/jdk17/element-list

@@ -2,10 +2,12 @@ module:java.base
 java.io
 java.lang
 java.lang.annotation
+java.lang.constant
 java.lang.invoke
 java.lang.module
 java.lang.ref
 java.lang.reflect
+java.lang.runtime
 java.math
 java.net
 java.net.spi
@@ -18,7 +20,6 @@ java.nio.file
 java.nio.file.attribute
 java.nio.file.spi
 java.security
-java.security.acl
 java.security.cert
 java.security.interfaces
 java.security.spec
@@ -35,6 +36,7 @@ java.util.concurrent.atomic
 java.util.concurrent.locks
 java.util.function
 java.util.jar
+java.util.random
 java.util.regex
 java.util.spi
 java.util.stream
@@ -131,14 +133,14 @@ javax.naming
 javax.naming.directory
 javax.naming.event
 javax.naming.ldap
+javax.naming.ldap.spi
 javax.naming.spi
 module:java.net.http
 java.net.http
 module:java.prefs
 java.util.prefs
 module:java.rmi
 java.rmi
-java.rmi.activation
 java.rmi.dgc
 java.rmi.registry
 java.rmi.server
@@ -219,12 +221,14 @@ module:jdk.hotspot.agent
 module:jdk.httpserver
 com.sun.net.httpserver
 com.sun.net.httpserver.spi
+module:jdk.incubator.foreign
+jdk.incubator.foreign
+module:jdk.incubator.vector
+jdk.incubator.vector
 module:jdk.jartool
 com.sun.jarsigner
 jdk.security.jarsigner
 module:jdk.javadoc
-com.sun.javadoc
-com.sun.tools.javadoc
 jdk.javadoc.doclet
 module:jdk.jcmd
 module:jdk.jconsole
@@ -241,6 +245,7 @@ module:jdk.jfr
 jdk.jfr
 jdk.jfr.consumer
 module:jdk.jlink
+module:jdk.jpackage
 module:jdk.jshell
 jdk.jshell
 jdk.jshell.execution
@@ -260,10 +265,8 @@ module:jdk.naming.rmi
 module:jdk.net
 jdk.net
 jdk.nio
-module:jdk.pack
-module:jdk.scripting.nashorn
-jdk.nashorn.api.scripting
-jdk.nashorn.api.tree
+module:jdk.nio.mapmode
+jdk.nio.mapmode
 module:jdk.sctp
 com.sun.nio.sctp
 module:jdk.security.auth
@@ -278,5 +281,4 @@ org.w3c.dom.css
 org.w3c.dom.html
 org.w3c.dom.stylesheets
 org.w3c.dom.xpath
-module:jdk.zipfs
-
+module:jdk.zipfs