On Tue, 21 Jan 2025 19:41:39 GMT, Phil Race <p...@openjdk.org> wrote:
>> Please review a doc-only change to mostly add missing `@serial` javadoc >> tags. This is a sub-task of [JDK-8286931] to allow us to re-enable the >> javadoc `-serialwarn` option in the JDK doc build, which has been disabled >> since JDK 19. >> >> [JDK-8286931]: https://bugs.openjdk.org/browse/JDK-8286931 >> >> For private and package-private serialized fields that already have a doc >> comment, the main description is converted to a block tag by prepending >> `@serial` since these fields do not require a main description. For >> protected and public serialized fields that require a main description, an >> empty `@serial` block tag is appended to the doc comment instead. The effect >> is the same, as the main description is used in `serial-form.html` if the >> `@serial` tag is missing or empty. For those fields that do not have a doc >> comment, a doc comment with an empty `@serial` tag is added. >> >> Apart from missing `@serial` tags, this PR also adds a `@serialData` tag to >> `java.awt.datatransfer.DataFlavor.writeExternal(ObjectOutput)` that the >> javadoc `-serialwarn` option complains about. This is the only change in >> this PR that adds documentation text and causes a change in the generated >> documentation. > > src/java.datatransfer/share/classes/java/awt/datatransfer/DataFlavor.java > line 1288: > >> 1286: >> 1287: /** >> 1288: * Serializes this {@code DataFlavor}. > > This most definitely changes the serialisation spec. So a CSR is needed. > Also shouldn't readExternal be updated to correspond ? Only the `writeExternal` method is required to have a `@serialData` tag in order to keep javadoc running with `-serialwarn` option from complaining. I guess the thinking is that the `readExternal` logic can be derived from that. @prrace do you have any suggestions for the spec change, or are you ok with the proposed wording? ------------- PR Review Comment: https://git.openjdk.org/jdk/pull/22980#discussion_r1924979277
