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
In the Description, you write:
>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.
Just from reading that alone, (and not reading code or sample output yet) that
seems mildly questionable, in that we otherwise generally encourage the
provision of `@param` tags for all parameters, whether they are type-level or
member-level type-parameters, or plain old executable (constructor, method)
parameters.
-------------
PR Comment: https://git.openjdk.org/jdk/pull/20494#issuecomment-2274267176
