RFR: JDK-8192935 Fix EnumSet's SerializationProxy javadoc

[Stuart Marks]

On 12/4/17 12:36 PM, Martin Buchholz wrote:
> On Mon, Dec 4, 2017 at 12:12 PM, Roger Riggs <Roger.Riggs at oracle.com> wrote:
>> The java.time APIs refined the pattern used for Serialization proxies to
>> document the relationship between
>> the original class and its serialization proxies methods.
>>
> 
> Right.  I was aware of the effort that java.time people put into their
> serialization code.  They did a good job, and my proposed change makes it
> more like theirs (but even more like the ones in j.u.c.a.)

Hi Martin, Roger,

I disagree that the java.time approach is a Best Practice (capitalized), as 
Martin said, for dealing with documentation of serial proxies. It's a workaround 
for lack of support for this pattern in the javadoc tool.

Having the redeclare all the fields of EnumSet as transient is evidence of this. 
(IMO the java.time classes are worse, as they include the fields of objects that 
are replaced by the proxy.)

Having the original class appear in the serialized form documentation is a bug, 
since it never appears in the serial form. It sort-of helps define the 
relationship between the original class and the proxy, but in a confusing, 
roundabout way.

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.

s'marks