On Wed, 7 Aug 2024 15:49:01 GMT, Hannes Wallnöfer <[email protected]> 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
Mostly OK. I'll go through it one more time tomorrow before giving the A-word.
I like how the general coding style is working out these days, in both code and
tests.
One question/suggestion, perhaps for followup work. I get that you do not want
the visual clutter of linking to locally defined type parameters, but would it
help to give a short tooltip (i.e. `title` attribute) in this situation even if
you do not also create a link.
Is this an interesting idea for any place where we cannot or do not create a
link?
-------------
PR Review: https://git.openjdk.org/jdk/pull/20494#pullrequestreview-2226235577
