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

[Chen Liang]

On Thu, 21 Nov 2024 10:52:56 GMT, Adam Sotona <asotona at openjdk.org> wrote:

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

This links to the index tag on returnAddress.

> src/java.base/share/classes/java/lang/classfile/instruction/StoreInstruction.java line 76:
> 
>> 74:      * {@return the {@linkplain TypeKind##computational-type computational type}
>> 75:      * of the value to be stored}  The {@link TypeKind#REFERENCE reference}
>> 76:      * type store instructions also operate on the {@code returnAddress} type,
> 
> Where do we expose a TypeKind related to a return address?

We do not. This just notes astore can store jsr addresses (see jvms). This is intended to be similar to the array load/store boolean note.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/21625#discussion_r1852021242
PR Review Comment: https://git.openjdk.org/jdk/pull/21625#discussion_r1852020112