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