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

[Jorn Vernee]

On Thu, 4 Sep 2025 17:17:58 GMT, Chen Liang <liach at openjdk.org> wrote:

>> java.lang.invoke has a few Holder classes in DirectMethodHandle, DelegatingMethodHandle, Invokers, and LambdaForm.
>> 
>> Currently, the comments simply refer to "Placeholder for xxx generated ahead-of-time".
>> 
>> However, they carry executed bytecode and show up in flame graphs. The current comments are definitely not sufficient for their details and purposes.
>> 
>> To address these shortcomings, I improved the comments on the Holder classes and GenerateJLIClassesHelper to briefly describe the generation process. In addition, I improved the comments on BoundMethodHandle to provide a more efficient overview.
>
> Chen Liang has updated the pull request incrementally with one additional commit since the last revision:
> 
>   More ioi review

Thanks for improving the documentation! I've left a few suggestions inline.

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.

src/java.base/share/classes/java/lang/invoke/DelegatingMethodHandle.java line 205:

> 203:     ///
> 204:     /// The method names of this class are internal tokens recognized by
> 205:     /// [InvokerBytecodeGenerator#lookupPregenerated] and is subject to change.

Suggestion:

    /// [InvokerBytecodeGenerator#lookupPregenerated] and are subject to change.

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).

src/java.base/share/classes/java/lang/invoke/GenerateJLIClassesHelper.java line 100:

> 98: /// > ```
> 99: /// > javap -c -p -v java.lang.invoke.LambdaForm\$Holder
> 100: /// > ```

I think it is probably enough to put this comment on `javap` here, and it doesn't need to be on all the holder classes, since the comment there already links here.

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

Marked as reviewed by jvernee (Reviewer).

PR Review: https://git.openjdk.org/jdk/pull/27010#pullrequestreview-3186456503
PR Review Comment: https://git.openjdk.org/jdk/pull/27010#discussion_r2322985931
PR Review Comment: https://git.openjdk.org/jdk/pull/27010#discussion_r2322987321
PR Review Comment: https://git.openjdk.org/jdk/pull/27010#discussion_r2323028010
PR Review Comment: https://git.openjdk.org/jdk/pull/27010#discussion_r2323013426