On Fri, 6 Dec 2024 15:25:47 GMT, Hannes Wallnöfer <hann...@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";>

This pull request has now been integrated.

Changeset: 573bcb61
Author:    Hannes Wallnöfer <hann...@openjdk.org>
URL:       
https://git.openjdk.org/jdk/commit/573bcb61809cbd98ec52d159d0c8e030e4a8e3f5
Stats:     29 lines in 6 files changed: 13 ins; 1 del; 15 mod

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

Reviewed-by: liach

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

PR: https://git.openjdk.org/jdk/pull/22608

Reply via email to