RFR: JDK-8192935 Fix EnumSet's SerializationProxy javadoc

[Stuart Marks]

>>     If you don't like my alternative, fine; it has its own set of tradeoffs
>>     that might be net positive or negative. If you want to proceed with the
>>     current approach, then I won't stand in the way. At the very least there
>>     should be some boilerplate added to EnumSet that makes it clear that
>>     EnumSet itself never appears in the serial form.
>     I don't disagree, there are many things that could be improved.
> 
> I only volunteered to bring EnumSet (as the poster child for the Serialization 
> Proxy Pattern) into a no-worse state than other classes implementing the 
> pattern.  The doc of the writeReplace and readObject methods is pretty good 
> implicit documentation that the pattern applies here.  Serialization overall 
> remains as deeply flawed as ever.
> 
> I still plan to submit what I have now.

Thanks for volunteering. It goes to show that no good deed goes unpunished. :-)

To close the loop on this, I think what you have is acceptable. I also think 
that "no-worse state" is a better characterization than "Best Practice," which 
seems to imply that no further improvement is possible or necessary. And 
finally, Jon Gibbons has filed JDK-8193019 to cover future javadoc enhancements 
to better support serialization.

s'marks