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

[Chen Liang]

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

After offline discussions, I believe it is necessary to also include the data models of instructions in the javadoc; they will be removed from the `java.lang.classfile` top-level documentation later.

I am pleased with the current state of the documentation, and have submitted a CSR.
Please review the renderings:

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

(Omitted the constant rendering changes; committed locally, will push with other review fixes later)

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

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