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
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/resources/script.js.template
line 239:
> 237: link.addEventListener("click", (e) => {
> 238: const href = e.currentTarget.getAttribute("href");
> 239: if (href && href.startsWith("#") &&
> href.indexOf("type-param-") > -1) {
Does the `href.startsWith("#")` mean that this only works for references within
the same file? Is it even a sensible question to wonder if you can link to type
parameters in other files?
test/langtools/jdk/javadoc/doclet/testLinkTaglet/TestLinkTagletTypeParam.java
line 49:
> 47: ToolBox tb = new ToolBox();
> 48:
> 49: @JavadocTester.Test
Is there a reason to use `JavadocTester.Test` and not just `Test`, as is common
in other tests?
-------------
PR Review Comment: https://git.openjdk.org/jdk/pull/20494#discussion_r1707907084
PR Review Comment: https://git.openjdk.org/jdk/pull/20494#discussion_r1707910674
