[lworld] RFR: 8346307: [lworld] Clarify identity vs value in Class, Objects, and document limitations of value objects [v3]

[Roger Riggs]

On Mon, 13 Jan 2025 22:09:42 GMT, Roger Riggs <rriggs at openjdk.org> wrote:

>> Add APINote  and javadoc for IdentityException where it will be useful to know that identity or value objects are treated differently. 
>> Simplified WeakHashMap javadoc updates for IdentityException. 
>> Added note to System.identityHashCode to include value objects.
>> Added to class javadoc for IdentityHashMap for value objects.
>
> Roger Riggs has updated the pull request incrementally with two additional commits since the last revision:
> 
>  - Merge remote-tracking branch 'refs/remotes/origin/8346307-throws-identityexception' into 8346307-throws-identityexception
>  - 8346307: [lworld] Document WeakHashMap and other apis that may throw IdentityException
>    Add APINote and javadoc for IdentityException where it will be useful to know.
>    Updated Objects.hasIdentity to return true for non-null reference to identity class; else false
>    Added Objects.isValueObject to return true for non-null reference to value class; else false
>    Updated tests for value objects.

I've been trying out the various incarnations of the javadoc support to see how they work, but that can be a separate PR when it settles.

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

PR Comment: https://git.openjdk.org/valhalla/pull/1327#issuecomment-2635022869