On Fri, 7 Aug 2026 22:00:38 GMT, Joe Darcy <[email protected]> wrote:
>> FYI, John and I agreed to address the broader need to define some core
>> concepts related to identity and == via JDK-8389875.
>
> Okay; work can resume on this issue once the broader document is available.
> Edit: if we're looking to this as the definitive word on "indistinguishable",
> I would drop "completely" and italicize "indistinguishable".
>
> But we can link to JLS from the specs. Maybe even better to turn
> "indistinguishable" into a link to 15.21.3? (In value-objects-jls.html today,
> eventually in JLS proper.)
Just on the logistics front, for an in-line reference to the JLS the typical
idiom looks something like
...elements with default values (JLS {@jls 9.6.2})
...in section {@jls 12.4} of <cite>The Java Language Specification</cite>
There is a newer idiom to allow at least block references to preview spec
documents:
`* @jls value-objects-8.1.1.5 {@code value} Classes`
However, I don't know if this works for in-line usage.
In any case, I think it is preferable for java.lang.Object to primarily link to
some API-level discussion of this concept, which in turn would have the
appropriate links to preview or final JLS text.
-------------
PR Review Comment: https://git.openjdk.org/jdk/pull/32158#discussion_r3752716603
