[lworld] RFR: 8346035: [lworld] javadoc for value objects when enable preview [v2]

[Dan Smith]

On Thu, 12 Dec 2024 20:42:35 GMT, Roger Riggs <rriggs at openjdk.org> wrote:

>> Updated javadoc for value objects when preview is enabled.
>> 
>> Added text and decoration to highlight preview behavior of identity classes that are value classes with --enable-preview
>> The decorations are similar to the existing preview highlights for Preview classes and methods.
>> 
>> The updates include all of the wrapper classes, java.time, and java.util.Optional* and other classed annotated with @ValueBased.
>> 
>> The ValueBased is updated to describe the behavior when --enable-preview.
>
> Roger Riggs has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Tidy up ValueBased.html

src/java.base/share/classes/java/lang/Boolean.java line 51:

> 49:  * class; programmers should treat instances that are {@linkplain #equals(Object) equal}
> 50:  * as interchangeable and should not use instances for synchronization, mutexes, or
> 51:  * with {@linkplain java.lang.ref.Reference object references}.

We have a preview feature disclaimer for References.

Is there a similar one for mutexes? (What exactly do you mean by "mutexes"? Is it distinct from "synchronization"?)

src/java.base/share/classes/java/lang/Record.java line 74:

> 72:  *          When preview features are enabled, {@code Record} is
> 73:  *          an abstract {@linkplain Class#isValue value class}.
> 74:  *          Subclasses of {@code Number} can be either an {@linkplain Class#isIdentity identity class}

s/Number/Record/

src/java.base/share/classes/java/lang/doc-files/ValueBased.html line 48:

> 46:         visible change in the behavior of the class's methods;</li>
> 47:     <li>the class performs no synchronization using an instance's monitor;</li>
> 48:     <li>the class does not declare (or has deprecated any) accessible constructors;</li>

This one is still relevant, as a concrete case of the next bullet, right? A value-based class should not let clients control identity creation.

src/java.base/share/classes/java/lang/doc-files/ValueBased.html line 68:

> 66:     associated monitor.</p>
> 67: 
> 68: <p>When preview features are enabled, use of value class instances for synchronization, mutexes, or with

A value-based class is not necessarily a value class under preview.

I think this "behavior may change" disclaimer is trying to cover two cases, which should probably be identified directly:
- The class may choose to allocate/cache instances differently
- The class may choose to become a value class, and then [things may fail]

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

PR Review Comment: https://git.openjdk.org/valhalla/pull/1316#discussion_r1884529534
PR Review Comment: https://git.openjdk.org/valhalla/pull/1316#discussion_r1884518251
PR Review Comment: https://git.openjdk.org/valhalla/pull/1316#discussion_r1884520249
PR Review Comment: https://git.openjdk.org/valhalla/pull/1316#discussion_r1884526159