Integrated: 8313931: Javadoc: links to type parameters actually generate links to classes

[Hannes Wallnöfer]

On Wed, 7 Aug 2024 15:18:59 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/java/util/HashSet.html#...

This pull request has now been integrated.

Changeset: 14071607
Author:    Hannes Wallnöfer <hannesw at openjdk.org>
URL:       https://git.openjdk.org/jdk/commit/140716078694a338e2c2f837841761262cee5542
Stats:     348 lines in 26 files changed: 257 ins; 12 del; 79 mod

8313931: Javadoc: links to type parameters actually generate links to classes

Reviewed-by: jjg

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

PR: https://git.openjdk.org/jdk/pull/20494