On Fri, 22 Oct 2021 02:11:34 GMT, Jonathan Gibbons <j...@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
