RFR: 8365428: Unclear comments on java.lang.invoke Holder classes [v3]

[Chen Liang]

On Thu, 4 Sep 2025 17:56:07 GMT, Jorn Vernee <jvernee at openjdk.org> wrote:

>> Chen Liang has updated the pull request incrementally with one additional commit since the last revision:
>> 
>>   More ioi review
>
> src/java.base/share/classes/java/lang/invoke/BoundMethodHandle.java line 46:
> 
>> 44: /// arguments for currying.
>> 45: ///
>> 46: /// Each BMH acts like a strongly-typed argument list, where the types are
> 
> What do you mean with 'strongly-typed argument list'? Bound method handles are not just used for arguments.
> 
> I'd described BMH as method handles with a number of extra fields that can be referenced from its lambda form.

Yep, I reworded to:

> Each BMH class supports a number of values, each of a particular [BasicType].
> This per-class value type and count information is recorded by [SpeciesData].
> A [Specializer] manages lookup for any species.

> src/java.base/share/classes/java/lang/invoke/GenerateJLIClassesHelper.java line 58:
> 
>> 56: ///
>> 57: /// Since lambda forms and bound method handle species are closely tied to
>> 58: /// method types, which have many varieties, this generator needs *traces* to
> 
> Since this is the first mention of 'traces' in this file, I think it would be great if you could explain what they are, how they are generated (with the system properties), and what their format are (probably just a link to the right methods where the printing happens).

The link is right below to `generateHolderClasses` - it describes the process without mandating the contents, and links to MethodHandleStatics#traceLambdaForm and MethodHandleStatics#traceSpeciesType. I think that is sufficient.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/27010#discussion_r2323764132
PR Review Comment: https://git.openjdk.org/jdk/pull/27010#discussion_r2323763191