RFR: JDK-8192935 Fix EnumSet's SerializationProxy javadoc

[Roger Riggs]

Hi Stuart,

On 12/4/2017 4:23 PM, Stuart Marks wrote:
>
>
> 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.
I wouldn't argue with javadoc tool being improved, but with the tools 
available...
>
> 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.)
Another alternative is to define ObjectStreamField[] 
serialPersistentFields = {};

>
> 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.
I disagree here since it implements Serializable and needs to be indexed 
as such.
>
> 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.

Roger