Summary

Massive addition and improvement of API specification and notes to java.lang.classfile.instruction package and related classes.

Problem

The java.lang.classfile.instruction has only barebone documentation. It needs more documentation to advertise its best usages, and note about error-prone details.

Solution

1. Improve the package info to give an overview about the usage of instructions in reading and writing, and the exception behaviors.
2. For each instruction, describe its conceptual/physical data model: this will be removed from the java.lang.classfile top level documentation later. Also refer to rewriting of some instructions.
3. Add notes on constantpool returning-methods to indicate how to get a symbolic representation, to discourage the use of raw constant pool entries.
4. Improve Opcode to link to JVMS for opcodes, and fix stylistic issues (missing trailing period).

Specification

See attached apidiff files. There is also a link to the latest javadoc and apidiff rendering of the changes. Note that for the javadoc and apidiff, the changes for java.lang.classfile is included, but you need to navigate to that package as link is to instruction package.