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

Reply via email to