On Mon, 30 Sep 2024 11:41:19 GMT, Pavel Rappo <pra...@openjdk.org> wrote:
>> 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.
>
> Fair enough, @hns. Initially, I thought to reply to you that we don't seem to
> specify the form of id generated by `@index` and that, in fact, it would be
> more error-prone for an author to guess/compute it in their head. For
> example, I would expect automatically generated ids to be camelCased.
>
> But then I recalled the design of the `@index` tag and realised that the
> author does not have to think about the id. Just like index in good old paper
> books, javadoc index does not discriminate between referring and the
> defining sites of a term. Sites are simply grouped by the term.
>
> However, if the term is even slightly different ("wrapper class" vs "wrapper
> classES"), the author does not get the desired indexing without working
> around javadoc. Seems like `@index` might be too inflexible.
>
> Here's a real case of bad index. Those entries are really about the same
> term, but that's currently inexpressible with `@index` without restructuring
> one of the sites:
>
> *
> https://docs.oracle.com/en/java/javase/23/docs/api/java.compiler/javax/lang/model/package-summary.html#Javalanguagemodel
>
> *
> https://docs.oracle.com/en/java/javase/23/docs/api/java.compiler/module-summary.html#LanguageModel
@pavelrappo if the goal is to define a different search term/anchor, then an
explicit additional `id` is certainly justified. Regarding the last example, it
is ok to use the same search term on different pages/classes. It's only within
one HTML page that duplicate id's are invalid.
-------------
PR Review Comment: https://git.openjdk.org/jdk/pull/21215#discussion_r1781063866
