On Sat, 28 Sep 2024 21:45:09 GMT, Chen Liang <li...@openjdk.org> wrote:
>> 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
>
> Agree; I have recommedned consolidating id property into h2 without an extra
> a tag.
`<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.
-------------
PR Review Comment: https://git.openjdk.org/jdk/pull/21215#discussion_r1780100498
