[lworld] RFR: 8346035: javadoc value cleanup

[Chen Liang]

On Wed, 11 Dec 2024 22:02:25 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.

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

> 68:     {@link java.lang.IdentityException} is thrown.</p>
> 69: 
> 70: <p>When preview features are enabled, use of value class instances for synchronization, mutexes, or with

Should we include the 

<div class="preview-block">
     <div class="preview-comment">

blocks here?

src/java.base/share/classes/java/time/ZoneId.java line 167:

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

Should we add the preview warning with rewords, like

When preview features are enabled, all implementations of {@code ZoneId} are {@linkplain Class#isValue value class}. ...

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

PR Review Comment: https://git.openjdk.org/valhalla/pull/1316#discussion_r1881083595
PR Review Comment: https://git.openjdk.org/valhalla/pull/1316#discussion_r1881181544