RFR: 8345664: Use simple parameter type names in @link and @see tags

[Hannes Wallnöfer]

On Fri, 6 Dec 2024 15:25:47 GMT, Hannes Wallnöfer <hannesw at openjdk.org> wrote:

> 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 useful 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">

Thanks!

-------------

PR Comment: https://git.openjdk.org/jdk/pull/22608#issuecomment-2523700689