RFR: 8341064: Define anchor point and index term for "wrapper classes" [v3]

[Pavel Rappo]

On Sat, 28 Sep 2024 15:02:50 GMT, Joe Darcy <darcy at openjdk.org> wrote:

>> The is the initial version of a PR to defined an anchor point and index term of "wrapper classes."
>
> Joe Darcy has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Respond to review feedback.

src/java.base/share/classes/java/lang/package-info.java line 34:

> 32:  * <p>Frequently it is necessary to represent a value of primitive
> 33:  * type as if it were an object.<a id="wrapperClasses"></a> The
> 34:  * <dfn>{@index "wrapper classes"}</dfn> {@link Boolean}, {@link

I can see that JDK uses the `<a name="xyz"></a>` pattern in many locations. That is, an empty `a` tag which has the `name` attribute. You use the `id` attribute. JDK uses such pattern too, but only in a few locations.

Regardless of the details, I was wondering if instead of adding a new tag with an attribute, we should just add an attribute to an existing tag.

`dfn` seems to be designed exactly for that [^1][^2]. Additionally, keeping tags to a minimum might not worsen readability as much:

    <dfn id="wrapperClasses">{@index "wrapper classes"}</dfn>

@jonathan-gibbons, @hns, thoughts?

[^1]: https://html.spec.whatwg.org/multipage/text-level-semantics.html#the-dfn-element
[^2]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/dfn

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

PR Review Comment: https://git.openjdk.org/jdk/pull/21215#discussion_r1779774865