RFR: JDK-8192935 Fix EnumSet's SerializationProxy javadoc

[Stuart Marks]

On 12/1/17 4:42 PM, Martin Buchholz wrote:
>     1. JDK-8192935 <https://bugs.openjdk.java.net/browse/JDK-8192935>
> 
> http://cr.openjdk.java.net/~martin/webrevs/openjdk10/EnumSet-SerializationProxy/EnumSet-SerializationProxy.patch

--- a/src/java.base/share/classes/java/util/EnumSet.java
+++ b/src/java.base/share/classes/java/util/EnumSet.java
@@ -75,7 +75,6 @@
   * @author Josh Bloch
   * @since 1.5
   * @see EnumMap
- * @serial exclude
   */

I suspect you're following other examples in the JDK that include the serial 
form documentation for a class that uses a serialization proxy, but I think this 
is a mistake. It's a mistake because this will cause EnumSet to appear in 
serialized-form.html, but EnumSet actually should *never* appear in any 
serialized byte stream. This is quite confusing. I think those other places 
should be fixed, instead.

Instead of including EnumSet itself in the serialized-form.html, how about 
restoring its "@serial exclude" and then putting a link directly from the 
EnumSet class doc to the EnumSet.SerializationProxy serial form doc? Something like

  * <p>When an instance of this class is serialized, it is replaced with the 

  * serial form of an instance of 

  * <a href="../../serialized-form.html#java.util.EnumSet.SerializationProxy"> 

  * {@code EnumSet.SerializationProxy}</a>. 


The changes to EnumSet.SerializationProxy class are good.

s'marks