RFR: 8254275: Development to revise "value-based class" & apply to wrappers [v2]

[Dan Smith]

On Fri, 16 Oct 2020 17:13:10 GMT, Dan Smith <dlsmith at openjdk.org> wrote:

>> In the text referring to ValueBase.html in many classes:
>> 
>> Is the "," misplaced.  Should it read:
>> "not use instances for synchronization or unpredictable behavior may occur."
>> 
>> If the comment in each class was a simple reference to ValueBased, it would be easier to maintain and there would be
>> less duplication between lots of classes and the explanation in ValueBased.html.
>
>> In the text referring to ValueBase.html in many classes:
>> 
>> Is the "," misplaced. Should it read:
>> "not use instances for synchronization or unpredictable behavior may occur."
> 
> Grammatically, it's a compound sentence. Two statements: 1) programmers should do some stuff; 2) otherwise,
> unpredictable behavior. The comma helps to communicate where the "parentheses" go: (1a && 1b) || 2.
> But I think you may be concerned that the "unpredictable behavior" only applies to the synchronization part of (1), not
> the "interchangeable" part? It's my intent that it applies to both. If you try to distinguish between instances with
> ==, or do synchronization, behavior will be unpredictable (because it's possible things that were != yesterday will be
> == today, per the rules about factories).
>> If the comment in each class was a simple reference to ValueBased, it would be easier to maintain and there would be
>> less duplication between lots of classes and the explanation in ValueBased.html.
> 
> Yes. This approach of scattering boilerplate throughout the API is not optimized for maintainability. But that's okay,
> because change will not be frequent, and meanwhile it's optimized for getting readers' attention instead. I would worry
> that if we stripped out all the boilerplate and just had a link, most readers wouldn't follow the link or appreciate
> what it meant.

Pushed some updates; here's an updated docs build:
http://cr.openjdk.java.net/~dlsmith/8254275/8254275-20201016/api/index.html

-------------

PR: https://git.openjdk.java.net/valhalla/pull/222