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://download.java.net/java/early_access/jdk24/docs/api/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 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, it is rendered
with a visual highlight, which is similar to the one used for `{@index ...}`
tags but fades out after a few seconds. The purpose is to make the type
parameter documentation recognizable as link target. While we found that a
temporary highlight is sufficient for this use case, `{@index ...}` and related
tags continue to use a permanent highlight.
I wanted to upload sample documentation to `cr.openjdk.org`, but unfortunately
I'm currently unable to connect to the server. I'll try again later.
-------------
Commit messages:
- Remove trailing whitespace
- JDK-8313931: Javadoc: links to type parameters actually generate links to
classes
Changes: https://git.openjdk.org/jdk/pull/20494/files
Webrev: https://webrevs.openjdk.org/?repo=jdk&pr=20494&range=00
Issue: https://bugs.openjdk.org/browse/JDK-8313931
Stats: 348 lines in 26 files changed: 257 ins; 12 del; 79 mod
Patch: https://git.openjdk.org/jdk/pull/20494.diff
Fetch: git fetch https://git.openjdk.org/jdk.git pull/20494/head:pull/20494
PR: https://git.openjdk.org/jdk/pull/20494
