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

[Dan Smith]

On Mon, 16 Dec 2024 16:19:26 GMT, Roger Riggs <rriggs at openjdk.org> wrote:

>> 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.

This document is primarily meant for API users who are not using preview features.

The general rule, covered by the next bullet, is that a value-based (identity) class API will not expose identity creation. As applied to constructors, that means these classes shouldn't have public constructors. However, we want to allow for classes like Integer that have public constructors, but have deprecated them.

In contrast, yes, a _value class_ doesn't need to worry about exposing constructors, because those don't expose any kind of identity creation anymore. After migrating Integer to be a value class, we can un-deprecate its constructors. (And thus, for now we can undo "forRemoval", since we know we don't intend to remove them.)

I'd be happy to say "the class does not declare (or discourages use of any) accessible constructors;".

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

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