On Mon, 30 Sep 2024 10:36:55 GMT, Hannes Wallnöfer <hann...@openjdk.org> wrote:
>> 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.
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
-------------
PR Review Comment: https://git.openjdk.org/jdk/pull/21215#discussion_r1780960886
