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

[Ioi Lam]

On Wed, 3 Sep 2025 00:06:59 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 with a new target base due to a merge or a rebase. The incremental webrev excludes the unrelated changes brought in by the merge/rebase. The pull request contains three additional commits since the last revision:
> 
>  - Merge branch 'master' of https://github.com/openjdk/jdk into doc/mh-holder-pregen
>  - Ioi reviews
>  - 8365428: Unclear comments on java.lang.invoke Holder classes

Looks good. Just a few small nits.

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

> 67: /// and behave identically to on-demand generated ones.  Pregenerated lambda
> 68: /// forms are resolved in [InvokerBytecodeGenerator#lookupPregenerated], which
> 69: /// look up from the following 4 possibly-generated classes:

which look up from the following 4 possibly-generated classes:

->

which looks up methods in the following 4 possibly-generated classes:

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

> 89: /// process of the JDK.
> 90: ///
> 91: /// > To list all the Species classes in a JDK image:

Should the `>` characters be deleted?

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

> 396:     /// subject to change.
> 397:     ///
> 398:     /// @param traces the *traces* to determine the lambda forms and species

the lambda forms and species
->
the lambda forms and species to be generated.

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

PR Review: https://git.openjdk.org/jdk/pull/27010#pullrequestreview-3178835555
PR Review Comment: https://git.openjdk.org/jdk/pull/27010#discussion_r2317677840
PR Review Comment: https://git.openjdk.org/jdk/pull/27010#discussion_r2317679614
PR Review Comment: https://git.openjdk.org/jdk/pull/27010#discussion_r2317676497