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

[Joe Darcy]

On Mon, 30 Sep 2024 12:53:26 GMT, Hannes Wallnöfer <hannesw at openjdk.org> wrote:

>> 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.

I'm going to push this PR as-is. Any cleanup in index terms and `id`s can happen in a subsequent changeset. Thanks.

-------------

PR Review Comment: https://git.openjdk.org/jdk/pull/21215#discussion_r1781412401