On Mon, 30 Sep 2024 02:07:08 GMT, Joe Darcy <da...@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
