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

[Hannes Wallnöfer]

On Mon, 30 Sep 2024 02:07:08 GMT, Joe Darcy <darcy at openjdk.org> wrote:

>> `<dfn>` is a semantic tag to indicate the defining instance of a term. It may be used by search engines, to improve their results.   When `<dfn>` is used as intended, it may be reasonable and convenient to put an `id` on the tag, to provide a link target for elsewhere in the documentation. It may also be convenient to add `id` to other locations, especially headers, but note that `javadoc` now does that automatically.
>> 
>> The usage of `<a name="...">` is a legacy usage from HTML 4, before the improved rules for `id` in HTML 5.  It would be a reasonable cleanup to move away from such tags, putting an equivalent `id` on either a replacement tag (such as `<span>`) or on an appropriate nearby tag.
>
> Thanks for the HTML tip; will add an id to the dfn tag.

Adding the `id` attribute to the `dfn` tag is an improvement over the `<a name=...>` tag, but the embedded `{@index ...}` tag already generates a `span` tag with a very similar id derived from the tag content, in this case `id="wrapperclasses"`. Although there may be some benefits to defining an anchor explicitly, having two very similar `id` attributes seems redundant and error-prone. My preference would be to omit the `id` from the `dfn` tag and just use the one generated by the `{@index ...}` tag in the new links.

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

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