RFR: 8342469: Improve API documentation for java.lang.classfile.instruction [v4]

[Adam Sotona]

On Wed, 20 Nov 2024 23:03:43 GMT, Chen Liang <liach at openjdk.org> wrote:

>> Improve the documentation for classfile instructions. Includes links to all opcodes, usage notes for instructions, and other various fixes.
>> 
>> API Diff: https://cr.openjdk.org/~liach/apidiff/cf-instr/java.base/module-summary.html
>> Javadoc: https://cr.openjdk.org/~liach/javadoc/cf-instr/java.base/java/lang/classfile/instruction/package-summary.html
>> 
>> Please review the associated CSR as well.
>
> Chen Liang has updated the pull request incrementally with four additional commits since the last revision:
> 
>  - typo
>  - More cleanup
>  - Remove a few confusions around bad modeling, some missing exceptions, also the labelless info models
>  - Non-int constant values

src/java.base/share/classes/java/lang/classfile/instruction/ConvertInstruction.java line 44:

> 42:  * Delivered as a {@link CodeElement} when traversing the elements of a {@link CodeModel}.
> 43:  * <p>
> 44:  * Conceptually, a primitive conversion instruction is a record:

Here remains "Conceptually, ... is a record"

src/java.base/share/classes/java/lang/classfile/instruction/DiscontinuedInstruction.java line 69:

> 67:      * instruction model is written by a {@link CodeBuilder}.
> 68:      * <p>
> 69:      * Jump subroutine instructions push a {@link TypeKind##returnAddress

I don't think we have a TypeKind##returnAddress.

src/java.base/share/classes/java/lang/classfile/instruction/DiscontinuedInstruction.java line 130:

> 128:      * <p>
> 129:      * {@link StoreInstruction astore} series of instructions store a {@link
> 130:      * TypeKind##returnAddress returnAddress} value to a local variable slot,

And the same here.

src/java.base/share/classes/java/lang/classfile/instruction/InvokeInstruction.java line 51:

> 49:  * Delivered as a {@link CodeElement} when traversing the elements of a {@link CodeModel}.
> 50:  * <p>
> 51:  * Conceptually, a method invocation instruction is a record:

And here

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

PR Review Comment: https://git.openjdk.org/jdk/pull/21625#discussion_r1851832104
PR Review Comment: https://git.openjdk.org/jdk/pull/21625#discussion_r1851829395
PR Review Comment: https://git.openjdk.org/jdk/pull/21625#discussion_r1851829969
PR Review Comment: https://git.openjdk.org/jdk/pull/21625#discussion_r1851835367