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

[Hannes Wallnöfer]

On Mon, 30 Sep 2024 11:41:19 GMT, Pavel Rappo <prappo at 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