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

[Adam Sotona]

On Mon, 18 Nov 2024 02:58:31 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 with a new target base due to a merge or a rebase. The pull request now contains six commits:
> 
>  - Further facelift
>  - Merge branch 'master' of https://github.com/openjdk/jdk into docs/cf-instruction
>  - Merge branch 'master' of https://github.com/openjdk/jdk into docs/cf-instruction
>  - Typos, long lines
>  - Labels
>  - Wip instr

My personal feeling is that sentences like "Conceptually, Xy is a record..." and "Physically,  Xy is a record..." are more confusing than explaining. My understanding of "Conceptually" is that the particular sealed interface xyInstruction represents the model concept. My understanding of "Physically" is that the particular chapter 6. paragraph of the JVMS describes the mechanics. And I don't see there any records (in particular Java meaning) .

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

PR Comment: https://git.openjdk.org/jdk/pull/21625#issuecomment-2485248411