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

[Roger Riggs]

On Fri, 13 Dec 2024 20:52:55 GMT, Dan Smith <dlsmith at openjdk.org> wrote:

>> 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.
>
> Could maybe soften to "(or discourages use of any)"...

I understood we've reversed the thinking of deprecating constructors for value classes, i.e. Integer.
They don't need to be deprecated. Saying `new Integer(3)` does not give it identity (with --enable-preview).
In the short term, the deprecation warning raises awareness in the non-enable-review case.
This text is trying to cover two similar but not identical states, one as a recommendation for non-preview and the other for preview enabled.

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

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