Please review a change to use simple raw parameter type names in method
signatures generated by `@link` and `@see` tags. This is the same signature
format we use for methods in the table of contents sidebar.
The change only applies if the method reference doesn't contain a signature
(i.e. method name only as in `{@link #set}`). If the reference in the tag
includes a signature, that signature continues to be used in the link label
(i.e. `{@link #set(Object)}` or `{@link #set(java.lang.Object)}`).
The argument for using simple and raw type names is:
- The purpose of a method link label is to make the user understand which
method we're talking about, and that requires recognizing the number and type
names of parameters. Using fully qualified type names and possibly type
parameters with bounded wildcards makes both much harder and is not required at
this stage.
- If information about package names or type parameters of parameter types is
required, that's what the link to the method details is for (possibly clicking
through to the parameter type).
Here is a before/after comparison of a rather typical case in
`MethodHandles.collectArguments`:
<img width="763" alt="methodhandles-full"
src="https://github.com/user-attachments/assets/c4ada44b-7c2e-4e54-9535-c5e7a576ca35";>
<img width="482" alt="methodhandles-simple"
src="https://github.com/user-attachments/assets/8a5e04f1-8be2-4b8a-8b98-d1888f386702";>
Here's a before/after comparison that shows the effect on fully qualified type
names with bounded wildcards in `CompletionStage.exceptionallyAsync`:
<img width="718" alt="completionhandler-full"
src="https://github.com/user-attachments/assets/021b717e-a493-4110-9fda-848ed314ba51";>
<img width="710" alt="completionhandler-simple"
src="https://github.com/user-attachments/assets/e1f0b97b-92c0-49e2-93a1-eced52b46434";>
-------------
Commit messages:
- 8345664: Use simple parameter type names in @link and @see tags
Changes: https://git.openjdk.org/jdk/pull/22608/files
Webrev: https://webrevs.openjdk.org/?repo=jdk&pr=22608&range=00
Issue: https://bugs.openjdk.org/browse/JDK-8345664
Stats: 29 lines in 6 files changed: 13 ins; 1 del; 15 mod
Patch: https://git.openjdk.org/jdk/pull/22608.diff
Fetch: git fetch https://git.openjdk.org/jdk.git pull/22608/head:pull/22608
PR: https://git.openjdk.org/jdk/pull/22608
