8342469: Improve API documentation for java.lang.classfile.instruction

Reviewed-by: asotona, darcy

Author: liach

src/java.base/share/classes/java/lang/classfile/ClassFile.java

@@ -32,6 +32,8 @@
 import java.lang.classfile.constantpool.ClassEntry;
 import java.lang.classfile.constantpool.ConstantPoolBuilder;
 import java.lang.classfile.constantpool.Utf8Entry;
+import java.lang.classfile.instruction.BranchInstruction;
+import java.lang.classfile.instruction.DiscontinuedInstruction;
 import java.lang.classfile.instruction.ExceptionCatch;
 import java.lang.constant.ClassDesc;
 import java.lang.reflect.AccessFlag;
@@ -230,17 +232,35 @@ enum LineNumbersOption implements Option {
     /**
      * Option describing whether to automatically rewrite short jumps to
      * long when necessary.
-     * Default is {@code FIX_SHORT_JUMPS} to automatically rewrite jump
+     * Default is {@link #FIX_SHORT_JUMPS} to automatically rewrite jump
      * instructions.
+     * <p>
+     * Due to physical restrictions, some types of instructions cannot encode
+     * certain jump targets with bci offsets less than -32768 or greater than
+     * 32767, as they use a {@code s2} to encode such an offset.  (The maximum
+     * length of the {@code code} array is 65535.)  These types of instructions
+     * are called "short jumps".
      *
+     * @see BranchInstruction
+     * @see DiscontinuedInstruction.JsrInstruction
      * @since 24
      */
     enum ShortJumpsOption implements Option {
 
-        /** Automatically convert short jumps to long when necessary */
+        /**
+         * Automatically convert short jumps to long when necessary.
+         * <p>
+         * For an invalid instruction model, a {@link CodeBuilder} may generate
+         * another or a few other instructions to accomplish the same effect.
+         */
         FIX_SHORT_JUMPS,
 
-        /** Fail if short jump overflows */
+        /**
+         * Fail with an {@link IllegalArgumentException} if short jump overflows.
+         * <p>
+         * This is useful to ensure the physical accuracy of a generated {@code
+         * class} file.
+         */
         FAIL_ON_SHORT_JUMPS
     }
 

src/java.base/share/classes/java/lang/classfile/CodeBuilder.java

@@ -51,7 +51,7 @@
  * #with(ClassFileElement)} or concretely by calling the various {@code withXxx}
  * methods.
  *
- * <h2>Instruction Factories</h2>
+ * <h2 id="instruction-factories">Instruction Factories</h2>
  * {@code CodeBuilder} provides convenience methods to create instructions (See
  * JVMS {@jvms 6.5} Instructions) by their mnemonic, taking necessary operands.
  * <ul>

src/java.base/share/classes/java/lang/classfile/Instruction.java

@@ -25,13 +25,20 @@
 
 package java.lang.classfile;
 
+import java.lang.classfile.attribute.CodeAttribute;
 import java.lang.classfile.instruction.*;
 
 import jdk.internal.classfile.impl.AbstractInstruction;
 
 /**
- * Models an executable instruction in a method body.
+ * Models an executable instruction in the {@code code} array of the {@link
+ * CodeAttribute Code} attribute of a method.
+ * <p>
+ * The {@link #opcode() opcode} identifies the operation of an instruction.
+ * Each {@linkplain Opcode#kind() kind} of opcode has its own modeling interface
+ * for instructions.
  *
+ * @sealedGraph
  * @since 24
  */
 public sealed interface Instruction extends CodeElement
@@ -46,12 +53,14 @@ public sealed interface Instruction extends CodeElement
                 ThrowInstruction, TypeCheckInstruction, AbstractInstruction {
 
     /**
-     * {@return the opcode of this instruction}
+     * {@return the operation of this instruction}
      */
     Opcode opcode();
 
     /**
      * {@return the size in bytes of this instruction}
+     * This value is equal to {@link Opcode#sizeIfFixed()
+     * opcode().sizeIfFixed()} if it is not {@code -1}.
      */
     int sizeInBytes();
 }

src/java.base/share/classes/java/lang/classfile/Label.java

@@ -24,21 +24,60 @@
  */
 package java.lang.classfile;
 
+import java.lang.classfile.attribute.CodeAttribute;
+import java.lang.classfile.instruction.LabelTarget;
+import java.util.ListIterator;
+
 import jdk.internal.classfile.impl.LabelImpl;
 
 /**
  * A marker for a position within the instructions of a method body.  The
- * association between a label's identity and the position it represents is
- * managed by the entity managing the method body (a {@link CodeModel} or {@link
- * CodeBuilder}), not the label itself; this allows the same label to have a
- * meaning both in an existing method (as managed by a {@linkplain CodeModel})
- * and in the transformation of that method (as managed by a {@linkplain
- * CodeBuilder}), while corresponding to different positions in each. When
- * traversing the elements of a {@linkplain CodeModel}, {@linkplain Label}
- * markers will be delivered at the position to which they correspond.  A label
- * can be bound to the current position within a {@linkplain CodeBuilder} via
- * {@link CodeBuilder#labelBinding(Label)} or {@link CodeBuilder#with(ClassFileElement)}.
+ * position is a cursor position in the list of instructions, similar to that
+ * of a {@link ListIterator}.
+ *
+ * <h2 id="reading">Reading Labels</h2>
+ * Labels read from {@code class} files represent positions in the {@code code}
+ * array of a {@link CodeAttribute Code} attribute.  It is associated with a
+ * <dfn>{@index bci}</dfn> (bytecode index), also known as <dfn>{@index pc}</dfn>
+ * (program counter), the index into the {@code code} array; the actual cursor
+ * position is immediately before the given index, so a label at the beginning
+ * of the instructions has bci {@code 0}, and a label at the end of the
+ * instructions has bci {@link CodeAttribute#codeLength codeLength() + 1}.  The
+ * bci can be inspected through {@link CodeAttribute#labelToBci
+ * CodeAttribute::labelToBci}.
+ * <p>
+ * In generic {@link CodeModel}s, a label may not have a bci value; the position
+ * of a label can be found by searching for the corresponding {@link LabelTarget}
+ * within that model.
+ *
+ * <h2 id="writing">Writing Labels</h2>
+ * Many models in {@link java.lang.classfile} refer to labels.  To write a
+ * label, a label must be obtained, it must be bound to a {@link CodeBuilder}.
+ * <p>
+ * To obtain a label:
+ * <ul>
+ * <li>Use a label read from other models.
+ * <li>Use pre-defined labels from a {@link CodeBuilder}, such as {@link
+ *     CodeBuilder#startLabel() CodeBuilder::startLabel}, {@link CodeBuilder#endLabel
+ *     CodeBuilder::endLabel}, or {@link CodeBuilder.BlockCodeBuilder#breakLabel
+ *     BlockCodeBuilder::breakLabel}.  They are already bound.
+ * <li>Create labels with {@link CodeBuilder#newLabel CodeBuilder::newLabel} or
+ *     {@link CodeBuilder#newBoundLabel CodeBuilder::newBoundLabel}.
+ * </ul>
+ * <p>
+ * A label must be bound exactly once in the {@code CodeBuilder} where it is
+ * used; otherwise, writing fails.  To bind an unbound label:
+ * <ul>
+ * <li>Send a read {@link LabelTarget} to a {@code CodeBuilder}.
+ * <li>Use {@link CodeBuilder#labelBinding CodeBuilder::labelBinding}.
+ * </ul>
+ * Note that a label read from another model is not automatically bound in a
+ * {@code CodeBuilder}; they are separate entities and the label is bound to
+ * different positions in them.
  *
+ * @see CodeAttribute#labelToBci CodeAttribute::labelToBci
+ * @see CodeBuilder#newLabel CodeBuilder::newLabel
+ * @see CodeBuilder#labelBinding CodeBuilder::labelBinding
  * @since 24
  */
 public sealed interface Label