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

src/java.base/share/classes/java/lang/classfile/instruction/CharacterRange.java line 62:

> 60:  * <p>
> 61:  * Physically, a character range has the same structure; it is modeled by a
> 62:  * {@link CharacterRangeInfo}.

I'm not sure how to explain "Physically" and "it is modeled by".
If "Physically" means specific byte serialization, then it is an entry in a CRT attribute with BCIs instead of labels.

"it is modeled by a CharacterRangeInfo" seems to me very confusing as this class (CharacterRange) is the primary model class. 

Maybe we should explain the duplicity of some classfile structures accessible as attributes internal raw structures (CharacterRangeInfo) versus preferred primary models as labeled pseudo instructions (CharacterRange).

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

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