On Mon, 10 Aug 2026 19:30:32 GMT, Joe Darcy <[email protected]> wrote:
>> 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.
Inline usage works like `{@jls value-objects-15.21.3}`, which renders
"§15.21.3<sup>PREVIEW</sup>".
-------------
PR Review Comment: https://git.openjdk.org/jdk/pull/32158#discussion_r3752868740
