On Wed, 7 Aug 2024 15:49:01 GMT, Hannes Wallnöfer <hann...@openjdk.org> wrote:
>> Please review a JavaDoc change to make it possible to link to type parameter
>> documentation from automatically generated signatures as well as
>> user-defined `{@link ...}` and `@see ...` tags. The solution consists in
>> wrapping type parameter documentation into `<span
>> id="type-param-[type-param-name]">` elements for generic classes and `<span
>> id="[member-signature]-type-param-[type-param-name]">` for generic members.
>>
>> While this is not a very big change, there are a few aspects and
>> considerations that need to be explained.
>>
>> - Class-level type parameter documentation had to be moved out of the `<div
>> class="horizontal-scroll">` element for the main class description because
>> of [this bug in Chrome](https://issues.chromium.org/issues/40074749). The
>> only viable solution was to move the scroll container beneath the `<hr>`
>> element, which is the way it is already done for package and module pages.
>> This has almost no visual effects on the way pages are rendered, I'd be
>> happy to discuss the stylesheet tweaks if there's interest.
>>
>> - JavaDoc only creates links for type parameters in generic types, but not
>> those belonging to generic methods and constructors. While I added support
>> for linking member-level type parameters, I soon realized that these links
>> add a lot of visual noise by adding redundant links from member-level
>> descriptions and signatures to the details of the same member. Displaying
>> only type-level type parameters as links is actually quite helpful in
>> allowing to distinguish them from member-level type parameters. The
>> [documentation of
>> `java.util.Map`](https://cr.openjdk.org/~hannesw/8313931/api.02/java.base/java/util/Map.html#method-summary)
>> illustrates this nicely. The solution I settled for is to allow linking to
>> [member-level type
>> parameters](https://cr.openjdk.org/~hannesw/8313931/api.02/java.base/java/util/Set.html#of(E)-type-param-E)
>> using `{@link ...}` and `@see ...` tags if a `@param` tag is provided for
>> the type parameter, but not create such links for automatically generated
>> signatures.
>>
>> - Since `javadoc` will always create links for type parameters of generic
>> types, a link target with the appropriate `id` attribute has to be created
>> even if no `@param` tag for the type parameter is provided. This is done by
>> creating a span with the given `id` in the type signature shown in the main
>> heading of the page.
>>
>> - When type parameter documentation is displayed [as link
>> target](https://cr.openjdk.org/~hannesw/8313931/api.02/java.base/j...
>
> Hannes Wallnöfer has updated the pull request incrementally with one
> additional commit since the last revision:
>
> More post-merge cleanup
test/langtools/jdk/javadoc/doclet/testUnicode/TestUnicode.java line 104:
> 102: <dl class="notes">
> 103: <dt>Type Parameters:</dt>
> 104: <dd><span id="type-param-##"><code>##</code> - the
> ##</span></dd>
(Chuckle at the Chinese Elephant references!)
-------------
PR Review Comment: https://git.openjdk.org/jdk/pull/20494#discussion_r1707940337
