RFR: 8313931: Javadoc: links to type parameters actually generate links to classes [v3]

[Jonathan Gibbons]

On Wed, 7 Aug 2024 15:49:01 GMT, Hannes Wallnöfer <hannesw at 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

Marked as reviewed by jjg (Reviewer).

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

PR Review: https://git.openjdk.org/jdk/pull/20494#pullrequestreview-2229006081