RFR: JDK-8275199: Bogus warning generated for serializable records [v2]

[Hannes Wallnöfer]

On Fri, 22 Oct 2021 02:11:34 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> Please review a trivial fix and simple test for DocLint and serializable records.
>> 
>> Although the original JBS issue was somewhat confused, the underlying cause of the test case is that `javadoc`/`DocLint` was checking the comments on the private internal fields, prior to writing the fields in the "Serialized Form" page.  Since the serialized form is defined to be exactly the record components, there is no need to document the fields, as explained in section 1.13, Serialization of Records. 
>> https://docs.oracle.com/en/java/javase/17/docs/specs/serialization/serial-arch.html#serialization-of-records
>> 
>>> Documenting serializable fields and data for record classes is unnecessary, since there is no variation in the serial form, other than whether a substitute or replacement object is used.
>> 
>> ## Update
>> 
>> Based on feedback, the proposed implementation is changed to always generate entries for the private fields in the serialized form for serializable records.   This just requires that we now always generate the comments for the private fields for serializable records. If the comments are generated, they will be picked up automatically by `SerializedFormBuilder`
>
> Jonathan Gibbons has updated the pull request incrementally with one additional commit since the last revision:
> 
>   update to show fields of serializable records in the serializable form

The changes look good to me. 

It seems like the serializable record is created dynamically although a similar class is already available in the static test files.

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

> 453:         var fields = utils.isSerializable(elem)
> 454:                 ? utils.getFieldsUnfiltered(elem)
> 455:                 : utils.getFields(elem);

I guess the fields are filtered for inclusion later on, otherwise they would be included in the record's class docuentation as well?

test/langtools/jdk/javadoc/doclet/testRecordTypes/TestRecordTypes.java line 573:

> 571:                      */
> 572:                     public record Point(int x, int y) implements java.io.Serializable { }""");
> 573: 

I just noted the static files in the `examples` directory already contain a `public record SerializablePoint(int x, int y) implements Serializable { }`, but it seems the output is never checked. Not an error, just a bit of tiny bit of wasted resources.

-------------

Marked as reviewed by hannesw (Reviewer).

PR: https://git.openjdk.java.net/jdk/pull/6071