On Mon, 30 Sep 2024 12:53:26 GMT, Hannes Wallnöfer <hann...@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
