On Wed, 7 Aug 2024 15:18:59 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/java/util/HashSet.html#...
This pull request has now been integrated.
Changeset: 14071607
Author: Hannes Wallnöfer <hann...@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
