From 994ac95e67e049b4391cb6bfb158b33b8723d6a7 Mon Sep 17 00:00:00 2001
From: "David M. Lloyd" <david.lloyd@redhat.com>
Date: Thu, 12 Dec 2024 09:26:23 -0600
Subject: [PATCH] Update JDK

---
 jdk                                           |    2 +-
 .../github/dmlloyd/classfile/ClassFile.java   |   26 +-
 .../github/dmlloyd/classfile/CodeBuilder.java |    2 +-
 .../dmlloyd/classfile/CompoundElement.java    |   12 +
 .../github/dmlloyd/classfile/Instruction.java |   13 +-
 .../io/github/dmlloyd/classfile/Label.java    |   59 +-
 .../io/github/dmlloyd/classfile/Opcode.java   | 1696 ++++++++++++++---
 .../io/github/dmlloyd/classfile/TypeKind.java |   35 +-
 .../classfile/extras/constant/ModuleDesc.java |    2 +-
 .../classfile/impl/AccessFlagsImpl.java       |    2 +-
 .../classfile/impl/BoundLocalVariable.java    |    2 +-
 .../classfile/impl/CatchBuilderImpl.java      |    2 +-
 .../dmlloyd/classfile/impl/EntryMap.java      |    2 +-
 .../classfile/impl/InterfacesImpl.java        |    2 +-
 .../dmlloyd/classfile/impl/LabelImpl.java     |    2 +-
 .../classfile/impl/SuperclassImpl.java        |    2 +-
 .../impl/verifier/VerificationBytecodes.java  |    2 +-
 .../impl/verifier/VerificationTable.java      |    2 +-
 .../impl/verifier/VerificationType.java       |    2 +-
 .../instruction/ArrayLoadInstruction.java     |   22 +-
 .../instruction/ArrayStoreInstruction.java    |   22 +-
 .../instruction/BranchInstruction.java        |   33 +-
 .../classfile/instruction/CharacterRange.java |   29 +-
 .../instruction/ConstantInstruction.java      |  102 +-
 .../instruction/ConvertInstruction.java       |   32 +-
 .../instruction/DiscontinuedInstruction.java  |   98 +-
 .../classfile/instruction/ExceptionCatch.java |   36 +-
 .../instruction/FieldInstruction.java         |   26 +-
 .../instruction/IncrementInstruction.java     |   26 +-
 .../instruction/InvokeDynamicInstruction.java |   22 +-
 .../instruction/InvokeInstruction.java        |   52 +-
 .../classfile/instruction/LabelTarget.java    |   26 +-
 .../classfile/instruction/LineNumber.java     |   31 +-
 .../instruction/LoadInstruction.java          |   41 +-
 .../classfile/instruction/LocalVariable.java  |   46 +-
 .../instruction/LocalVariableType.java        |   52 +-
 .../instruction/LookupSwitchInstruction.java  |   23 +-
 .../instruction/MonitorInstruction.java       |   15 +-
 .../instruction/NewMultiArrayInstruction.java |   19 +-
 .../instruction/NewObjectInstruction.java     |   14 +-
 .../NewPrimitiveArrayInstruction.java         |   23 +-
 .../NewReferenceArrayInstruction.java         |   13 +-
 .../classfile/instruction/NopInstruction.java |    8 +-
 .../instruction/OperatorInstruction.java      |   12 +-
 .../instruction/ReturnInstruction.java        |   18 +-
 .../instruction/StackInstruction.java         |    9 +-
 .../instruction/StoreInstruction.java         |   44 +-
 .../classfile/instruction/SwitchCase.java     |   17 +-
 .../instruction/TableSwitchInstruction.java   |   31 +-
 .../instruction/ThrowInstruction.java         |    8 +-
 .../instruction/TypeCheckInstruction.java     |   27 +-
 .../classfile/instruction/package-info.java   |   38 +-
 52 files changed, 2430 insertions(+), 452 deletions(-)

diff --git a/jdk b/jdk
index bedb68a..22845a7 160000
--- a/jdk
+++ b/jdk
@@ -1 +1 @@
-Subproject commit bedb68aba126c6400ce9f2182105b5294ff42021
+Subproject commit 22845a77a2175202876d0029f75fa32271e07b91
diff --git a/src/main/java/io/github/dmlloyd/classfile/ClassFile.java b/src/main/java/io/github/dmlloyd/classfile/ClassFile.java
index e85f698..8e35b4f 100644
--- a/src/main/java/io/github/dmlloyd/classfile/ClassFile.java
+++ b/src/main/java/io/github/dmlloyd/classfile/ClassFile.java
@@ -32,6 +32,8 @@
 import io.github.dmlloyd.classfile.constantpool.ClassEntry;
 import io.github.dmlloyd.classfile.constantpool.ConstantPoolBuilder;
 import io.github.dmlloyd.classfile.constantpool.Utf8Entry;
+import io.github.dmlloyd.classfile.instruction.BranchInstruction;
+import io.github.dmlloyd.classfile.instruction.DiscontinuedInstruction;
 import io.github.dmlloyd.classfile.instruction.ExceptionCatch;
 import java.lang.constant.ClassDesc;
 import io.github.dmlloyd.classfile.extras.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
     }
 
diff --git a/src/main/java/io/github/dmlloyd/classfile/CodeBuilder.java b/src/main/java/io/github/dmlloyd/classfile/CodeBuilder.java
index 193cb9d..697ff22 100644
--- a/src/main/java/io/github/dmlloyd/classfile/CodeBuilder.java
+++ b/src/main/java/io/github/dmlloyd/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>
diff --git a/src/main/java/io/github/dmlloyd/classfile/CompoundElement.java b/src/main/java/io/github/dmlloyd/classfile/CompoundElement.java
index 5278675..ad43925 100644
--- a/src/main/java/io/github/dmlloyd/classfile/CompoundElement.java
+++ b/src/main/java/io/github/dmlloyd/classfile/CompoundElement.java
@@ -34,6 +34,8 @@
 import java.util.stream.Stream;
 import java.util.stream.StreamSupport;
 
+import io.github.dmlloyd.classfile.components.ClassPrinter;
+
 /**
  * A {@link ClassFileElement} that has complex structure defined in terms of
  * other classfile elements, such as a method, field, method body, or entire
@@ -92,4 +94,14 @@ public void accept(E e) {
         return Collections.unmodifiableList(list);
     }
 
+    /**
+     * {@return a text representation of the compound element and its contents for debugging purposes}
+     *
+     * The format, structure and exact contents of the returned string are not specified and may change at any time in the future.
+     */
+    default String toDebugString() {
+        StringBuilder text = new StringBuilder();
+        ClassPrinter.toYaml(this, ClassPrinter.Verbosity.TRACE_ALL, text::append);
+        return text.toString();
+    }
 }
diff --git a/src/main/java/io/github/dmlloyd/classfile/Instruction.java b/src/main/java/io/github/dmlloyd/classfile/Instruction.java
index 5ac6eae..dcd9e2a 100644
--- a/src/main/java/io/github/dmlloyd/classfile/Instruction.java
+++ b/src/main/java/io/github/dmlloyd/classfile/Instruction.java
@@ -25,13 +25,20 @@
 
 package io.github.dmlloyd.classfile;
 
+import io.github.dmlloyd.classfile.attribute.CodeAttribute;
 import io.github.dmlloyd.classfile.instruction.*;
 
 import io.github.dmlloyd.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();
 }
diff --git a/src/main/java/io/github/dmlloyd/classfile/Label.java b/src/main/java/io/github/dmlloyd/classfile/Label.java
index 92cd971..9e3c5e9 100644
--- a/src/main/java/io/github/dmlloyd/classfile/Label.java
+++ b/src/main/java/io/github/dmlloyd/classfile/Label.java
@@ -24,21 +24,60 @@
  */
 package io.github.dmlloyd.classfile;
 
+import io.github.dmlloyd.classfile.attribute.CodeAttribute;
+import io.github.dmlloyd.classfile.instruction.LabelTarget;
+import java.util.ListIterator;
+
 import io.github.dmlloyd.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 io.github.dmlloyd.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
diff --git a/src/main/java/io/github/dmlloyd/classfile/Opcode.java b/src/main/java/io/github/dmlloyd/classfile/Opcode.java
index 4490d62..d8f6f37 100644
--- a/src/main/java/io/github/dmlloyd/classfile/Opcode.java
+++ b/src/main/java/io/github/dmlloyd/classfile/Opcode.java
@@ -24,684 +24,1849 @@
  */
 package io.github.dmlloyd.classfile;
 
+import io.github.dmlloyd.classfile.instruction.*;
+
 import io.github.dmlloyd.classfile.impl.RawBytecodeHelper;
 
 /**
  * Describes the opcodes of the JVM instruction set, as described in JVMS {@jvms 6.5}.
- * As well as a number of pseudo-instructions that may be encountered when
- * traversing the instructions of a method.
+ * This includes a few pseudo-opcodes modified by {@link #isWide() wide}.
+ * <p>
+ * An opcode describes the operation of an instruction.
+ *
+ * @apiNote
+ * The enum constants are named after the opcodes' mnemonics in uppercase.
+ * Wide pseudo-opcodes are named with the original opcodes' mnemonic plus
+ * a {@code _W} suffix. However, {@link #LDC_W ldc_w}, {@link #LDC2_W ldc2_w},
+ * {@link #GOTO_W goto_w}, and {@link #JSR_W jsr_w} are legitimate opcodes
+ * instead of wide pseudo-opcodes.
  *
  * @see Instruction
- * @see PseudoInstruction
  *
  * @since 24
  */
 public enum Opcode {
 
-    /** Do nothing */
+    /**
+     * Do nothing.
+     *
+     * @jvms 6.5.nop <em>nop</em>
+     * @see Kind#NOP
+     */
     NOP(RawBytecodeHelper.NOP, 1, Kind.NOP),
 
-    /** Push null */
+    /**
+     * Push {@code null}.
+     *
+     * @jvms 6.5.aconst_null <em>aconst_null</em>
+     * @see ConstantInstruction.IntrinsicConstantInstruction
+     * @see Kind#CONSTANT
+     */
     ACONST_NULL(RawBytecodeHelper.ACONST_NULL, 1, Kind.CONSTANT),
 
-    /** Push int constant -1 */
+    /**
+     * Push {@link TypeKind#INT int} constant {@code -1}.
+     *
+     * @jvms 6.5.iconst_i <em>iconst_&lt;i&gt;</em>
+     * @see ConstantInstruction.IntrinsicConstantInstruction
+     * @see Kind#CONSTANT
+     */
     ICONST_M1(RawBytecodeHelper.ICONST_M1, 1, Kind.CONSTANT),
 
-    /** Push int constant 0 */
+    /**
+     * Push {@link TypeKind#INT int} constant {@code 0}.
+     *
+     * @jvms 6.5.iconst_i <em>iconst_&lt;i&gt;</em>
+     * @see ConstantInstruction.IntrinsicConstantInstruction
+     * @see Kind#CONSTANT
+     */
     ICONST_0(RawBytecodeHelper.ICONST_0, 1, Kind.CONSTANT),
 
-    /** Push int constant 1 */
+    /**
+     * Push {@link TypeKind#INT int} constant {@code 1}.
+     *
+     * @jvms 6.5.iconst_i <em>iconst_&lt;i&gt;</em>
+     * @see ConstantInstruction.IntrinsicConstantInstruction
+     * @see Kind#CONSTANT
+     */
     ICONST_1(RawBytecodeHelper.ICONST_1, 1, Kind.CONSTANT),
 
-    /** Push int constant 2 */
+    /**
+     * Push {@link TypeKind#INT int} constant {@code 2}.
+     *
+     * @jvms 6.5.iconst_i <em>iconst_&lt;i&gt;</em>
+     * @see ConstantInstruction.IntrinsicConstantInstruction
+     * @see Kind#CONSTANT
+     */
     ICONST_2(RawBytecodeHelper.ICONST_2, 1, Kind.CONSTANT),
 
-    /** Push int constant 3 */
+    /**
+     * Push {@link TypeKind#INT int} constant {@code 3}.
+     *
+     * @jvms 6.5.iconst_i <em>iconst_&lt;i&gt;</em>
+     * @see ConstantInstruction.IntrinsicConstantInstruction
+     * @see Kind#CONSTANT
+     */
     ICONST_3(RawBytecodeHelper.ICONST_3, 1, Kind.CONSTANT),
 
-    /** Push int constant 4 */
+    /**
+     * Push {@link TypeKind#INT int} constant {@code 4}.
+     *
+     * @jvms 6.5.iconst_i <em>iconst_&lt;i&gt;</em>
+     * @see ConstantInstruction.IntrinsicConstantInstruction
+     * @see Kind#CONSTANT
+     */
     ICONST_4(RawBytecodeHelper.ICONST_4, 1, Kind.CONSTANT),
 
-    /** Push int constant 5 */
+    /**
+     * Push {@link TypeKind#INT int} constant {@code 5}.
+     *
+     * @jvms 6.5.iconst_i <em>iconst_&lt;i&gt;</em>
+     * @see ConstantInstruction.IntrinsicConstantInstruction
+     * @see Kind#CONSTANT
+     */
     ICONST_5(RawBytecodeHelper.ICONST_5, 1, Kind.CONSTANT),
 
-    /** Push long constant 0 */
+    /**
+     * Push {@link TypeKind#LONG long} constant {@code 0L}.
+     *
+     * @jvms 6.5.lconst_l <em>lconst_&lt;l&gt;</em>
+     * @see ConstantInstruction.IntrinsicConstantInstruction
+     * @see Kind#CONSTANT
+     */
     LCONST_0(RawBytecodeHelper.LCONST_0, 1, Kind.CONSTANT),
 
-    /** Push long constant  1 */
+    /**
+     * Push {@link TypeKind#LONG long} constant {@code 1L}.
+     *
+     * @jvms 6.5.lconst_l <em>lconst_&lt;l&gt;</em>
+     * @see ConstantInstruction.IntrinsicConstantInstruction
+     * @see Kind#CONSTANT
+     */
     LCONST_1(RawBytecodeHelper.LCONST_1, 1, Kind.CONSTANT),
 
-    /** Push float constant 0 */
+    /**
+     * Push {@link TypeKind#FLOAT float} constant {@code 0.0F}.
+     *
+     * @jvms 6.5.fconst_f <em>fconst_&lt;f&gt;</em>
+     * @see ConstantInstruction.IntrinsicConstantInstruction
+     * @see Kind#CONSTANT
+     */
     FCONST_0(RawBytecodeHelper.FCONST_0, 1, Kind.CONSTANT),
 
-    /** Push float constant 1 */
+    /**
+     * Push {@link TypeKind#FLOAT float} constant {@code 1.0F}.
+     *
+     * @jvms 6.5.fconst_f <em>fconst_&lt;f&gt;</em>
+     * @see ConstantInstruction.IntrinsicConstantInstruction
+     * @see Kind#CONSTANT
+     */
     FCONST_1(RawBytecodeHelper.FCONST_1, 1, Kind.CONSTANT),
 
-    /** Push float constant 2 */
+    /**
+     * Push {@link TypeKind#FLOAT float} constant {@code 2.0F}.
+     *
+     * @jvms 6.5.fconst_f <em>fconst_&lt;f&gt;</em>
+     * @see ConstantInstruction.IntrinsicConstantInstruction
+     * @see Kind#CONSTANT
+     */
     FCONST_2(RawBytecodeHelper.FCONST_2, 1, Kind.CONSTANT),
 
-    /** Push double constant 0 */
+    /**
+     * Push {@link TypeKind#DOUBLE double} constant {@code 0.0D}.
+     *
+     * @jvms 6.5.dconst_d <em>dconst_&lt;d&gt;</em>
+     * @see ConstantInstruction.IntrinsicConstantInstruction
+     * @see Kind#CONSTANT
+     */
     DCONST_0(RawBytecodeHelper.DCONST_0, 1, Kind.CONSTANT),
 
-    /** Push double constant 1 */
+    /**
+     * Push {@link TypeKind#DOUBLE double} constant {@code 1.0D}.
+     *
+     * @jvms 6.5.dconst_d <em>dconst_&lt;d&gt;</em>
+     * @see ConstantInstruction.IntrinsicConstantInstruction
+     * @see Kind#CONSTANT
+     */
     DCONST_1(RawBytecodeHelper.DCONST_1, 1, Kind.CONSTANT),
 
-    /** Push byte */
+    /**
+     * Push {@link TypeKind#INT int} value from sign-extension of immediate
+     * {@link TypeKind#BYTE byte} value.
+     *
+     * @jvms 6.5.bipush <em>bipush</em>
+     * @see ConstantInstruction.ArgumentConstantInstruction
+     * @see Kind#CONSTANT
+     */
     BIPUSH(RawBytecodeHelper.BIPUSH, 2, Kind.CONSTANT),
 
-    /** Push short */
+    /**
+     * Push {@link TypeKind#INT int} value from sign-extension of immediate
+     * {@link TypeKind#SHORT short} value.
+     *
+     * @jvms 6.5.sipush <em>sipush</em>
+     * @see ConstantInstruction.ArgumentConstantInstruction
+     * @see Kind#CONSTANT
+     */
     SIPUSH(RawBytecodeHelper.SIPUSH, 3, Kind.CONSTANT),
 
-    /** Push item from run-time constant pool */
+    /**
+     * Push item from run-time constant pool.
+     *
+     * @jvms 6.5.ldc <em>ldc</em>
+     * @see ConstantInstruction.LoadConstantInstruction
+     * @see Kind#CONSTANT
+     */
     LDC(RawBytecodeHelper.LDC, 2, Kind.CONSTANT),
 
-    /** Push item from run-time constant pool (wide index) */
+    /**
+     * Push item from run-time constant pool (wide index).
+     *
+     * @jvms 6.5.ldc_w <em>ldc_w</em>
+     * @see ConstantInstruction.LoadConstantInstruction
+     * @see Kind#CONSTANT
+     */
     LDC_W(RawBytecodeHelper.LDC_W, 3, Kind.CONSTANT),
 
-    /** Push long or double from run-time constant pool (wide index) */
+    /**
+     * Push {@link TypeKind#LONG long} or {@link TypeKind#DOUBLE double}
+     * from run-time constant pool (wide index).
+     *
+     * @jvms 6.5.ldc2_w <em>ldc2_w</em>
+     * @see ConstantInstruction.LoadConstantInstruction
+     * @see Kind#CONSTANT
+     */
     LDC2_W(RawBytecodeHelper.LDC2_W, 3, Kind.CONSTANT),
 
-    /** Load int from local variable */
+    /**
+     * Load {@link TypeKind#INT int} from local variable.
+     *
+     * @jvms 6.5.iload <em>iload</em>
+     * @see Kind#LOAD
+     */
     ILOAD(RawBytecodeHelper.ILOAD, 2, Kind.LOAD),
 
-    /** Load long from local variable */
+    /**
+     * Load {@link TypeKind#LONG long} from local variable.
+     *
+     * @jvms 6.5.lload <em>lload</em>
+     * @see Kind#LOAD
+     */
     LLOAD(RawBytecodeHelper.LLOAD, 2, Kind.LOAD),
 
-    /** Load float from local variable */
+    /**
+     * Load {@link TypeKind#FLOAT float} from local variable.
+     *
+     * @jvms 6.5.fload <em>fload</em>
+     * @see Kind#LOAD
+     */
     FLOAD(RawBytecodeHelper.FLOAD, 2, Kind.LOAD),
 
-    /** Load double from local variable */
+    /**
+     * Load {@link TypeKind#DOUBLE double} from local variable.
+     *
+     * @jvms 6.5.dload <em>dload</em>
+     * @see Kind#LOAD
+     */
     DLOAD(RawBytecodeHelper.DLOAD, 2, Kind.LOAD),
 
-    /** Load reference from local variable */
+    /**
+     * Load {@link TypeKind#REFERENCE reference} from local variable.
+     *
+     * @jvms 6.5.aload <em>aload</em>
+     * @see Kind#LOAD
+     */
     ALOAD(RawBytecodeHelper.ALOAD, 2, Kind.LOAD),
 
-    /** Load int from local variable 0 */
+    /**
+     * Load {@link TypeKind#INT int} from local variable slot {@code 0}.
+     *
+     * @jvms 6.5.iload_n <em>iload_&lt;n&gt;</em>
+     * @see Kind#LOAD
+     */
     ILOAD_0(RawBytecodeHelper.ILOAD_0, 1, Kind.LOAD),
 
-    /** Load int from local variable 1 */
+    /**
+     * Load {@link TypeKind#INT int} from local variable slot {@code 1}.
+     *
+     * @jvms 6.5.iload_n <em>iload_&lt;n&gt;</em>
+     * @see Kind#LOAD
+     */
     ILOAD_1(RawBytecodeHelper.ILOAD_1, 1, Kind.LOAD),
 
-    /** Load int from local variable 2 */
+    /**
+     * Load {@link TypeKind#INT int} from local variable slot {@code 2}.
+     *
+     * @jvms 6.5.iload_n <em>iload_&lt;n&gt;</em>
+     * @see Kind#LOAD
+     */
     ILOAD_2(RawBytecodeHelper.ILOAD_2, 1, Kind.LOAD),
 
-    /** Load int from local variable3  */
+    /**
+     * Load {@link TypeKind#INT int} from local variable slot {@code 3}.
+     *
+     * @jvms 6.5.iload_n <em>iload_&lt;n&gt;</em>
+     * @see Kind#LOAD
+     */
     ILOAD_3(RawBytecodeHelper.ILOAD_3, 1, Kind.LOAD),
 
-    /** Load long from local variable 0 */
+    /**
+     * Load {@link TypeKind#LONG long} from local variable slot {@code 0}.
+     *
+     * @jvms 6.5.lload_n <em>lload_&lt;n&gt;</em>
+     * @see Kind#LOAD
+     */
     LLOAD_0(RawBytecodeHelper.LLOAD_0, 1, Kind.LOAD),
 
-    /** Load long from local variable 1 */
+    /**
+     * Load {@link TypeKind#LONG long} from local variable slot {@code 1}.
+     *
+     * @jvms 6.5.lload_n <em>lload_&lt;n&gt;</em>
+     * @see Kind#LOAD
+     */
     LLOAD_1(RawBytecodeHelper.LLOAD_1, 1, Kind.LOAD),
 
-    /** Load long from local variable 2 */
+    /**
+     * Load {@link TypeKind#LONG long} from local variable slot {@code 2}.
+     *
+     * @jvms 6.5.lload_n <em>lload_&lt;n&gt;</em>
+     * @see Kind#LOAD
+     */
     LLOAD_2(RawBytecodeHelper.LLOAD_2, 1, Kind.LOAD),
 
-    /** Load long from local variable 3 */
+    /**
+     * Load {@link TypeKind#LONG long} from local variable slot {@code 3}.
+     *
+     * @jvms 6.5.lload_n <em>lload_&lt;n&gt;</em>
+     * @see Kind#LOAD
+     */
     LLOAD_3(RawBytecodeHelper.LLOAD_3, 1, Kind.LOAD),
 
-    /** Load float from local variable 0 */
+    /**
+     * Load {@link TypeKind#FLOAT float} from local variable slot {@code 0}.
+     *
+     * @jvms 6.5.fload_n <em>fload_&lt;n&gt;</em>
+     * @see Kind#LOAD
+     */
     FLOAD_0(RawBytecodeHelper.FLOAD_0, 1, Kind.LOAD),
 
-    /** Load float from local variable 1 */
+    /**
+     * Load {@link TypeKind#FLOAT float} from local variable slot {@code 1}.
+     *
+     * @jvms 6.5.fload_n <em>fload_&lt;n&gt;</em>
+     * @see Kind#LOAD
+     */
     FLOAD_1(RawBytecodeHelper.FLOAD_1, 1, Kind.LOAD),
 
-    /** Load float from local variable 2 */
+    /**
+     * Load {@link TypeKind#FLOAT float} from local variable slot {@code 2}.
+     *
+     * @jvms 6.5.fload_n <em>fload_&lt;n&gt;</em>
+     * @see Kind#LOAD
+     */
     FLOAD_2(RawBytecodeHelper.FLOAD_2, 1, Kind.LOAD),
 
-    /** Load float from local variable 3 */
+    /**
+     * Load {@link TypeKind#FLOAT float} from local variable slot {@code 3}.
+     *
+     * @jvms 6.5.fload_n <em>fload_&lt;n&gt;</em>
+     * @see Kind#LOAD
+     */
     FLOAD_3(RawBytecodeHelper.FLOAD_3, 1, Kind.LOAD),
 
-    /** Load double from local variable 0 */
+    /**
+     * Load {@link TypeKind#DOUBLE double} from local variable slot {@code 0}.
+     *
+     * @jvms 6.5.dload_n <em>dload_&lt;n&gt;</em>
+     * @see Kind#LOAD
+     */
     DLOAD_0(RawBytecodeHelper.DLOAD_0, 1, Kind.LOAD),
 
-    /** Load double from local variable 1 */
+    /**
+     * Load {@link TypeKind#DOUBLE double} from local variable slot {@code 1}.
+     *
+     * @jvms 6.5.dload_n <em>dload_&lt;n&gt;</em>
+     * @see Kind#LOAD
+     */
     DLOAD_1(RawBytecodeHelper.DLOAD_1, 1, Kind.LOAD),
 
-    /** Load double from local variable 2 */
+    /**
+     * Load {@link TypeKind#DOUBLE double} from local variable slot {@code 2}.
+     *
+     * @jvms 6.5.dload_n <em>dload_&lt;n&gt;</em>
+     * @see Kind#LOAD
+     */
     DLOAD_2(RawBytecodeHelper.DLOAD_2, 1, Kind.LOAD),
 
-    /** Load double from local variable 3 */
+    /**
+     * Load {@link TypeKind#DOUBLE double} from local variable slot {@code 3}.
+     *
+     * @jvms 6.5.dload_n <em>dload_&lt;n&gt;</em>
+     * @see Kind#LOAD
+     */
     DLOAD_3(RawBytecodeHelper.DLOAD_3, 1, Kind.LOAD),
 
-    /**  Load reference from local variable 0 */
+    /**
+     * Load {@link TypeKind#REFERENCE reference} from local variable slot {@code 0}.
+     *
+     * @jvms 6.5.aload_n <em>aload_&lt;n&gt;</em>
+     * @see Kind#LOAD
+     */
     ALOAD_0(RawBytecodeHelper.ALOAD_0, 1, Kind.LOAD),
 
-    /** Load reference from local variable 1 */
+    /**
+     * Load {@link TypeKind#REFERENCE reference} from local variable slot {@code 1}.
+     *
+     * @jvms 6.5.aload_n <em>aload_&lt;n&gt;</em>
+     * @see Kind#LOAD
+     */
     ALOAD_1(RawBytecodeHelper.ALOAD_1, 1, Kind.LOAD),
 
-    /** Load reference from local variable 2 */
+    /**
+     * Load {@link TypeKind#REFERENCE reference} from local variable slot {@code 2}.
+     *
+     * @jvms 6.5.aload_n <em>aload_&lt;n&gt;</em>
+     * @see Kind#LOAD
+     */
     ALOAD_2(RawBytecodeHelper.ALOAD_2, 1, Kind.LOAD),
 
-    /** Load reference from local variable 3 */
+    /**
+     * Load {@link TypeKind#REFERENCE reference} from local variable slot {@code 3}.
+     *
+     * @jvms 6.5.aload_n <em>aload_&lt;n&gt;</em>
+     * @see Kind#LOAD
+     */
     ALOAD_3(RawBytecodeHelper.ALOAD_3, 1, Kind.LOAD),
 
-    /** Load int from array */
+    /**
+     * Load {@link TypeKind#INT int} from array.
+     *
+     * @jvms 6.5.iaload <em>iaload</em>
+     * @see Kind#ARRAY_LOAD
+     */
     IALOAD(RawBytecodeHelper.IALOAD, 1, Kind.ARRAY_LOAD),
 
-    /** Load long from array */
+    /**
+     * Load {@link TypeKind#LONG long} from array.
+     *
+     * @jvms 6.5.laload <em>laload</em>
+     * @see Kind#ARRAY_LOAD
+     */
     LALOAD(RawBytecodeHelper.LALOAD, 1, Kind.ARRAY_LOAD),
 
-    /** Load float from array */
+    /**
+     * Load {@link TypeKind#FLOAT float} from array.
+     *
+     * @jvms 6.5.faload <em>faload</em>
+     * @see Kind#ARRAY_LOAD
+     */
     FALOAD(RawBytecodeHelper.FALOAD, 1, Kind.ARRAY_LOAD),
 
-    /** Load double from array */
+    /**
+     * Load {@link TypeKind#DOUBLE double} from array.
+     *
+     * @jvms 6.5.daload <em>daload</em>
+     * @see Kind#ARRAY_LOAD
+     */
     DALOAD(RawBytecodeHelper.DALOAD, 1, Kind.ARRAY_LOAD),
 
-    /** Load reference from array */
+    /**
+     * Load {@link TypeKind#REFERENCE reference} from array.
+     *
+     * @jvms 6.5.aaload <em>aaload</em>
+     * @see Kind#ARRAY_LOAD
+     */
     AALOAD(RawBytecodeHelper.AALOAD, 1, Kind.ARRAY_LOAD),
 
-    /** Load byte from array */
+    /**
+     * Load {@link TypeKind#BYTE byte} or {@link TypeKind#BOOLEAN boolean} from array.
+     *
+     * @jvms 6.5.baload <em>baload</em>
+     * @see Kind#ARRAY_LOAD
+     */
     BALOAD(RawBytecodeHelper.BALOAD, 1, Kind.ARRAY_LOAD),
 
-    /** Load char from array */
+    /**
+     * Load {@link TypeKind#CHAR char} from array.
+     *
+     * @jvms 6.5.caload <em>caload</em>
+     * @see Kind#ARRAY_LOAD
+     */
     CALOAD(RawBytecodeHelper.CALOAD, 1, Kind.ARRAY_LOAD),
 
-    /** Load short from array */
+    /**
+     * Load {@link TypeKind#SHORT short} from array.
+     *
+     * @jvms 6.5.saload <em>saload</em>
+     * @see Kind#ARRAY_LOAD
+     */
     SALOAD(RawBytecodeHelper.SALOAD, 1, Kind.ARRAY_LOAD),
 
-    /** Store int into local variable */
+    /**
+     * Store {@link TypeKind#INT int} into local variable.
+     *
+     * @jvms 6.5.istore <em>istore</em>
+     * @see Kind#STORE
+     */
     ISTORE(RawBytecodeHelper.ISTORE, 2, Kind.STORE),
 
-    /** Store long into local variable */
+    /**
+     * Store {@link TypeKind#LONG long} into local variable.
+     *
+     * @jvms 6.5.lstore <em>lstore</em>
+     * @see Kind#STORE
+     */
     LSTORE(RawBytecodeHelper.LSTORE, 2, Kind.STORE),
 
-    /** Store float into local variable */
+    /**
+     * Store {@link TypeKind#FLOAT float} into local variable.
+     *
+     * @jvms 6.5.fstore <em>fstore</em>
+     * @see Kind#STORE
+     */
     FSTORE(RawBytecodeHelper.FSTORE, 2, Kind.STORE),
 
-    /** Store double into local variable */
+    /**
+     * Store {@link TypeKind#DOUBLE double} into local variable.
+     *
+     * @jvms 6.5.dstore <em>dstore</em>
+     * @see Kind#STORE
+     */
     DSTORE(RawBytecodeHelper.DSTORE, 2, Kind.STORE),
 
-    /** Store reference into local variable */
+    /**
+     * Store {@link TypeKind#REFERENCE reference} into local variable.
+     * Can also store the {@link TypeKind##returnAddress returnAddress} type.
+     *
+     * @jvms 6.5.astore <em>astore</em>
+     * @see Kind#STORE
+     */
     ASTORE(RawBytecodeHelper.ASTORE, 2, Kind.STORE),
 
-    /** Store int into local variable 0 */
+    /**
+     * Store {@link TypeKind#INT int} into local variable slot {@code 0}.
+     *
+     * @jvms 6.5.istore_n <em>istore_&lt;n&gt;</em>
+     * @see Kind#STORE
+     */
     ISTORE_0(RawBytecodeHelper.ISTORE_0, 1, Kind.STORE),
 
-    /** Store int into local variable 1 */
+    /**
+     * Store {@link TypeKind#INT int} into local variable slot {@code 1}.
+     *
+     * @jvms 6.5.istore_n <em>istore_&lt;n&gt;</em>
+     * @see Kind#STORE
+     */
     ISTORE_1(RawBytecodeHelper.ISTORE_1, 1, Kind.STORE),
 
-    /** Store int into local variable 2 */
+    /**
+     * Store {@link TypeKind#INT int} into local variable slot {@code 2}.
+     *
+     * @jvms 6.5.istore_n <em>istore_&lt;n&gt;</em>
+     * @see Kind#STORE
+     */
     ISTORE_2(RawBytecodeHelper.ISTORE_2, 1, Kind.STORE),
 
-    /** Store int into local variable 3 */
+    /**
+     * Store {@link TypeKind#INT int} into local variable slot {@code 3}.
+     *
+     * @jvms 6.5.istore_n <em>istore_&lt;n&gt;</em>
+     * @see Kind#STORE
+     */
     ISTORE_3(RawBytecodeHelper.ISTORE_3, 1, Kind.STORE),
 
-    /** Store long into local variable 0 */
+    /**
+     * Store {@link TypeKind#LONG long} into local variable slot {@code 0}.
+     *
+     * @jvms 6.5.lstore_n <em>lstore_&lt;n&gt;</em>
+     * @see Kind#STORE
+     */
     LSTORE_0(RawBytecodeHelper.LSTORE_0, 1, Kind.STORE),
 
-    /** Store long into local variable 1 */
+    /**
+     * Store {@link TypeKind#LONG long} into local variable slot {@code 1}.
+     *
+     * @jvms 6.5.lstore_n <em>lstore_&lt;n&gt;</em>
+     * @see Kind#STORE
+     */
     LSTORE_1(RawBytecodeHelper.LSTORE_1, 1, Kind.STORE),
 
-    /** Store long into local variable 2 */
+    /**
+     * Store {@link TypeKind#LONG long} into local variable slot {@code 2}.
+     *
+     * @jvms 6.5.lstore_n <em>lstore_&lt;n&gt;</em>
+     * @see Kind#STORE
+     */
     LSTORE_2(RawBytecodeHelper.LSTORE_2, 1, Kind.STORE),
 
-    /** Store long into local variable 3 */
+    /**
+     * Store {@link TypeKind#LONG long} into local variable slot {@code 3}.
+     *
+     * @jvms 6.5.lstore_n <em>lstore_&lt;n&gt;</em>
+     * @see Kind#STORE
+     */
     LSTORE_3(RawBytecodeHelper.LSTORE_3, 1, Kind.STORE),
 
-    /** Store float into local variable 0 */
+    /**
+     * Store {@link TypeKind#FLOAT float} into local variable slot {@code 0}.
+     *
+     * @jvms 6.5.fstore_n <em>fstore_&lt;n&gt;</em>
+     * @see Kind#STORE
+     */
     FSTORE_0(RawBytecodeHelper.FSTORE_0, 1, Kind.STORE),
 
-    /** Store float into local variable 1 */
+    /**
+     * Store {@link TypeKind#FLOAT float} into local variable slot {@code 1}.
+     *
+     * @jvms 6.5.fstore_n <em>fstore_&lt;n&gt;</em>
+     * @see Kind#STORE
+     */
     FSTORE_1(RawBytecodeHelper.FSTORE_1, 1, Kind.STORE),
 
-    /** Store float into local variable 2 */
+    /**
+     * Store {@link TypeKind#FLOAT float} into local variable slot {@code 2}.
+     *
+     * @jvms 6.5.fstore_n <em>fstore_&lt;n&gt;</em>
+     * @see Kind#STORE
+     */
     FSTORE_2(RawBytecodeHelper.FSTORE_2, 1, Kind.STORE),
 
-    /** Store float into local variable 3 */
+    /**
+     * Store {@link TypeKind#FLOAT float} into local variable slot {@code 3}.
+     *
+     * @jvms 6.5.fstore_n <em>fstore_&lt;n&gt;</em>
+     * @see Kind#STORE
+     */
     FSTORE_3(RawBytecodeHelper.FSTORE_3, 1, Kind.STORE),
 
-    /** Store double into local variable 0 */
+    /**
+     * Store {@link TypeKind#DOUBLE double} into local variable slot {@code 0}.
+     *
+     * @jvms 6.5.dstore_n <em>dstore_&lt;n&gt;</em>
+     * @see Kind#STORE
+     */
     DSTORE_0(RawBytecodeHelper.DSTORE_0, 1, Kind.STORE),
 
-    /** Store double into local variable 1 */
+    /**
+     * Store {@link TypeKind#DOUBLE double} into local variable slot {@code 1}.
+     *
+     * @jvms 6.5.dstore_n <em>dstore_&lt;n&gt;</em>
+     * @see Kind#STORE
+     */
     DSTORE_1(RawBytecodeHelper.DSTORE_1, 1, Kind.STORE),
 
-    /** Store double into local variable 2 */
+    /**
+     * Store {@link TypeKind#DOUBLE double} into local variable slot {@code 2}.
+     *
+     * @jvms 6.5.dstore_n <em>dstore_&lt;n&gt;</em>
+     * @see Kind#STORE
+     */
     DSTORE_2(RawBytecodeHelper.DSTORE_2, 1, Kind.STORE),
 
-    /** Store double into local variable 3 */
+    /**
+     * Store {@link TypeKind#DOUBLE double} into local variable slot {@code 3}.
+     *
+     * @jvms 6.5.dstore_n <em>dstore_&lt;n&gt;</em>
+     * @see Kind#STORE
+     */
     DSTORE_3(RawBytecodeHelper.DSTORE_3, 1, Kind.STORE),
 
-    /** Store reference into local variable 0 */
+    /**
+     * Store {@link TypeKind#REFERENCE reference} into local variable slot {@code 0}.
+     * Can also store the {@link TypeKind##returnAddress returnAddress} type.
+     *
+     * @jvms 6.5.astore_n <em>astore_&lt;n&gt;</em>
+     * @see Kind#STORE
+     */
     ASTORE_0(RawBytecodeHelper.ASTORE_0, 1, Kind.STORE),
 
-    /** Store reference into local variable 1 */
+    /**
+     * Store {@link TypeKind#REFERENCE reference} into local variable slot {@code 1}.
+     * Can also store the {@link TypeKind##returnAddress returnAddress} type.
+     *
+     * @jvms 6.5.astore_n <em>astore_&lt;n&gt;</em>
+     * @see Kind#STORE
+     */
     ASTORE_1(RawBytecodeHelper.ASTORE_1, 1, Kind.STORE),
 
-    /** Store reference into local variable 2 */
+    /**
+     * Store {@link TypeKind#REFERENCE reference} into local variable slot {@code 2}.
+     * Can also store the {@link TypeKind##returnAddress returnAddress} type.
+     *
+     * @jvms 6.5.astore_n <em>astore_&lt;n&gt;</em>
+     * @see Kind#STORE
+     */
     ASTORE_2(RawBytecodeHelper.ASTORE_2, 1, Kind.STORE),
 
-    /** Store reference into local variable 3 */
+    /**
+     * Store {@link TypeKind#REFERENCE reference} into local variable slot {@code 3}.
+     * Can also store the {@link TypeKind##returnAddress returnAddress} type.
+     *
+     * @jvms 6.5.astore_n <em>astore_&lt;n&gt;</em>
+     * @see Kind#STORE
+     */
     ASTORE_3(RawBytecodeHelper.ASTORE_3, 1, Kind.STORE),
 
-    /** Store into int array */
+    /**
+     * Store into {@link TypeKind#INT int} array.
+     *
+     * @jvms 6.5.iastore <em>iastore</em>
+     * @see Kind#ARRAY_STORE
+     */
     IASTORE(RawBytecodeHelper.IASTORE, 1, Kind.ARRAY_STORE),
 
-    /** Store into long array */
+    /**
+     * Store into {@link TypeKind#LONG long} array.
+     *
+     * @jvms 6.5.lastore <em>lastore</em>
+     * @see Kind#ARRAY_STORE
+     */
     LASTORE(RawBytecodeHelper.LASTORE, 1, Kind.ARRAY_STORE),
 
-    /** Store into float array */
+    /**
+     * Store into {@link TypeKind#FLOAT float} array.
+     *
+     * @jvms 6.5.fastore <em>fastore</em>
+     * @see Kind#ARRAY_STORE
+     */
     FASTORE(RawBytecodeHelper.FASTORE, 1, Kind.ARRAY_STORE),
 
-    /** Store into double array */
+    /**
+     * Store into {@link TypeKind#DOUBLE double} array.
+     *
+     * @jvms 6.5.dastore <em>dastore</em>
+     * @see Kind#ARRAY_STORE
+     */
     DASTORE(RawBytecodeHelper.DASTORE, 1, Kind.ARRAY_STORE),
 
-    /** Store into reference array */
+    /**
+     * Store into {@link TypeKind#REFERENCE reference} array.
+     *
+     * @jvms 6.5.aastore <em>aastore</em>
+     * @see Kind#ARRAY_STORE
+     */
     AASTORE(RawBytecodeHelper.AASTORE, 1, Kind.ARRAY_STORE),
 
-    /** Store into byte array */
+    /**
+     * Store into {@link TypeKind#BYTE byte} or {@link TypeKind#BOOLEAN boolean} array.
+     *
+     * @jvms 6.5.bastore <em>bastore</em>
+     * @see Kind#ARRAY_STORE
+     */
     BASTORE(RawBytecodeHelper.BASTORE, 1, Kind.ARRAY_STORE),
 
-    /** Store into char array */
+    /**
+     * Store into {@link TypeKind#CHAR char} array.
+     *
+     * @jvms 6.5.castore <em>castore</em>
+     * @see Kind#ARRAY_STORE
+     */
     CASTORE(RawBytecodeHelper.CASTORE, 1, Kind.ARRAY_STORE),
 
-    /** Store into short array */
+    /**
+     * Store into {@link TypeKind#SHORT short} array.
+     *
+     * @jvms 6.5.sastore <em>sastore</em>
+     * @see Kind#ARRAY_STORE
+     */
     SASTORE(RawBytecodeHelper.SASTORE, 1, Kind.ARRAY_STORE),
 
-    /** Pop the top operand stack value */
+    /**
+     * Pop the top operand stack value.
+     *
+     * @jvms 6.5.pop <em>pop</em>
+     * @see Kind#STACK
+     */
     POP(RawBytecodeHelper.POP, 1, Kind.STACK),
 
-    /** Pop the top one or two operand stack values */
+    /**
+     * Pop the top one or two operand stack values.
+     *
+     * @jvms 6.5.pop2 <em>pop2</em>
+     * @see Kind#STACK
+     */
     POP2(RawBytecodeHelper.POP2, 1, Kind.STACK),
 
-    /** Duplicate the top operand stack value */
+    /**
+     * Duplicate the top operand stack value.
+     *
+     * @jvms 6.5.dup <em>dup</em>
+     * @see Kind#STACK
+     */
     DUP(RawBytecodeHelper.DUP, 1, Kind.STACK),
 
-    /** Duplicate the top operand stack value and insert two values down */
+    /**
+     * Duplicate the top operand stack value and insert two values down.
+     *
+     * @jvms 6.5.dup_x1 <em>dup_x1</em>
+     * @see Kind#STACK
+     */
     DUP_X1(RawBytecodeHelper.DUP_X1, 1, Kind.STACK),
 
-    /** Duplicate the top operand stack value and insert two or three values down */
+    /**
+     * Duplicate the top operand stack value and insert two or three values down.
+     *
+     * @jvms 6.5.dup_x2 <em>dup_x2</em>
+     * @see Kind#STACK
+     */
     DUP_X2(RawBytecodeHelper.DUP_X2, 1, Kind.STACK),
 
-    /** Duplicate the top one or two operand stack values */
+    /**
+     * Duplicate the top one or two operand stack values.
+     *
+     * @jvms 6.5.dup2 <em>dup2</em>
+     * @see Kind#STACK
+     */
     DUP2(RawBytecodeHelper.DUP2, 1, Kind.STACK),
 
-    /** Duplicate the top one or two operand stack values and insert two or three values down */
+    /**
+     * Duplicate the top one or two operand stack values and insert two or three
+     * values down.
+     *
+     * @jvms 6.5.dup2_x1 <em>dup2_x1</em>
+     * @see Kind#STACK
+     */
     DUP2_X1(RawBytecodeHelper.DUP2_X1, 1, Kind.STACK),
 
-    /** Duplicate the top one or two operand stack values and insert two, three, or four values down */
+    /**
+     * Duplicate the top one or two operand stack values and insert two, three,
+     * or four values down.
+     *
+     * @jvms 6.5.dup2_x2 <em>dup2_x2</em>
+     * @see Kind#STACK
+     */
     DUP2_X2(RawBytecodeHelper.DUP2_X2, 1, Kind.STACK),
 
-    /** Swap the top two operand stack values */
+    /**
+     * Swap the top two operand stack values.
+     *
+     * @jvms 6.5.swap <em>swap</em>
+     * @see Kind#STACK
+     */
     SWAP(RawBytecodeHelper.SWAP, 1, Kind.STACK),
 
-    /** Add int */
+    /**
+     * Add {@link TypeKind#INT int}.
+     *
+     * @jvms 6.5.iadd <em>iadd</em>
+     * @see Kind#OPERATOR
+     */
     IADD(RawBytecodeHelper.IADD, 1, Kind.OPERATOR),
 
-    /** Add long */
+    /**
+     * Add {@link TypeKind#LONG long}.
+     *
+     * @jvms 6.5.ladd <em>ladd</em>
+     * @see Kind#OPERATOR
+     */
     LADD(RawBytecodeHelper.LADD, 1, Kind.OPERATOR),
 
-    /** Add float */
+    /**
+     * Add {@link TypeKind#FLOAT float}.
+     *
+     * @jvms 6.5.fadd <em>fadd</em>
+     * @see Kind#OPERATOR
+     */
     FADD(RawBytecodeHelper.FADD, 1, Kind.OPERATOR),
 
-    /** Add double */
+    /**
+     * Add {@link TypeKind#DOUBLE double}.
+     *
+     * @jvms 6.5.dadd <em>dadd</em>
+     * @see Kind#OPERATOR
+     */
     DADD(RawBytecodeHelper.DADD, 1, Kind.OPERATOR),
 
-    /** Subtract int */
+    /**
+     * Subtract {@link TypeKind#INT int}.
+     *
+     * @jvms 6.5.isub <em>isub</em>
+     * @see Kind#OPERATOR
+     */
     ISUB(RawBytecodeHelper.ISUB, 1, Kind.OPERATOR),
 
-    /** Subtract long */
+    /**
+     * Subtract {@link TypeKind#LONG long}.
+     *
+     * @jvms 6.5.lsub <em>lsub</em>
+     * @see Kind#OPERATOR
+     */
     LSUB(RawBytecodeHelper.LSUB, 1, Kind.OPERATOR),
 
-    /** Subtract float */
+    /**
+     * Subtract {@link TypeKind#FLOAT float}.
+     *
+     * @jvms 6.5.fsub <em>fsub</em>
+     * @see Kind#OPERATOR
+     */
     FSUB(RawBytecodeHelper.FSUB, 1, Kind.OPERATOR),
 
-    /** Subtract double */
+    /**
+     * Subtract {@link TypeKind#DOUBLE double}.
+     *
+     * @jvms 6.5.dsub <em>dsub</em>
+     * @see Kind#OPERATOR
+     */
     DSUB(RawBytecodeHelper.DSUB, 1, Kind.OPERATOR),
 
-    /** Multiply int */
+    /**
+     * Multiply {@link TypeKind#INT int}.
+     *
+     * @jvms 6.5.imul <em>imul</em>
+     * @see Kind#OPERATOR
+     */
     IMUL(RawBytecodeHelper.IMUL, 1, Kind.OPERATOR),
 
-    /** Multiply long */
+    /**
+     * Multiply {@link TypeKind#LONG long}.
+     *
+     * @jvms 6.5.lmul <em>lmul</em>
+     * @see Kind#OPERATOR
+     */
     LMUL(RawBytecodeHelper.LMUL, 1, Kind.OPERATOR),
 
-    /** Multiply float */
+    /**
+     * Multiply {@link TypeKind#FLOAT float}.
+     *
+     * @jvms 6.5.fmul <em>fmul</em>
+     * @see Kind#OPERATOR
+     */
     FMUL(RawBytecodeHelper.FMUL, 1, Kind.OPERATOR),
 
-    /** Multiply double */
+    /**
+     * Multiply {@link TypeKind#DOUBLE double}.
+     *
+     * @jvms 6.5.dmul <em>dmul</em>
+     * @see Kind#OPERATOR
+     */
     DMUL(RawBytecodeHelper.DMUL, 1, Kind.OPERATOR),
 
-    /** Divide int */
+    /**
+     * Divide {@link TypeKind#INT int}.
+     *
+     * @jvms 6.5.idiv <em>idiv</em>
+     * @see Kind#OPERATOR
+     */
     IDIV(RawBytecodeHelper.IDIV, 1, Kind.OPERATOR),
 
-    /** Divide long */
+    /**
+     * Divide {@link TypeKind#LONG long}.
+     *
+     * @jvms 6.5.ldiv <em>ldiv</em>
+     * @see Kind#OPERATOR
+     */
     LDIV(RawBytecodeHelper.LDIV, 1, Kind.OPERATOR),
 
-    /** Divide float */
+    /**
+     * Divide {@link TypeKind#FLOAT float}.
+     *
+     * @jvms 6.5.fdiv <em>fdiv</em>
+     * @see Kind#OPERATOR
+     */
     FDIV(RawBytecodeHelper.FDIV, 1, Kind.OPERATOR),
 
-    /** Divide double */
+    /**
+     * Divide {@link TypeKind#DOUBLE double}.
+     *
+     * @jvms 6.5.ddiv <em>ddiv</em>
+     * @see Kind#OPERATOR
+     */
     DDIV(RawBytecodeHelper.DDIV, 1, Kind.OPERATOR),
 
-    /** Remainder int */
+    /**
+     * Remainder {@link TypeKind#INT int}.
+     *
+     * @jvms 6.5.irem <em>irem</em>
+     * @see Kind#OPERATOR
+     */
     IREM(RawBytecodeHelper.IREM, 1, Kind.OPERATOR),
 
-    /** Remainder long */
+    /**
+     * Remainder {@link TypeKind#LONG long}.
+     *
+     * @jvms 6.5.lrem <em>lrem</em>
+     * @see Kind#OPERATOR
+     */
     LREM(RawBytecodeHelper.LREM, 1, Kind.OPERATOR),
 
-    /** Remainder float */
+    /**
+     * Remainder {@link TypeKind#FLOAT float}.
+     *
+     * @jvms 6.5.frem <em>frem</em>
+     * @see Kind#OPERATOR
+     */
     FREM(RawBytecodeHelper.FREM, 1, Kind.OPERATOR),
 
-    /** Remainder double */
+    /**
+     * Remainder {@link TypeKind#DOUBLE double}.
+     *
+     * @jvms 6.5.drem <em>drem</em>
+     * @see Kind#OPERATOR
+     */
     DREM(RawBytecodeHelper.DREM, 1, Kind.OPERATOR),
 
-    /** Negate int */
+    /**
+     * Negate {@link TypeKind#INT int}.
+     *
+     * @jvms 6.5.ineg <em>ineg</em>
+     * @see Kind#OPERATOR
+     */
     INEG(RawBytecodeHelper.INEG, 1, Kind.OPERATOR),
 
-    /** Negate long */
+    /**
+     * Negate {@link TypeKind#LONG long}.
+     *
+     * @jvms 6.5.lneg <em>lneg</em>
+     * @see Kind#OPERATOR
+     */
     LNEG(RawBytecodeHelper.LNEG, 1, Kind.OPERATOR),
 
-    /** Negate float */
+    /**
+     * Negate {@link TypeKind#FLOAT float}.
+     *
+     * @jvms 6.5.fneg <em>fneg</em>
+     * @see Kind#OPERATOR
+     */
     FNEG(RawBytecodeHelper.FNEG, 1, Kind.OPERATOR),
 
-    /** Negate double */
+    /**
+     * Negate {@link TypeKind#DOUBLE double}.
+     *
+     * @jvms 6.5.dneg <em>dneg</em>
+     * @see Kind#OPERATOR
+     */
     DNEG(RawBytecodeHelper.DNEG, 1, Kind.OPERATOR),
 
-    /** Shift left int */
+    /**
+     * Shift left {@link TypeKind#INT int}.
+     *
+     * @jvms 6.5.ishl <em>ishl</em>
+     * @see Kind#OPERATOR
+     */
     ISHL(RawBytecodeHelper.ISHL, 1, Kind.OPERATOR),
 
-    /** Shift left long */
+    /**
+     * Shift left {@link TypeKind#LONG long}.
+     *
+     * @jvms 6.5.lshl <em>lshl</em>
+     * @see Kind#OPERATOR
+     */
     LSHL(RawBytecodeHelper.LSHL, 1, Kind.OPERATOR),
 
-    /** Shift right int */
+    /**
+     * Arithmetic shift right {@link TypeKind#INT int}.
+     *
+     * @jvms 6.5.ishr <em>ishr</em>
+     * @see Kind#OPERATOR
+     */
     ISHR(RawBytecodeHelper.ISHR, 1, Kind.OPERATOR),
 
-    /** Shift right long */
+    /**
+     * Arithmetic shift right {@link TypeKind#LONG long}.
+     *
+     * @jvms 6.5.lshr <em>lshr</em>
+     * @see Kind#OPERATOR
+     */
     LSHR(RawBytecodeHelper.LSHR, 1, Kind.OPERATOR),
 
-    /** Logical shift right int */
+    /**
+     * Logical shift right {@link TypeKind#INT int}.
+     *
+     * @jvms 6.5.iushr <em>iushr</em>
+     * @see Kind#OPERATOR
+     */
     IUSHR(RawBytecodeHelper.IUSHR, 1, Kind.OPERATOR),
 
-    /** Logical shift right long */
+    /**
+     * Logical shift right {@link TypeKind#LONG long}.
+     *
+     * @jvms 6.5.lushr <em>lushr</em>
+     * @see Kind#OPERATOR
+     */
     LUSHR(RawBytecodeHelper.LUSHR, 1, Kind.OPERATOR),
 
-    /** Boolean AND int */
+    /**
+     * Bitwise AND {@link TypeKind#INT int}.
+     *
+     * @apiNote
+     * This may be used to implement {@link TypeKind#BOOLEAN boolean} AND.
+     *
+     * @jvms 6.5.iand <em>iand</em>
+     * @see Kind#OPERATOR
+     */
     IAND(RawBytecodeHelper.IAND, 1, Kind.OPERATOR),
 
-    /** Boolean AND long */
+    /**
+     * Bitwise AND {@link TypeKind#LONG long}.
+     *
+     * @jvms 6.5.land <em>land</em>
+     * @see Kind#OPERATOR
+     */
     LAND(RawBytecodeHelper.LAND, 1, Kind.OPERATOR),
 
-    /** Boolean OR int */
+    /**
+     * Bitwise OR {@link TypeKind#INT int}.
+     *
+     * @apiNote
+     * This may be used to implement {@link TypeKind#BOOLEAN boolean} OR.
+     *
+     * @jvms 6.5.ior <em>ior</em>
+     * @see Kind#OPERATOR
+     */
     IOR(RawBytecodeHelper.IOR, 1, Kind.OPERATOR),
 
-    /** Boolean OR long */
+    /**
+     * Bitwise OR {@link TypeKind#LONG long}.
+     *
+     * @jvms 6.5.lor <em>lor</em>
+     * @see Kind#OPERATOR
+     */
     LOR(RawBytecodeHelper.LOR, 1, Kind.OPERATOR),
 
-    /** Boolean XOR int */
+    /**
+     * Bitwise XOR {@link TypeKind#INT int}.
+     *
+     * @apiNote
+     * This may be used to implement {@link TypeKind#BOOLEAN boolean} XOR.
+     *
+     * @jvms 6.5.ixor <em>ixor</em>
+     * @see Kind#OPERATOR
+     */
     IXOR(RawBytecodeHelper.IXOR, 1, Kind.OPERATOR),
 
-    /** Boolean XOR long */
+    /**
+     * Bitwise XOR {@link TypeKind#LONG long}.
+     *
+     * @jvms 6.5.lxor <em>lxor</em>
+     * @see Kind#OPERATOR
+     */
     LXOR(RawBytecodeHelper.LXOR, 1, Kind.OPERATOR),
 
-    /** Increment local variable by constant */
+    /**
+     * Increment local variable by constant.
+     *
+     * @jvms 6.5.iinc <em>iinc</em>
+     * @see Kind#INCREMENT
+     */
     IINC(RawBytecodeHelper.IINC, 3, Kind.INCREMENT),
 
-    /** Convert int to long */
+    /**
+     * Convert {@link TypeKind#INT int} to {@link TypeKind#LONG long}.
+     *
+     * @jls 5.1.2 Widening Primitive Conversion
+     * @jvms 6.5.i2l <em>i2l</em>
+     * @see Kind#CONVERT
+     */
     I2L(RawBytecodeHelper.I2L, 1, Kind.CONVERT),
 
-    /** Convert int to float */
+    /**
+     * Convert {@link TypeKind#INT int} to {@link TypeKind#FLOAT float}.
+     *
+     * @jls 5.1.2 Widening Primitive Conversion
+     * @jvms 6.5.i2f <em>i2f</em>
+     * @see Kind#CONVERT
+     */
     I2F(RawBytecodeHelper.I2F, 1, Kind.CONVERT),
 
-    /** Convert int to double */
+    /**
+     * Convert {@link TypeKind#INT int} to {@link TypeKind#DOUBLE double}.
+     *
+     * @jls 5.1.2 Widening Primitive Conversion
+     * @jvms 6.5.i2d <em>i2d</em>
+     * @see Kind#CONVERT
+     */
     I2D(RawBytecodeHelper.I2D, 1, Kind.CONVERT),
 
-    /** Convert long to int */
+    /**
+     * Convert {@link TypeKind#LONG long} to {@link TypeKind#INT int}.
+     *
+     * @jls 5.1.3 Narrowing Primitive Conversion
+     * @jvms 6.5.l2i <em>l2i</em>
+     * @see Kind#CONVERT
+     */
     L2I(RawBytecodeHelper.L2I, 1, Kind.CONVERT),
 
-    /** Convert long to float */
+    /** Convert {@link TypeKind#LONG long} to {@link TypeKind#FLOAT float}.
+     *
+     * @jls 5.1.2 Widening Primitive Conversion
+     * @jvms 6.5.l2f <em>l2f</em>
+     * @see Kind#CONVERT
+     */
     L2F(RawBytecodeHelper.L2F, 1, Kind.CONVERT),
 
-    /** Convert long to double */
+    /** Convert {@link TypeKind#LONG long} to {@link TypeKind#DOUBLE double}.
+     *
+     * @jls 5.1.2 Widening Primitive Conversion
+     * @jvms 6.5.l2d <em>l2d</em>
+     * @see Kind#CONVERT
+     */
     L2D(RawBytecodeHelper.L2D, 1, Kind.CONVERT),
 
-    /** Convert float to int */
+    /**
+     * Convert {@link TypeKind#FLOAT float} to {@link TypeKind#INT int}.
+     *
+     * @jls 5.1.3 Narrowing Primitive Conversion
+     * @jvms 6.5.f2i <em>f2i</em>
+     * @see Kind#CONVERT
+     */
     F2I(RawBytecodeHelper.F2I, 1, Kind.CONVERT),
 
-    /** Convert float to long */
+    /**
+     * Convert {@link TypeKind#FLOAT float} to {@link TypeKind#LONG long}.
+     *
+     * @jls 5.1.3 Narrowing Primitive Conversion
+     * @jvms 6.5.f2l <em>f2l</em>
+     * @see Kind#CONVERT
+     */
     F2L(RawBytecodeHelper.F2L, 1, Kind.CONVERT),
 
-    /** Convert float to double */
+    /**
+     * Convert {@link TypeKind#FLOAT float} to {@link TypeKind#DOUBLE double}.
+     *
+     * @jls 5.1.2 Widening Primitive Conversion
+     * @jvms 6.5.f2d <em>f2d</em>
+     * @see Kind#CONVERT
+     */
     F2D(RawBytecodeHelper.F2D, 1, Kind.CONVERT),
 
-    /** Convert double to int */
+    /**
+     * Convert {@link TypeKind#DOUBLE double} to {@link TypeKind#INT int}.
+     *
+     * @jls 5.1.3 Narrowing Primitive Conversion
+     * @jvms 6.5.d2i <em>d2i</em>
+     * @see Kind#CONVERT
+     */
     D2I(RawBytecodeHelper.D2I, 1, Kind.CONVERT),
 
-    /** Convert double to long */
+    /**
+     * Convert {@link TypeKind#DOUBLE double} to {@link TypeKind#LONG long}.
+     *
+     * @jvms 6.5.d2l <em>d2l</em>
+     * @see Kind#CONVERT
+     */
     D2L(RawBytecodeHelper.D2L, 1, Kind.CONVERT),
 
-    /** Convert double to float */
+    /**
+     * Convert {@link TypeKind#DOUBLE double} to {@link TypeKind#FLOAT float}.
+     *
+     * @jls 5.1.3 Narrowing Primitive Conversion
+     * @jvms 6.5.d2f <em>d2f</em>
+     * @see Kind#CONVERT
+     */
     D2F(RawBytecodeHelper.D2F, 1, Kind.CONVERT),
 
-    /** Convert int to byte */
+    /**
+     * Convert {@link TypeKind#INT int} to {@link TypeKind#BYTE byte}.
+     * This is as if storing the {@linkplain TypeKind##computational-type
+     * computational} {@code int} into a {@code byte} and loading it back.
+     *
+     * @jls 5.1.3 Narrowing Primitive Conversion
+     * @jvms 6.5.i2b <em>i2b</em>
+     * @see Kind#CONVERT
+     */
     I2B(RawBytecodeHelper.I2B, 1, Kind.CONVERT),
 
-    /** Convert int to char */
+    /**
+     * Convert {@link TypeKind#INT int} to {@link TypeKind#CHAR char}.
+     * This is as if storing the {@linkplain TypeKind##computational-type
+     * computational} {@code int} into a {@code char} and loading it back.
+     *
+     * @jls 5.1.3 Narrowing Primitive Conversion
+     * @jvms 6.5.i2c <em>i2c</em>
+     * @see Kind#CONVERT
+     */
     I2C(RawBytecodeHelper.I2C, 1, Kind.CONVERT),
 
-    /** Convert int to short */
+    /**
+     * Convert {@link TypeKind#INT int} to {@link TypeKind#SHORT short}.
+     * This is as if storing the {@linkplain TypeKind##computational-type
+     * computational} {@code int} into a {@code short} and loading it back.
+     *
+     * @jls 5.1.3 Narrowing Primitive Conversion
+     * @jvms 6.5.i2s <em>i2s</em>
+     * @see Kind#CONVERT
+     */
     I2S(RawBytecodeHelper.I2S, 1, Kind.CONVERT),
 
-    /** Compare long */
+    /**
+     * Compare {@link TypeKind#LONG long}.
+     *
+     * @see Long#compare(long, long)
+     * @jvms 6.5.lcmp <em>lcmp</em>
+     * @see Kind#OPERATOR
+     */
     LCMP(RawBytecodeHelper.LCMP, 1, Kind.OPERATOR),
 
-    /** Compare float */
+    /**
+     * Compare {@link TypeKind#FLOAT float}.
+     * Produces {@code -1} if any operand is {@link Float#isNaN(float) NaN}.
+     *
+     * @see Double##equivalenceRelation Floating-point Equality, Equivalence, and Comparison
+     * @jvms 6.5.fcmp_op <em>fcmp&lt;op&gt;</em>
+     * @see Kind#OPERATOR
+     */
     FCMPL(RawBytecodeHelper.FCMPL, 1, Kind.OPERATOR),
 
-    /** Compare float */
+    /**
+     * Compare {@link TypeKind#FLOAT float}.
+     * Produces {@code 1} if any operand is {@link Float#isNaN(float) NaN}.
+     *
+     * @see Double##equivalenceRelation Floating-point Equality, Equivalence, and Comparison
+     * @jvms 6.5.fcmp_op <em>fcmp&lt;op&gt;</em>
+     * @see Kind#OPERATOR
+     */
     FCMPG(RawBytecodeHelper.FCMPG, 1, Kind.OPERATOR),
 
-    /** Compare double */
+    /**
+     * Compare {@link TypeKind#DOUBLE double}.
+     * Produces {@code -1} if any operand is {@link Double#isNaN(double) NaN}.
+     *
+     * @see Double##equivalenceRelation Floating-point Equality, Equivalence, and Comparison
+     * @jvms 6.5.dcmp_op <em>dcmp&lt;op&gt;</em>
+     * @see Kind#OPERATOR
+     */
     DCMPL(RawBytecodeHelper.DCMPL, 1, Kind.OPERATOR),
 
-    /** Compare double */
+    /**
+     * Compare {@link TypeKind#DOUBLE double}.
+     * Produces {@code 1} if any operand is {@link Double#isNaN(double) NaN}.
+     *
+     * @see Double##equivalenceRelation Floating-point Equality, Equivalence, and Comparison
+     * @jvms 6.5.dcmp_op <em>dcmp&lt;op&gt;</em>
+     * @see Kind#OPERATOR
+     */
     DCMPG(RawBytecodeHelper.DCMPG, 1, Kind.OPERATOR),
 
-    /** Branch if int comparison with zero succeeds */
+    /**
+     * Branch if {@link TypeKind#INT int} comparison {@code == 0} succeeds.
+     *
+     * @jvms 6.5.if_cond <em>if_&lt;cond&gt;</em>
+     * @see Kind#BRANCH
+     */
     IFEQ(RawBytecodeHelper.IFEQ, 3, Kind.BRANCH),
 
-    /** Branch if int comparison with zero succeeds */
+    /**
+     * Branch if {@link TypeKind#INT int} comparison {@code != 0} succeeds.
+     *
+     * @jvms 6.5.if_cond <em>if_&lt;cond&gt;</em>
+     * @see Kind#BRANCH
+     */
     IFNE(RawBytecodeHelper.IFNE, 3, Kind.BRANCH),
 
-    /** Branch if int comparison with zero succeeds */
+    /**
+     * Branch if {@link TypeKind#INT int} comparison {@code < 0} succeeds.
+     *
+     * @jvms 6.5.if_cond <em>if_&lt;cond&gt;</em>
+     * @see Kind#BRANCH
+     */
     IFLT(RawBytecodeHelper.IFLT, 3, Kind.BRANCH),
 
-    /** Branch if int comparison with zero succeeds */
+    /**
+     * Branch if {@link TypeKind#INT int} comparison {@code >= 0} succeeds.
+     *
+     * @jvms 6.5.if_cond <em>if_&lt;cond&gt;</em>
+     * @see Kind#BRANCH
+     */
     IFGE(RawBytecodeHelper.IFGE, 3, Kind.BRANCH),
 
-    /** Branch if int comparison with zero succeeds */
+    /**
+     * Branch if {@link TypeKind#INT int} comparison {@code > 0} succeeds.
+     *
+     * @jvms 6.5.if_cond <em>if_&lt;cond&gt;</em>
+     * @see Kind#BRANCH
+     */
     IFGT(RawBytecodeHelper.IFGT, 3, Kind.BRANCH),
 
-    /** Branch if int comparison with zero succeeds */
+    /**
+     * Branch if {@link TypeKind#INT int} comparison {@code <= 0} succeeds.
+     *
+     * @jvms 6.5.if_cond <em>if_&lt;cond&gt;</em>
+     * @see Kind#BRANCH
+     */
     IFLE(RawBytecodeHelper.IFLE, 3, Kind.BRANCH),
 
-    /** Branch if int comparison succeeds */
+    /**
+     * Branch if {@link TypeKind#INT int} comparison {@code operand1 == operand2} succeeds.
+     *
+     * @jvms 6.5.if_icmp_cond <em>if_icmp&lt;cond&gt;</em>
+     * @see Kind#BRANCH
+     */
     IF_ICMPEQ(RawBytecodeHelper.IF_ICMPEQ, 3, Kind.BRANCH),
 
-    /** Branch if int comparison succeeds */
+    /**
+     * Branch if {@link TypeKind#INT int} comparison {@code operand1 != operand2} succeeds.
+     *
+     * @jvms 6.5.if_icmp_cond <em>if_icmp&lt;cond&gt;</em>
+     * @see Kind#BRANCH
+     */
     IF_ICMPNE(RawBytecodeHelper.IF_ICMPNE, 3, Kind.BRANCH),
 
-    /** Branch if int comparison succeeds */
+    /**
+     * Branch if {@link TypeKind#INT int} comparison {@code operand1 < operand2} succeeds.
+     *
+     * @jvms 6.5.if_icmp_cond <em>if_icmp&lt;cond&gt;</em>
+     * @see Kind#BRANCH
+     */
     IF_ICMPLT(RawBytecodeHelper.IF_ICMPLT, 3, Kind.BRANCH),
 
-    /** Branch if int comparison succeeds */
+    /**
+     * Branch if {@link TypeKind#INT int} comparison {@code operand1 >= operand2} succeeds.
+     *
+     * @jvms 6.5.if_icmp_cond <em>if_icmp&lt;cond&gt;</em>
+     * @see Kind#BRANCH
+     */
     IF_ICMPGE(RawBytecodeHelper.IF_ICMPGE, 3, Kind.BRANCH),
 
-    /** Branch if int comparison succeeds */
+    /**
+     * Branch if {@link TypeKind#INT int} comparison {@code operand1 > operand2} succeeds.
+     *
+     * @jvms 6.5.if_icmp_cond <em>if_icmp&lt;cond&gt;</em>
+     * @see Kind#BRANCH
+     */
     IF_ICMPGT(RawBytecodeHelper.IF_ICMPGT, 3, Kind.BRANCH),
 
-    /** Branch if int comparison succeeds */
+    /**
+     * Branch if {@link TypeKind#INT int} comparison {@code operand1 <= operand2} succeeds.
+     *
+     * @jvms 6.5.if_icmp_cond <em>if_icmp&lt;cond&gt;</em>
+     * @see Kind#BRANCH
+     */
     IF_ICMPLE(RawBytecodeHelper.IF_ICMPLE, 3, Kind.BRANCH),
 
-    /** Branch if reference comparison succeeds */
+    /**
+     * Branch if {@link TypeKind#REFERENCE reference} comparison
+     * {@code operand1 == operand2} succeeds.
+     *
+     * @jvms 6.5.if_acmp_cond <em>if_acmp&lt;cond&gt;</em>
+     * @see Kind#BRANCH
+     */
     IF_ACMPEQ(RawBytecodeHelper.IF_ACMPEQ, 3, Kind.BRANCH),
 
-    /** Branch if reference comparison succeeds */
+    /**
+     * Branch if {@link TypeKind#REFERENCE reference} comparison
+     * {@code operand1 != operand2} succeeds.
+     *
+     * @jvms 6.5.if_acmp_cond <em>if_acmp&lt;cond&gt;</em>
+     * @see Kind#BRANCH
+     */
     IF_ACMPNE(RawBytecodeHelper.IF_ACMPNE, 3, Kind.BRANCH),
 
-    /** Branch always */
+    /**
+     * Branch always.
+     *
+     * @jvms 6.5.goto <em>goto</em>
+     * @see Kind#BRANCH
+     */
     GOTO(RawBytecodeHelper.GOTO, 3, Kind.BRANCH),
 
     /**
-     * Jump subroutine is discontinued opcode
-     * @see io.github.dmlloyd.classfile.instruction.DiscontinuedInstruction
+     * (Discontinued) Jump subroutine; last used in major version {@value
+     * ClassFile#JAVA_6_VERSION}.
+     *
+     * @jvms 4.9.1 Static Constraints
+     * @jvms 6.5.jsr <em>jsr</em>
+     * @see Kind#DISCONTINUED_JSR
      */
     JSR(RawBytecodeHelper.JSR, 3, Kind.DISCONTINUED_JSR),
 
     /**
-     * Return from subroutine is discontinued opcode
-     * @see io.github.dmlloyd.classfile.instruction.DiscontinuedInstruction
+     * (Discontinued) Return from subroutine; last used in major version
+     * {@value ClassFile#JAVA_6_VERSION}.
+     *
+     * @jvms 4.9.1 Static Constraints
+     * @jvms 6.5.ret <em>ret</em>
+     * @see Kind#DISCONTINUED_RET
      */
     RET(RawBytecodeHelper.RET, 2, Kind.DISCONTINUED_RET),
 
-    /** Access jump table by index and jump */
+    /**
+     * Access jump table by index and jump.
+     *
+     * @jvms 6.5.tableswitch <em>tableswitch</em>
+     * @see Kind#TABLE_SWITCH
+     */
     TABLESWITCH(RawBytecodeHelper.TABLESWITCH, -1, Kind.TABLE_SWITCH),
 
-    /** Access jump table by key match and jump */
+    /**
+     * Access jump table by key match and jump.
+     *
+     * @jvms 6.5.lookupswitch <em>lookupswitch</em>
+     * @see Kind#LOOKUP_SWITCH
+     */
     LOOKUPSWITCH(RawBytecodeHelper.LOOKUPSWITCH, -1, Kind.LOOKUP_SWITCH),
 
-    /** Return int from method */
+    /**
+     * Return {@link TypeKind#INT int} from method.
+     *
+     * @jvms 6.5.ireturn <em>ireturn</em>
+     * @see Kind#RETURN
+     */
     IRETURN(RawBytecodeHelper.IRETURN, 1, Kind.RETURN),
 
-    /** Return long from method */
+    /**
+     * Return {@link TypeKind#LONG long} from method.
+     *
+     * @jvms 6.5.lreturn <em>lreturn</em>
+     * @see Kind#RETURN
+     */
     LRETURN(RawBytecodeHelper.LRETURN, 1, Kind.RETURN),
 
-    /** Return float from method */
+    /**
+     * Return {@link TypeKind#FLOAT float} from method.
+     *
+     * @jvms 6.5.freturn <em>freturn</em>
+     * @see Kind#RETURN
+     */
     FRETURN(RawBytecodeHelper.FRETURN, 1, Kind.RETURN),
 
-    /** Return double from method */
+    /**
+     * Return {@link TypeKind#DOUBLE double} from method.
+     *
+     * @jvms 6.5.dreturn <em>dreturn</em>
+     * @see Kind#RETURN
+     */
     DRETURN(RawBytecodeHelper.DRETURN, 1, Kind.RETURN),
 
-    /** Return reference from method */
+    /**
+     * Return {@link TypeKind#REFERENCE reference} from method.
+     *
+     * @jvms 6.5.areturn <em>areturn</em>
+     * @see Kind#RETURN
+     */
     ARETURN(RawBytecodeHelper.ARETURN, 1, Kind.RETURN),
 
-    /** Return void from method */
+    /**
+     * Return {@link TypeKind#VOID void} from method.
+     *
+     * @jvms 6.5.return <em>return</em>
+     * @see Kind#RETURN
+     */
     RETURN(RawBytecodeHelper.RETURN, 1, Kind.RETURN),
 
-    /** Get static field from class */
+    /**
+     * Get {@code static} field from class.
+     *
+     * @jvms 6.5.getstatic <em>getstatic</em>
+     * @see Kind#FIELD_ACCESS
+     */
     GETSTATIC(RawBytecodeHelper.GETSTATIC, 3, Kind.FIELD_ACCESS),
 
-    /** Set static field in class */
+    /**
+     * Set {@code static} field in class.
+     *
+     * @jvms 6.5.putstatic <em>putstatic</em>
+     * @see Kind#FIELD_ACCESS
+     */
     PUTSTATIC(RawBytecodeHelper.PUTSTATIC, 3, Kind.FIELD_ACCESS),
 
-    /** Fetch field from object */
+    /**
+     * Fetch field from object.
+     *
+     * @jvms 6.5.getfield <em>getfield</em>
+     * @see Kind#FIELD_ACCESS
+     */
     GETFIELD(RawBytecodeHelper.GETFIELD, 3, Kind.FIELD_ACCESS),
 
-    /** Set field in object */
+    /**
+     * Set field in object.
+     *
+     * @jvms 6.5.putfield <em>putfield</em>
+     * @see Kind#FIELD_ACCESS
+     */
     PUTFIELD(RawBytecodeHelper.PUTFIELD, 3, Kind.FIELD_ACCESS),
 
-    /** Invoke instance method; dispatch based on class */
+    /**
+     * Invoke instance method; dispatch based on class.
+     *
+     * @jvms 6.5.invokevirtual <em>invokevirtual</em>
+     * @see Kind#INVOKE
+     */
     INVOKEVIRTUAL(RawBytecodeHelper.INVOKEVIRTUAL, 3, Kind.INVOKE),
 
     /**
      * Invoke instance method; direct invocation of instance initialization
-     * methods and methods of the current class and its supertypes
+     * methods and methods of the current class and its supertypes.
+     *
+     * @jvms 6.5.invokevirtual <em>invokevirtual</em>
+     * @see Kind#INVOKE
      */
     INVOKESPECIAL(RawBytecodeHelper.INVOKESPECIAL, 3, Kind.INVOKE),
 
-    /** Invoke a class (static) method */
+    /**
+     * Invoke a class ({@code static}) method.
+     *
+     * @jvms 6.5.invokestatic <em>invokestatic</em>
+     * @see Kind#INVOKE
+     */
     INVOKESTATIC(RawBytecodeHelper.INVOKESTATIC, 3, Kind.INVOKE),
 
-    /** Invoke interface method */
+    /**
+     * Invoke interface method.
+     *
+     * @jvms 6.5.invokeinterface <em>invokeinterface</em>
+     * @see Kind#INVOKE
+     */
     INVOKEINTERFACE(RawBytecodeHelper.INVOKEINTERFACE, 5, Kind.INVOKE),
 
-    /** Invoke a dynamically-computed call site */
+    /**
+     * Invoke a dynamically-computed call site.
+     *
+     * @jvms 6.5.invokedynamic <em>invokedynamic</em>
+     * @see Kind#INVOKE_DYNAMIC
+     */
     INVOKEDYNAMIC(RawBytecodeHelper.INVOKEDYNAMIC, 5, Kind.INVOKE_DYNAMIC),
 
-    /** Create new object */
+    /**
+     * Create new object.
+     *
+     * @jvms 6.5.new <em>new</em>
+     * @see Kind#NEW_OBJECT
+     */
     NEW(RawBytecodeHelper.NEW, 3, Kind.NEW_OBJECT),
 
-    /** Create new array */
+    /**
+     * Create new array.
+     *
+     * @jvms 6.5.newarray <em>newarray</em>
+     * @see Kind#NEW_PRIMITIVE_ARRAY
+     */
     NEWARRAY(RawBytecodeHelper.NEWARRAY, 2, Kind.NEW_PRIMITIVE_ARRAY),
 
-    /** Create new array of reference */
+    /**
+     * Create new array of {@link TypeKind#REFERENCE reference}.
+     *
+     * @jvms 6.5.anewarray <em>anewarray</em>
+     * @see Kind#NEW_REF_ARRAY
+     */
     ANEWARRAY(RawBytecodeHelper.ANEWARRAY, 3, Kind.NEW_REF_ARRAY),
 
-    /** Get length of array */
+    /**
+     * Get length of array.
+     *
+     * @jvms 6.5.arraylength <em>arraylength</em>
+     * @see Kind#OPERATOR
+     */
     ARRAYLENGTH(RawBytecodeHelper.ARRAYLENGTH, 1, Kind.OPERATOR),
 
-    /** Throw exception or error */
+    /**
+     * Throw exception or error.
+     *
+     * @jvms 6.5.athrow <em>athrow</em>
+     * @see Kind#THROW_EXCEPTION
+     */
     ATHROW(RawBytecodeHelper.ATHROW, 1, Kind.THROW_EXCEPTION),
 
-    /** Check whether object is of given type */
+    /**
+     * Check whether object is of given type.
+     *
+     * @see Class#cast(Object)
+     * @jvms 6.5.checkcast <em>checkcast</em>
+     * @see Kind#TYPE_CHECK
+     */
     CHECKCAST(RawBytecodeHelper.CHECKCAST, 3, Kind.TYPE_CHECK),
 
-    /** Determine if object is of given type */
+    /**
+     * Determine if object is of given type.
+     *
+     * @see Class#isInstance(Object)
+     * @jvms 6.5.instanceof <em>instanceof</em>
+     * @see Kind#TYPE_CHECK
+     */
     INSTANCEOF(RawBytecodeHelper.INSTANCEOF, 3, Kind.TYPE_CHECK),
 
-    /** Enter monitor for object */
+    /**
+     * Enter monitor for object.
+     *
+     * @jvms 6.5.monitorenter <em>monitorenter</em>
+     * @see Kind#MONITOR
+     */
     MONITORENTER(RawBytecodeHelper.MONITORENTER, 1, Kind.MONITOR),
 
-    /** Exit monitor for object */
+    /**
+     * Exit monitor for object.
+     *
+     * @jvms 6.5.monitorexit <em>monitorexit</em>
+     * @see Kind#MONITOR
+     */
     MONITOREXIT(RawBytecodeHelper.MONITOREXIT, 1, Kind.MONITOR),
 
-    /** Create new multidimensional array */
+    /**
+     * Create new multidimensional array.
+     *
+     * @jvms 6.5.multianewarray <em>multianewarray</em>
+     * @see Kind#NEW_MULTI_ARRAY
+     */
     MULTIANEWARRAY(RawBytecodeHelper.MULTIANEWARRAY, 4, Kind.NEW_MULTI_ARRAY),
 
-    /** Branch if reference is null */
+    /**
+     * Branch if {@link TypeKind#REFERENCE reference} is {@code null}.
+     *
+     * @jvms 6.5.ifnull <em>ifnull</em>
+     * @see Kind#BRANCH
+     */
     IFNULL(RawBytecodeHelper.IFNULL, 3, Kind.BRANCH),
 
-    /** Branch if reference not null */
+    /**
+     * Branch if {@link TypeKind#REFERENCE reference} is not {@code null}.
+     *
+     * @jvms 6.5.ifnonnull <em>ifnonnull</em>
+     * @see Kind#BRANCH
+     */
     IFNONNULL(RawBytecodeHelper.IFNONNULL, 3, Kind.BRANCH),
 
-    /** Branch always (wide index) */
+    /**
+     * Branch always (wide index).
+     *
+     * @jvms 6.5.goto_w <em>goto_w</em>
+     * @see Kind#BRANCH
+     */
     GOTO_W(RawBytecodeHelper.GOTO_W, 5, Kind.BRANCH),
 
     /**
-     * Jump subroutine (wide index) is discontinued opcode
-     * @see io.github.dmlloyd.classfile.instruction.DiscontinuedInstruction
+     * (Discontinued) Jump subroutine (wide index); last used in major
+     * version {@value ClassFile#JAVA_6_VERSION}.
+     *
+     * @jvms 4.9.1 Static Constraints
+     * @jvms 6.5.jsr_w <em>jsr_w</em>
+     * @see Kind#DISCONTINUED_JSR
      */
     JSR_W(RawBytecodeHelper.JSR_W, 5, Kind.DISCONTINUED_JSR),
 
-    /** Load int from local variable (wide index) */
+    /**
+     * Load {@link TypeKind#INT int} from local variable (wide index).
+     * This is a {@linkplain #isWide() wide}-modified pseudo-opcode.
+     *
+     * @jvms 6.5.wide <em>wide</em>
+     * @jvms 6.5.iload <em>iload</em>
+     * @see Kind#LOAD
+     */
     ILOAD_W((RawBytecodeHelper.WIDE << 8) | RawBytecodeHelper.ILOAD, 4, Kind.LOAD),
 
-    /** Load long from local variable (wide index) */
+    /**
+     * Load {@link TypeKind#LONG long} from local variable (wide index).
+     * This is a {@linkplain #isWide() wide}-modified pseudo-opcode.
+     *
+     * @jvms 6.5.wide <em>wide</em>
+     * @jvms 6.5.lload <em>lload</em>
+     * @see Kind#LOAD
+     */
     LLOAD_W((RawBytecodeHelper.WIDE << 8) | RawBytecodeHelper.LLOAD, 4, Kind.LOAD),
 
-    /** Load float from local variable (wide index) */
+    /**
+     * Load {@link TypeKind#FLOAT float} from local variable (wide index).
+     * This is a {@linkplain #isWide() wide}-modified pseudo-opcode.
+     *
+     * @jvms 6.5.wide <em>wide</em>
+     * @jvms 6.5.fload <em>fload</em>
+     * @see Kind#LOAD
+     */
     FLOAD_W((RawBytecodeHelper.WIDE << 8) | RawBytecodeHelper.FLOAD, 4, Kind.LOAD),
 
-    /** Load double from local variable (wide index) */
+    /**
+     * Load {@link TypeKind#DOUBLE double} from local variable (wide index).
+     * This is a {@linkplain #isWide() wide}-modified pseudo-opcode.
+     *
+     * @jvms 6.5.wide <em>wide</em>
+     * @jvms 6.5.dload <em>dload</em>
+     * @see Kind#LOAD
+     */
     DLOAD_W((RawBytecodeHelper.WIDE << 8) | RawBytecodeHelper.DLOAD, 4, Kind.LOAD),
 
-    /** Load reference from local variable (wide index) */
+    /**
+     * Load {@link TypeKind#REFERENCE reference} from local variable (wide index).
+     * This is a {@linkplain #isWide() wide}-modified pseudo-opcode.
+     *
+     * @jvms 6.5.wide <em>wide</em>
+     * @jvms 6.5.aload <em>aload</em>
+     * @see Kind#LOAD
+     */
     ALOAD_W((RawBytecodeHelper.WIDE << 8) | RawBytecodeHelper.ALOAD, 4, Kind.LOAD),
 
-    /** Store int into local variable (wide index) */
+    /**
+     * Store {@link TypeKind#INT int} into local variable (wide index).
+     * This is a {@linkplain #isWide() wide}-modified pseudo-opcode.
+     *
+     * @jvms 6.5.wide <em>wide</em>
+     * @jvms 6.5.istore <em>istore</em>
+     * @see Kind#STORE
+     */
     ISTORE_W((RawBytecodeHelper.WIDE << 8) | RawBytecodeHelper.ISTORE, 4, Kind.STORE),
 
-    /** Store long into local variable (wide index) */
+    /**
+     * Store {@link TypeKind#LONG long} into local variable (wide index).
+     * This is a {@linkplain #isWide() wide}-modified pseudo-opcode.
+     *
+     * @jvms 6.5.wide <em>wide</em>
+     * @jvms 6.5.lstore <em>lstore</em>
+     * @see Kind#STORE
+     */
     LSTORE_W((RawBytecodeHelper.WIDE << 8) | RawBytecodeHelper.LSTORE, 4, Kind.STORE),
 
-    /** Store float into local variable (wide index) */
+    /**
+     * Store {@link TypeKind#FLOAT float} into local variable (wide index).
+     * This is a {@linkplain #isWide() wide}-modified pseudo-opcode.
+     *
+     * @jvms 6.5.wide <em>wide</em>
+     * @jvms 6.5.fstore <em>fstore</em>
+     * @see Kind#STORE
+     */
     FSTORE_W((RawBytecodeHelper.WIDE << 8) | RawBytecodeHelper.FSTORE, 4, Kind.STORE),
 
-    /** Store double into local variable (wide index) */
+    /**
+     * Store {@link TypeKind#DOUBLE double} into local variable (wide index).
+     * This is a {@linkplain #isWide() wide}-modified pseudo-opcode.
+     *
+     * @jvms 6.5.wide <em>wide</em>
+     * @jvms 6.5.dstore <em>dstore</em>
+     * @see Kind#STORE
+     */
     DSTORE_W((RawBytecodeHelper.WIDE << 8) | RawBytecodeHelper.DSTORE, 4, Kind.STORE),
 
-    /** Store reference into local variable (wide index) */
+    /**
+     * Store {@link TypeKind#REFERENCE reference} into local variable (wide index).
+     * This is a {@linkplain #isWide() wide}-modified pseudo-opcode.
+     * Can also store the {@link TypeKind##returnAddress returnAddress} type.
+     *
+     * @jvms 6.5.wide <em>wide</em>
+     * @jvms 6.5.astore <em>astore</em>
+     * @see Kind#STORE
+     */
     ASTORE_W((RawBytecodeHelper.WIDE << 8) | RawBytecodeHelper.ASTORE, 4, Kind.STORE),
 
     /**
-     * Return from subroutine (wide index) is discontinued opcode
-     * @see io.github.dmlloyd.classfile.instruction.DiscontinuedInstruction
+     * (Discontinued) Return from subroutine (wide index); last used in major
+     * version {@value ClassFile#JAVA_6_VERSION}.
+     * This is a {@linkplain #isWide() wide}-modified pseudo-opcode.
+     *
+     * @jvms 4.9.1 Static Constraints
+     * @jvms 6.5.wide <em>wide</em>
+     * @jvms 6.5.ret <em>ret</em>
+     * @see Kind#DISCONTINUED_RET
      */
     RET_W((RawBytecodeHelper.WIDE << 8) | RawBytecodeHelper.RET, 4, Kind.DISCONTINUED_RET),
 
-    /** Increment local variable by constant (wide index) */
+    /**
+     * Increment local variable by constant (wide index).
+     * This is a {@linkplain #isWide() wide}-modified pseudo-opcode.
+     *
+     * @jvms 6.5.wide <em>wide</em>
+     * @jvms 6.5.iinc <em>iinc</em>
+     * @see Kind#INCREMENT
+     */
     IINC_W((RawBytecodeHelper.WIDE << 8) | RawBytecodeHelper.IINC, 6, Kind.INCREMENT);
 
     /**
-     * Kinds of opcodes.
+     * Kinds of opcodes.  Each kind of opcode has its own modeling interface
+     * for its instructions.
      *
      * @since 24
      */
-    public static enum Kind {
+    public enum Kind {
 
         /**
-         * Load from local variable
+         * Load from local variable.
          *
+         * @see LoadInstruction
          * @see Opcode#ILOAD
          * @see Opcode#LLOAD
          * @see Opcode#FLOAD
@@ -736,8 +1901,9 @@ public static enum Kind {
         LOAD,
 
         /**
-         * Store into local variable
+         * Store into local variable.
          *
+         * @see StoreInstruction
          * @see Opcode#ISTORE
          * @see Opcode#LSTORE
          * @see Opcode#FSTORE
@@ -772,16 +1938,18 @@ public static enum Kind {
         STORE,
 
         /**
-         * Increment local variable
+         * Increment local variable.
          *
+         * @see IncrementInstruction
          * @see Opcode#IINC
          * @see Opcode#IINC_W
          */
         INCREMENT,
 
         /**
-         * Branch
+         * Branch.
          *
+         * @see BranchInstruction
          * @see Opcode#IFEQ
          * @see Opcode#IFNE
          * @see Opcode#IFLT
@@ -804,22 +1972,25 @@ public static enum Kind {
         BRANCH,
 
         /**
-         * Access jump table by key match and jump
+         * Access jump table by key match and jump.
          *
+         * @see LookupSwitchInstruction
          * @see Opcode#LOOKUPSWITCH
          */
         LOOKUP_SWITCH,
 
         /**
-         * Access jump table by index and jump
+         * Access jump table by index and jump.
          *
+         * @see TableSwitchInstruction
          * @see Opcode#TABLESWITCH
          */
         TABLE_SWITCH,
 
         /**
-         * Return from method
+         * Return from method.
          *
+         * @see ReturnInstruction
          * @see Opcode#IRETURN
          * @see Opcode#LRETURN
          * @see Opcode#FRETURN
@@ -830,15 +2001,17 @@ public static enum Kind {
         RETURN,
 
         /**
-         * Throw exception or error
+         * Throw exception or error.
          *
+         * @see ThrowInstruction
          * @see Opcode#ATHROW
          */
         THROW_EXCEPTION,
 
         /**
-         * Access field
+         * Access field.
          *
+         * @see FieldInstruction
          * @see Opcode#GETSTATIC
          * @see Opcode#PUTSTATIC
          * @see Opcode#GETFIELD
@@ -847,8 +2020,9 @@ public static enum Kind {
         FIELD_ACCESS,
 
         /**
-         * Invoke method or constructor
+         * Invoke method or constructor.
          *
+         * @see InvokeInstruction
          * @see Opcode#INVOKEVIRTUAL
          * @see Opcode#INVOKESPECIAL
          * @see Opcode#INVOKESTATIC
@@ -857,51 +2031,58 @@ public static enum Kind {
         INVOKE,
 
         /**
-         * Invoke a dynamically-computed call site
+         * Invoke a dynamically-computed call site.
          *
+         * @see InvokeDynamicInstruction
          * @see Opcode#INVOKEDYNAMIC
          */
         INVOKE_DYNAMIC,
 
         /**
-         * Create new object
+         * Create new object.
          *
+         * @see NewObjectInstruction
          * @see Opcode#NEW
          */
         NEW_OBJECT,
 
         /**
-         * Create new array
+         * Create new array.
          *
+         * @see NewPrimitiveArrayInstruction
          * @see Opcode#NEWARRAY
          */
         NEW_PRIMITIVE_ARRAY,
 
         /**
-         * Create new reference array
+         * Create new {@link TypeKind#REFERENCE reference} array.
          *
+         * @see NewReferenceArrayInstruction
          * @see Opcode#ANEWARRAY
          */
         NEW_REF_ARRAY,
 
         /**
-         * Create new multidimensional array
+         * Create new multidimensional array.
          *
+         * @see NewMultiArrayInstruction
          * @see Opcode#MULTIANEWARRAY
          */
         NEW_MULTI_ARRAY,
 
         /**
-         * Check whether object is of given type
+         * Check whether object is of given type.
          *
+         * @see TypeCheckInstruction
          * @see Opcode#CHECKCAST
          * @see Opcode#INSTANCEOF
          */
         TYPE_CHECK,
 
         /**
-         * Load from array
+         * Load from array.
          *
+         * @see ArrayLoadInstruction
          * @see Opcode#IALOAD
          * @see Opcode#LALOAD
          * @see Opcode#FALOAD
@@ -914,8 +2095,9 @@ public static enum Kind {
         ARRAY_LOAD,
 
         /**
-         * Store into array
+         * Store into array.
          *
+         * @see ArrayStoreInstruction
          * @see Opcode#IASTORE
          * @see Opcode#LASTORE
          * @see Opcode#FASTORE
@@ -928,8 +2110,9 @@ public static enum Kind {
         ARRAY_STORE,
 
         /**
-         * Stack operations
+         * Stack operations.
          *
+         * @see StackInstruction
          * @see Opcode#POP
          * @see Opcode#POP2
          * @see Opcode#DUP
@@ -943,8 +2126,9 @@ public static enum Kind {
         STACK,
 
         /**
-         * Type conversions
+         * Type conversions.
          *
+         * @see ConvertInstruction
          * @see Opcode#I2L
          * @see Opcode#I2F
          * @see Opcode#I2D
@@ -964,8 +2148,9 @@ public static enum Kind {
         CONVERT,
 
         /**
-         * Operators
+         * Operators.
          *
+         * @see OperatorInstruction
          * @see Opcode#IADD
          * @see Opcode#LADD
          * @see Opcode#FADD
@@ -1012,8 +2197,9 @@ public static enum Kind {
         OPERATOR,
 
         /**
-         * Constants
+         * Constants.
          *
+         * @see ConstantInstruction
          * @see Opcode#ACONST_NULL
          * @see Opcode#ICONST_M1
          * @see Opcode#ICONST_0
@@ -1038,35 +2224,37 @@ public static enum Kind {
         CONSTANT,
 
         /**
-         * Monitor
+         * Monitor.
          *
+         * @see MonitorInstruction
          * @see Opcode#MONITORENTER
          * @see Opcode#MONITOREXIT
          */
         MONITOR,
 
         /**
-         * Do nothing
+         * Do nothing.
          *
+         * @see NopInstruction
          * @see Opcode#NOP
          */
         NOP,
 
         /**
-         * Discontinued jump subroutine
+         * Discontinued jump subroutine.
          *
+         * @see DiscontinuedInstruction.JsrInstruction
          * @see Opcode#JSR
          * @see Opcode#JSR_W
-         * @see io.github.dmlloyd.classfile.instruction.DiscontinuedInstruction
          */
         DISCONTINUED_JSR,
 
         /**
-         * Discontinued return from subroutine
+         * Discontinued return from subroutine.
          *
+         * @see DiscontinuedInstruction.RetInstruction
          * @see Opcode#RET
          * @see Opcode#RET_W
-         * @see io.github.dmlloyd.classfile.instruction.DiscontinuedInstruction
          */
         DISCONTINUED_RET;
     }
@@ -1090,7 +2278,10 @@ public static enum Kind {
 
     /**
      * {@return true if this is a pseudo-opcode modified by wide opcode}
+     * <p>
+     * {@code wide} extends local variable index by additional bytes.
      *
+     * @jvms 6.5.wide <em>wide</em>
      * @see #ILOAD_W
      * @see #LLOAD_W
      * @see #FLOAD_W
@@ -1109,11 +2300,14 @@ public static enum Kind {
     /**
      * {@return size of the instruction in bytes if fixed, or -1 otherwise} This size includes
      * the opcode itself.
+     *
+     * @see Instruction#sizeInBytes() Instruction::sizeInBytes
      */
     public int sizeIfFixed() { return sizeIfFixed; }
 
     /**
-     * {@return instruction kind}
+     * {@return operation kind}  Each kind of operation has its own modeling
+     * interface to model instructions belonging to that kind.
      */
     public Kind kind() { return kind; }
 }
diff --git a/src/main/java/io/github/dmlloyd/classfile/TypeKind.java b/src/main/java/io/github/dmlloyd/classfile/TypeKind.java
index 37f20b9..4e7d78f 100644
--- a/src/main/java/io/github/dmlloyd/classfile/TypeKind.java
+++ b/src/main/java/io/github/dmlloyd/classfile/TypeKind.java
@@ -26,6 +26,9 @@
 package io.github.dmlloyd.classfile;
 
 import io.github.dmlloyd.classfile.instruction.DiscontinuedInstruction;
+import io.github.dmlloyd.classfile.instruction.LoadInstruction;
+import io.github.dmlloyd.classfile.instruction.NewPrimitiveArrayInstruction;
+import io.github.dmlloyd.classfile.instruction.StoreInstruction;
 import java.lang.constant.ClassDesc;
 import java.lang.constant.ConstantDescs;
 import java.lang.invoke.TypeDescriptor;
@@ -33,13 +36,17 @@
 //import jdk.internal.vm.annotation.Stable;
 
 /**
- * Describes the data types Java Virtual Machine operates on.
- * This omits {@code returnAddress} (JVMS {@jvms 2.3.3}),
- * which is only used by discontinued {@link
- * DiscontinuedInstruction.JsrInstruction jsr} and {@link
- * DiscontinuedInstruction.RetInstruction ret} instructions,
- * and includes {@link #VOID void} (JVMS {@jvms 4.3.3}), which
- * appears as a method return type.
+ * Describes the data types Java Virtual Machine operates on.  This omits {@code
+ * returnAddress} (JVMS {@jvms 2.3.3}) and includes {@link #VOID void} (JVMS
+ * {@jvms 4.3.3}), which appears as a method return type.
+ * <p>
+ * The <code>{@index returnAddress}</code> type is only used by discontinued
+ * {@linkplain DiscontinuedInstruction.JsrInstruction jump subroutine} and
+ * {@linkplain DiscontinuedInstruction.RetInstruction return from subroutine}
+ * instructions.  Jump subroutine instructions push {@code returnAddress} to the
+ * operand stack; {@link StoreInstruction astore} instructions store {@code
+ * returnAddress} from the operand stack to local variables; return from
+ * subroutine instructions load {@code returnAddress} from local variables.
  *
  * <h2 id="computational-type">Computational Type</h2>
  * In the {@code class} file format, local variables (JVMS {@jvms 2.6.1}),
@@ -164,7 +171,10 @@ private ClassDesc fetchUpperBound() {
     /**
      * {@return the code used by the {@link Opcode#NEWARRAY newarray} instruction to create an array
      * of this component type, or {@code -1} if this type is not supported by {@code newarray}}
-     * @jvms 6.5.newarray <i>newarray</i>
+     *
+     * @jvms 6.5.newarray <em>newarray</em>
+     * @see NewPrimitiveArrayInstruction
+     * @see #fromNewarrayCode(int) fromNewarrayCode(int)
      */
     public int newarrayCode() {
         return newarrayCode;
@@ -175,6 +185,7 @@ public int newarrayCode() {
      * This is also the category of this type for instructions operating on the operand stack without
      * regard to type (JVMS {@jvms 2.11.1}), such as {@link Opcode#POP pop} versus {@link Opcode#POP2
      * pop2}.
+     *
      * @jvms 2.6.1 Local Variables
      * @jvms 2.6.2 Operand Stacks
      */
@@ -185,6 +196,9 @@ public int slotSize() {
     /**
      * {@return the {@linkplain ##computational-type computational type} for this type, or {@link #VOID void}
      * for {@code void}}
+     *
+     * @see LoadInstruction
+     * @see StoreInstruction
      */
     public TypeKind asLoadable() {
         return ordinal() < 4 ? INT : this;
@@ -193,9 +207,12 @@ public TypeKind asLoadable() {
     /**
      * {@return the component type described by the array code used as an operand to {@link Opcode#NEWARRAY
      * newarray}}
+     *
      * @param newarrayCode the operand of the {@code newarray} instruction
      * @throws IllegalArgumentException if the code is invalid
-     * @jvms 6.5.newarray <i>newarray</i>
+     * @jvms 6.5.newarray <em>newarray</em>
+     * @see NewPrimitiveArrayInstruction
+     * @see #newarrayCode() newarrayCode()
      */
     public static TypeKind fromNewarrayCode(int newarrayCode) {
         return switch (newarrayCode) {
diff --git a/src/main/java/io/github/dmlloyd/classfile/extras/constant/ModuleDesc.java b/src/main/java/io/github/dmlloyd/classfile/extras/constant/ModuleDesc.java
index 85e4e64..3a4ec64 100644
--- a/src/main/java/io/github/dmlloyd/classfile/extras/constant/ModuleDesc.java
+++ b/src/main/java/io/github/dmlloyd/classfile/extras/constant/ModuleDesc.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2023, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2023, 2024, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
diff --git a/src/main/java/io/github/dmlloyd/classfile/impl/AccessFlagsImpl.java b/src/main/java/io/github/dmlloyd/classfile/impl/AccessFlagsImpl.java
index 23b1cd6..58847af 100644
--- a/src/main/java/io/github/dmlloyd/classfile/impl/AccessFlagsImpl.java
+++ b/src/main/java/io/github/dmlloyd/classfile/impl/AccessFlagsImpl.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2022, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2022, 2024, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
diff --git a/src/main/java/io/github/dmlloyd/classfile/impl/BoundLocalVariable.java b/src/main/java/io/github/dmlloyd/classfile/impl/BoundLocalVariable.java
index 0c02d74..06a6d4b 100644
--- a/src/main/java/io/github/dmlloyd/classfile/impl/BoundLocalVariable.java
+++ b/src/main/java/io/github/dmlloyd/classfile/impl/BoundLocalVariable.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2022, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2022, 2024, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
diff --git a/src/main/java/io/github/dmlloyd/classfile/impl/CatchBuilderImpl.java b/src/main/java/io/github/dmlloyd/classfile/impl/CatchBuilderImpl.java
index 3c77398..e1d2dff 100644
--- a/src/main/java/io/github/dmlloyd/classfile/impl/CatchBuilderImpl.java
+++ b/src/main/java/io/github/dmlloyd/classfile/impl/CatchBuilderImpl.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2022, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2022, 2024, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
diff --git a/src/main/java/io/github/dmlloyd/classfile/impl/EntryMap.java b/src/main/java/io/github/dmlloyd/classfile/impl/EntryMap.java
index c3600d2..77a50f0 100644
--- a/src/main/java/io/github/dmlloyd/classfile/impl/EntryMap.java
+++ b/src/main/java/io/github/dmlloyd/classfile/impl/EntryMap.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2022, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2022, 2024, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
diff --git a/src/main/java/io/github/dmlloyd/classfile/impl/InterfacesImpl.java b/src/main/java/io/github/dmlloyd/classfile/impl/InterfacesImpl.java
index b833994..f232dd6 100644
--- a/src/main/java/io/github/dmlloyd/classfile/impl/InterfacesImpl.java
+++ b/src/main/java/io/github/dmlloyd/classfile/impl/InterfacesImpl.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2022, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2022, 2024, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
diff --git a/src/main/java/io/github/dmlloyd/classfile/impl/LabelImpl.java b/src/main/java/io/github/dmlloyd/classfile/impl/LabelImpl.java
index ab37e9a..2b6b570 100644
--- a/src/main/java/io/github/dmlloyd/classfile/impl/LabelImpl.java
+++ b/src/main/java/io/github/dmlloyd/classfile/impl/LabelImpl.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2022, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2022, 2024, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
diff --git a/src/main/java/io/github/dmlloyd/classfile/impl/SuperclassImpl.java b/src/main/java/io/github/dmlloyd/classfile/impl/SuperclassImpl.java
index ec6bae8..f01930c 100644
--- a/src/main/java/io/github/dmlloyd/classfile/impl/SuperclassImpl.java
+++ b/src/main/java/io/github/dmlloyd/classfile/impl/SuperclassImpl.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2022, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2022, 2024, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
diff --git a/src/main/java/io/github/dmlloyd/classfile/impl/verifier/VerificationBytecodes.java b/src/main/java/io/github/dmlloyd/classfile/impl/verifier/VerificationBytecodes.java
index 54a6fd4..a35063d 100644
--- a/src/main/java/io/github/dmlloyd/classfile/impl/verifier/VerificationBytecodes.java
+++ b/src/main/java/io/github/dmlloyd/classfile/impl/verifier/VerificationBytecodes.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2022, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2022, 2024, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
diff --git a/src/main/java/io/github/dmlloyd/classfile/impl/verifier/VerificationTable.java b/src/main/java/io/github/dmlloyd/classfile/impl/verifier/VerificationTable.java
index 45a93d9..7a679e7 100644
--- a/src/main/java/io/github/dmlloyd/classfile/impl/verifier/VerificationTable.java
+++ b/src/main/java/io/github/dmlloyd/classfile/impl/verifier/VerificationTable.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2022, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2022, 2024, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
diff --git a/src/main/java/io/github/dmlloyd/classfile/impl/verifier/VerificationType.java b/src/main/java/io/github/dmlloyd/classfile/impl/verifier/VerificationType.java
index 9b95ff6..d504e96 100644
--- a/src/main/java/io/github/dmlloyd/classfile/impl/verifier/VerificationType.java
+++ b/src/main/java/io/github/dmlloyd/classfile/impl/verifier/VerificationType.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2022, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2022, 2024, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
diff --git a/src/main/java/io/github/dmlloyd/classfile/instruction/ArrayLoadInstruction.java b/src/main/java/io/github/dmlloyd/classfile/instruction/ArrayLoadInstruction.java
index b8260a7..3dac4a8 100644
--- a/src/main/java/io/github/dmlloyd/classfile/instruction/ArrayLoadInstruction.java
+++ b/src/main/java/io/github/dmlloyd/classfile/instruction/ArrayLoadInstruction.java
@@ -24,6 +24,7 @@
  */
 package io.github.dmlloyd.classfile.instruction;
 
+import io.github.dmlloyd.classfile.CodeBuilder;
 import io.github.dmlloyd.classfile.CodeElement;
 import io.github.dmlloyd.classfile.CodeModel;
 import io.github.dmlloyd.classfile.Instruction;
@@ -35,18 +36,29 @@
 
 /**
  * Models an array load instruction in the {@code code} array of a {@code Code}
- * attribute.  Corresponding opcodes will have a {@code kind} of {@link
- * Opcode.Kind#ARRAY_LOAD}.  Delivered as a {@link CodeElement} when
+ * attribute.  Corresponding opcodes have a {@linkplain Opcode#kind() kind}
+ * of {@link Opcode.Kind#ARRAY_LOAD}.  Delivered as a {@link CodeElement} when
  * traversing the elements of a {@link CodeModel}.
+ * <p>
+ * An array load instruction is composite:
+ * {@snippet lang=text :
+ * // @link substring="ArrayLoadInstruction" target="CodeBuilder#arrayLoad(TypeKind)" :
+ * ArrayLoadInstruction(TypeKind typeKind) // @link substring="typeKind" target="#typeKind"
+ * }
+ * where {@code typeKind} is not {@link TypeKind#VOID void}, and {@link
+ * TypeKind#BOOLEAN boolean} is converted to {@link TypeKind#BYTE byte}.
  *
+ * @see Opcode.Kind#ARRAY_LOAD
+ * @see CodeBuilder#arrayLoad CodeBuilder::arrayLoad
  * @since 24
  */
 public sealed interface ArrayLoadInstruction extends Instruction
         permits AbstractInstruction.UnboundArrayLoadInstruction {
     /**
-     * {@return the component type of the array} The {@link TypeKind#BYTE byte}
+     * {@return the component type of the array}  The {@link TypeKind#BYTE byte}
      * type load instruction {@link Opcode#BALOAD baload} also operates on
-     * {@link TypeKind#BOOLEAN boolean} arrays.
+     * {@link TypeKind#BOOLEAN boolean} arrays, so this never returns
+     * {@code boolean}.
      */
     TypeKind typeKind();
 
@@ -56,7 +68,7 @@ public sealed interface ArrayLoadInstruction extends Instruction
      * @param op the opcode for the specific type of array load instruction,
      *           which must be of kind {@link Opcode.Kind#ARRAY_LOAD}
      * @throws IllegalArgumentException if the opcode kind is not
-     *         {@link Opcode.Kind#ARRAY_LOAD}.
+     *         {@link Opcode.Kind#ARRAY_LOAD}
      */
     static ArrayLoadInstruction of(Opcode op) {
         Util.checkKind(op, Opcode.Kind.ARRAY_LOAD);
diff --git a/src/main/java/io/github/dmlloyd/classfile/instruction/ArrayStoreInstruction.java b/src/main/java/io/github/dmlloyd/classfile/instruction/ArrayStoreInstruction.java
index 417904d..7f94477 100644
--- a/src/main/java/io/github/dmlloyd/classfile/instruction/ArrayStoreInstruction.java
+++ b/src/main/java/io/github/dmlloyd/classfile/instruction/ArrayStoreInstruction.java
@@ -24,6 +24,7 @@
  */
 package io.github.dmlloyd.classfile.instruction;
 
+import io.github.dmlloyd.classfile.CodeBuilder;
 import io.github.dmlloyd.classfile.CodeElement;
 import io.github.dmlloyd.classfile.CodeModel;
 import io.github.dmlloyd.classfile.Instruction;
@@ -35,18 +36,29 @@
 
 /**
  * Models an array store instruction in the {@code code} array of a {@code Code}
- * attribute.  Corresponding opcodes will have a {@code kind} of {@link
- * Opcode.Kind#ARRAY_STORE}.  Delivered as a {@link CodeElement} when
+ * attribute.  Corresponding opcodes have a {@linkplain Opcode#kind() kind}
+ * of {@link Opcode.Kind#ARRAY_STORE}.  Delivered as a {@link CodeElement} when
  * traversing the elements of a {@link CodeModel}.
+ * <p>
+ * An array store instruction is composite:
+ * {@snippet lang=text :
+ * // @link substring="ArrayStoreInstruction" target="CodeBuilder#arrayStore(TypeKind)" :
+ * ArrayStoreInstruction(TypeKind typeKind) // @link substring="typeKind" target="#typeKind"
+ * }
+ * where {@code typeKind} is not {@link TypeKind#VOID void}, and {@link
+ * TypeKind#BOOLEAN boolean} is converted to {@link TypeKind#BYTE byte}.
  *
+ * @see Opcode.Kind#ARRAY_STORE
+ * @see CodeBuilder#arrayStore CodeBuilder::arrayStore
  * @since 24
  */
 public sealed interface ArrayStoreInstruction extends Instruction
         permits AbstractInstruction.UnboundArrayStoreInstruction {
     /**
-     * {@return the component type of the array} The {@link TypeKind#BYTE byte}
+     * {@return the component type of the array}  The {@link TypeKind#BYTE byte}
      * type store instruction {@link Opcode#BASTORE bastore} also operates on
-     * {@link TypeKind#BOOLEAN boolean} arrays.
+     * {@link TypeKind#BOOLEAN boolean} arrays, so this never returns
+     * {@code boolean}.
      */
     TypeKind typeKind();
 
@@ -56,7 +68,7 @@ public sealed interface ArrayStoreInstruction extends Instruction
      * @param op the opcode for the specific type of array store instruction,
      *           which must be of kind {@link Opcode.Kind#ARRAY_STORE}
      * @throws IllegalArgumentException if the opcode kind is not
-     *         {@link Opcode.Kind#ARRAY_STORE}.
+     *         {@link Opcode.Kind#ARRAY_STORE}
      */
     static ArrayStoreInstruction of(Opcode op) {
         Util.checkKind(op, Opcode.Kind.ARRAY_STORE);
diff --git a/src/main/java/io/github/dmlloyd/classfile/instruction/BranchInstruction.java b/src/main/java/io/github/dmlloyd/classfile/instruction/BranchInstruction.java
index c873842..afb509f 100644
--- a/src/main/java/io/github/dmlloyd/classfile/instruction/BranchInstruction.java
+++ b/src/main/java/io/github/dmlloyd/classfile/instruction/BranchInstruction.java
@@ -24,28 +24,41 @@
  */
 package io.github.dmlloyd.classfile.instruction;
 
-import io.github.dmlloyd.classfile.CodeElement;
-import io.github.dmlloyd.classfile.CodeModel;
-import io.github.dmlloyd.classfile.Instruction;
-import io.github.dmlloyd.classfile.Label;
-import io.github.dmlloyd.classfile.Opcode;
+import io.github.dmlloyd.classfile.*;
 
 import io.github.dmlloyd.classfile.impl.AbstractInstruction;
 import io.github.dmlloyd.classfile.impl.Util;
 
 /**
  * Models a branching instruction (conditional or unconditional) in the {@code
- * code} array of a {@code Code} attribute.  Corresponding opcodes will have a
- * {@code kind} of {@link Opcode.Kind#BRANCH}.  Delivered as a {@link
- * CodeElement} when traversing the elements of a {@link CodeModel}.
+ * code} array of a {@code Code} attribute.  Corresponding opcodes have a
+ * {@linkplain Opcode#kind() kind} of {@link Opcode.Kind#BRANCH}.  Delivered as
+ * a {@link CodeElement} when traversing the elements of a {@link CodeModel}.
+ * <p>
+ * A branch instruction is composite:
+ * {@snippet lang=text :
+ * // @link substring="BranchInstruction" target="#of":
+ * BranchInstruction(
+ *     Opcode opcode, // @link substring="opcode" target="#opcode()"
+ *     Label target // @link substring="target" target="#target()"
+ * )
+ * }
+ * <p>
+ * Due to physical restrictions, some types of instructions cannot encode labels
+ * too far away in the list of code elements.  In such cases, the {@link
+ * ClassFile.ShortJumpsOption} controls how an invalid branch instruction model
+ * is written by a {@link CodeBuilder}.
  *
+ * @see Opcode.Kind#BRANCH
+ * @see CodeBuilder#branch CodeBuilder::branch
+ * @see ClassFile.ShortJumpsOption
  * @since 24
  */
 public sealed interface BranchInstruction extends Instruction
         permits AbstractInstruction.BoundBranchInstruction,
                 AbstractInstruction.UnboundBranchInstruction {
     /**
-     * {@return the target of the branch}
+     * {@return the branch target of this instruction}
      */
     Label target();
 
@@ -56,7 +69,7 @@ public sealed interface BranchInstruction extends Instruction
      *           which must be of kind {@link Opcode.Kind#BRANCH}
      * @param target the target of the branch
      * @throws IllegalArgumentException if the opcode kind is not
-     *         {@link Opcode.Kind#BRANCH}.
+     *         {@link Opcode.Kind#BRANCH}
      */
     static BranchInstruction of(Opcode op, Label target) {
         Util.checkKind(op, Opcode.Kind.BRANCH);
diff --git a/src/main/java/io/github/dmlloyd/classfile/instruction/CharacterRange.java b/src/main/java/io/github/dmlloyd/classfile/instruction/CharacterRange.java
index 7202752..d4f55b2 100644
--- a/src/main/java/io/github/dmlloyd/classfile/instruction/CharacterRange.java
+++ b/src/main/java/io/github/dmlloyd/classfile/instruction/CharacterRange.java
@@ -25,6 +25,7 @@
 package io.github.dmlloyd.classfile.instruction;
 
 import io.github.dmlloyd.classfile.ClassFile;
+import io.github.dmlloyd.classfile.CodeBuilder;
 import io.github.dmlloyd.classfile.CodeElement;
 import io.github.dmlloyd.classfile.CodeModel;
 import io.github.dmlloyd.classfile.Label;
@@ -36,11 +37,31 @@
 import io.github.dmlloyd.classfile.impl.BoundCharacterRange;
 
 /**
- * A pseudo-instruction which models a single entry in the
- * {@link CharacterRangeTableAttribute}.  Delivered as a {@link CodeElement}
- * during traversal of the elements of a {@link CodeModel}, according to
- * the setting of the {@link ClassFile.DebugElementsOption} option.
+ * A pseudo-instruction which models a single entry in the {@link
+ * CharacterRangeTableAttribute CharacterRangeTable} attribute.  Delivered as a
+ * {@link CodeElement} during traversal of the elements of a {@link CodeModel},
+ * according to the setting of the {@link ClassFile.DebugElementsOption} option.
+ * <p>
+ * A character range entry is composite:
+ * {@snippet lang=text :
+ * // @link substring="CharacterRange" target="#of":
+ * CharacterRange(
+ *     Label startScope, // @link substring="startScope" target="#startScope"
+ *     Label endScope, // @link substring="endScope" target="#endScope"
+ *     int characterRangeStart, // @link substring="characterRangeStart" target="#characterRangeStart"
+ *     int characterRangeEnd, // @link substring="characterRangeEnd" target="#characterRangeEnd"
+ *     int flags // @link substring="flags" target="#flags"
+ * )
+ * }
+ * <p>
+ * Another model, {@link CharacterRangeInfo}, also models a character range
+ * entry;  it has no dependency on a {@code CodeModel} and represents of bci
+ * values as {@code int}s instead of {@code Label}s, and is used as components
+ * of a {@link CharacterRangeTableAttribute}.
  *
+ * @see CharacterRangeInfo
+ * @see CodeBuilder#characterRange CodeBuilder::characterRange
+ * @see ClassFile.DebugElementsOption
  * @since 24
  */
 public sealed interface CharacterRange extends PseudoInstruction
diff --git a/src/main/java/io/github/dmlloyd/classfile/instruction/ConstantInstruction.java b/src/main/java/io/github/dmlloyd/classfile/instruction/ConstantInstruction.java
index 2af38b3..e69d7a0 100644
--- a/src/main/java/io/github/dmlloyd/classfile/instruction/ConstantInstruction.java
+++ b/src/main/java/io/github/dmlloyd/classfile/instruction/ConstantInstruction.java
@@ -24,6 +24,7 @@
  */
 package io.github.dmlloyd.classfile.instruction;
 
+import io.github.dmlloyd.classfile.CodeBuilder;
 import io.github.dmlloyd.classfile.CodeElement;
 import io.github.dmlloyd.classfile.CodeModel;
 import io.github.dmlloyd.classfile.Instruction;
@@ -38,12 +39,22 @@
 
 /**
  * Models a constant-load instruction in the {@code code} array of a {@code
- * Code} attribute, including "intrinsic constant" instructions (e.g., {@code
- * iconst_0}), "argument constant" instructions (e.g., {@code bipush}), and "load
- * constant" instructions (e.g., {@code LDC}).  Corresponding opcodes will have
- * a {@code kind} of {@link Opcode.Kind#CONSTANT}.  Delivered as a {@link
- * CodeElement} when traversing the elements of a {@link CodeModel}.
+ * Code} attribute, including {@linkplain IntrinsicConstantInstruction
+ * "intrinsic"}, {@linkplain ArgumentConstantInstruction "argument"}, and
+ * {@linkplain LoadConstantInstruction "load"} constant instructions.
+ * Corresponding opcodes have a {@linkplain Opcode#kind() kind} of {@link
+ * Opcode.Kind#CONSTANT}.  Delivered as a {@link CodeElement} when traversing
+ * the elements of a {@link CodeModel}.
+ * <p>
+ * The loaded constant value is symbolically represented as a {@link ConstantDesc}:
+ * {@snippet lang=text :
+ * // @link substring="ConstantInstruction" target="CodeBuilder#loadConstant(ConstantDesc)" :
+ * ConstantInstruction(ConstantDesc constantValue) // @link substring="constantValue" target="#constantValue()"
+ * }
  *
+ * @see Opcode.Kind#CONSTANT
+ * @see CodeBuilder#loadConstant(ConstantDesc) CodeBuilder::loadConstant
+ * @sealedGraph
  * @since 24
  */
 public sealed interface ConstantInstruction extends Instruction {
@@ -54,22 +65,36 @@ public sealed interface ConstantInstruction extends Instruction {
     ConstantDesc constantValue();
 
     /**
-     * {@return the type of the constant}
+     * {@return the {@linkplain TypeKind##computational-type computational type} of the constant}
+     * This is derived from the {@link #constantValue() constantValue}.
      */
     TypeKind typeKind();
 
     /**
-     * Models an "intrinsic constant" instruction (e.g., {@code
-     * iconst_0}).
+     * Models an "intrinsic constant" instruction, which encodes
+     * the constant value in its opcode. Examples include {@link
+     * Opcode#ACONST_NULL aconst_null} and {@link
+     * Opcode#ICONST_0 iconst_0}.
+     * <p>
+     * An intrinsic constant instruction is composite:
+     * {@snippet lang=text :
+     * // @link substring="IntrinsicConstantInstruction" target="#ofIntrinsic" :
+     * IntrinsicConstantInstruction(Opcode opcode) // @link substring="opcode" target="#opcode()"
+     * }
+     * where:
+     * <dl>
+     * <dt>{@link #opcode() opcode}</dt>
+     * <dd>Must be of the constant kind and have a {@linkplain
+     * Opcode#sizeIfFixed() fixed size} of 1.</dd>
+     * </dl>
      *
+     * @see Opcode.Kind#CONSTANT
+     * @see ConstantInstruction#ofIntrinsic ConstantInstruction::ofIntrinsic
      * @since 24
      */
     sealed interface IntrinsicConstantInstruction extends ConstantInstruction
             permits AbstractInstruction.UnboundIntrinsicConstantInstruction {
 
-        /**
-         * {@return the type of the constant}
-         */
         @Override
         default TypeKind typeKind() {
             return BytecodeHelpers.intrinsicConstantType(opcode());
@@ -77,9 +102,31 @@ default TypeKind typeKind() {
     }
 
     /**
-     * Models an "argument constant" instruction (e.g., {@code
-     * bipush}).
+     * Models an "argument constant" instruction, which encodes the
+     * constant value in the instruction directly. Includes {@link
+     * Opcode#BIPUSH bipush} and {@link Opcode#SIPUSH sipush} instructions.
+     * <p>
+     * An argument constant instruction is composite:
+     * {@snippet lang=text :
+     * // @link substring="ArgumentConstantInstruction" target="#ofArgument" :
+     * ArgumentConstantInstruction(
+     *     Opcode opcode, // @link substring="opcode" target="#opcode()"
+     *     int constantValue // @link substring="constantValue" target="#constantValue()"
+     * )
+     * }
+     * where:
+     * <ul>
+     * <li>{@code opcode} must be one of {@code bipush} or {@code sipush}.
+     * <li>{@code constantValue} must be in the range of {@code byte}, {@code
+     * [-128, 127]}, for {@code bipush},  and in the range of {@code short},
+     * {@code [-32768, 32767]}, for {@code sipush}.
+     * </ul>
      *
+     * @see Opcode.Kind#CONSTANT
+     * @see ConstantInstruction#ofArgument ConstantInstruction::ofArgument
+     * @see CodeBuilder#loadConstant(int) CodeBuilder::loadConstant(int)
+     * @see CodeBuilder#bipush CodeBuilder::bipush
+     * @see CodeBuilder#sipush CodeBuilder::sipush
      * @since 24
      */
     sealed interface ArgumentConstantInstruction extends ConstantInstruction
@@ -89,9 +136,6 @@ sealed interface ArgumentConstantInstruction extends ConstantInstruction
         @Override
         Integer constantValue();
 
-        /**
-         * {@return the type of the constant}
-         */
         @Override
         default TypeKind typeKind() {
             return TypeKind.INT;
@@ -99,9 +143,24 @@ default TypeKind typeKind() {
     }
 
     /**
-     * Models a "load constant" instruction (e.g., {@code
-     * ldc}).
+     * Models a "load constant" instruction, which encodes the constant value
+     * in the constant pool.  Includes {@link Opcode#LDC ldc} and {@link
+     * Opcode#LDC_W ldc_w}, and {@link Opcode#LDC2_W ldc2_w} instructions.
+     * <p>
+     * A load constant instruction is composite:
+     * {@snippet lang=text :
+     * // @link substring="LoadConstantInstruction" target="CodeBuilder#ldc(LoadableConstantEntry)" :
+     * LoadConstantInstruction(LoadableConstantEntry constantEntry) // @link substring="constantEntry" target="#constantEntry()"
+     * }
+     * <p>
+     * A "load constant" instruction can load any constant value supported by
+     * other constant-load instructions.  However, other instructions are
+     * usually more optimized, avoiding extra constant pool entries and being
+     * smaller.
      *
+     * @see Opcode.Kind#CONSTANT
+     * @see ConstantInstruction#ofLoad ConstantInstruction::ofLoad
+     * @see CodeBuilder#ldc CodeBuilder::ldc
      * @since 24
      */
     sealed interface LoadConstantInstruction extends ConstantInstruction
@@ -113,9 +172,6 @@ sealed interface LoadConstantInstruction extends ConstantInstruction
          */
         LoadableConstantEntry constantEntry();
 
-        /**
-         * {@return the type of the constant}
-         */
         @Override
         default TypeKind typeKind() {
             return constantEntry().typeKind();
@@ -139,6 +195,10 @@ static IntrinsicConstantInstruction ofIntrinsic(Opcode op) {
 
     /**
      * {@return an argument constant instruction}
+     * <p>
+     * {@code value} must be in the range of {@code byte}, {@code [-128, 127]},
+     * for {@link Opcode#BIPUSH}, and in the range of {@code short}, {@code
+     * [-32768, 32767]}, for {@link Opcode#SIPUSH}.
      *
      * @param op the opcode for the specific type of argument constant instruction,
      *           which must be {@link Opcode#BIPUSH} or {@link Opcode#SIPUSH}
diff --git a/src/main/java/io/github/dmlloyd/classfile/instruction/ConvertInstruction.java b/src/main/java/io/github/dmlloyd/classfile/instruction/ConvertInstruction.java
index 47b6353..4fae653 100644
--- a/src/main/java/io/github/dmlloyd/classfile/instruction/ConvertInstruction.java
+++ b/src/main/java/io/github/dmlloyd/classfile/instruction/ConvertInstruction.java
@@ -24,6 +24,7 @@
  */
 package io.github.dmlloyd.classfile.instruction;
 
+import io.github.dmlloyd.classfile.CodeBuilder;
 import io.github.dmlloyd.classfile.CodeElement;
 import io.github.dmlloyd.classfile.CodeModel;
 import io.github.dmlloyd.classfile.Instruction;
@@ -36,10 +37,27 @@
 
 /**
  * Models a primitive conversion instruction in the {@code code} array of a
- * {@code Code} attribute, such as {@code i2l}.  Corresponding opcodes will have
- * a {@code kind} of {@link Opcode.Kind#CONVERT}.  Delivered as a {@link
- * CodeElement} when traversing the elements of a {@link CodeModel}.
+ * {@code Code} attribute, such as {@link Opcode#I2L i2l}.  Corresponding opcodes
+ * have a {@linkplain Opcode#kind() kind} of {@link Opcode.Kind#CONVERT}.
+ * Delivered as a {@link CodeElement} when traversing the elements of a {@link CodeModel}.
+ * <p>
+ * A primitive conversion instruction is composite:
+ * {@snippet lang=text :
+ * // @link substring="ConvertInstruction" target="#of(TypeKind, TypeKind)" :
+ * ConvertInstruction(
+ *     TypeKind fromType, // @link substring="fromType" target="#fromType"
+ *     TypeKind toType // @link substring="toType" target="#toType"
+ * )
+ * }
+ * where these conversions are valid:
+ * <ul>
+ * <li>Between {@code int}, {@code long}, {@code float}, and {@code double}, where
+ * {@code fromType != toType};
+ * <li>From {@code int} to {@code byte}, {@code char}, and {@code short}.
+ * </ul>
  *
+ * @see Opcode.Kind#CONVERT
+ * @see CodeBuilder#conversion CodeBuilder::conversion
  * @since 24
  */
 public sealed interface ConvertInstruction extends Instruction
@@ -55,10 +73,16 @@ public sealed interface ConvertInstruction extends Instruction
     TypeKind toType();
 
     /**
-     * {@return A conversion instruction}
+     * {@return a conversion instruction}  Valid conversions are:
+     * <ul>
+     * <li>Between {@code int}, {@code long}, {@code float}, and {@code double},
+     * where {@code fromType != toType};
+     * <li>From {@code int} to {@code byte}, {@code char}, and {@code short}.
+     * </ul>
      *
      * @param fromType the type to convert from
      * @param toType the type to convert to
+     * @throws IllegalArgumentException if this is not a valid conversion
      */
     static ConvertInstruction of(TypeKind fromType, TypeKind toType) {
         return of(BytecodeHelpers.convertOpcode(fromType, toType));
diff --git a/src/main/java/io/github/dmlloyd/classfile/instruction/DiscontinuedInstruction.java b/src/main/java/io/github/dmlloyd/classfile/instruction/DiscontinuedInstruction.java
index 352df38..56903d5 100644
--- a/src/main/java/io/github/dmlloyd/classfile/instruction/DiscontinuedInstruction.java
+++ b/src/main/java/io/github/dmlloyd/classfile/instruction/DiscontinuedInstruction.java
@@ -24,32 +24,54 @@
  */
 package io.github.dmlloyd.classfile.instruction;
 
-import io.github.dmlloyd.classfile.CodeElement;
-import io.github.dmlloyd.classfile.CodeModel;
-import io.github.dmlloyd.classfile.Instruction;
-import io.github.dmlloyd.classfile.Label;
-import io.github.dmlloyd.classfile.Opcode;
+import io.github.dmlloyd.classfile.*;
 
 import io.github.dmlloyd.classfile.impl.AbstractInstruction;
 import io.github.dmlloyd.classfile.impl.BytecodeHelpers;
 import io.github.dmlloyd.classfile.impl.Util;
 
 /**
- * Models instruction discontinued from the {@code code} array of a {@code Code}
- * attribute. Delivered as a {@link CodeElement} when traversing the elements of
- * a {@link CodeModel}.
+ * Marker interface for instruction discontinued from the {@code code} array of
+ * a {@code Code} attribute.  Delivered as a {@link CodeElement} when traversing
+ * the elements of a {@link CodeModel}.
  *
+ * @apiNote
+ * While most instructions have convenience factory methods in {@link
+ * CodeBuilder}, discontinued instructions can only be supplied to code builders
+ * explicitly with {@link CodeBuilder#with CodeBuilder::with} to discourage
+ * their use.
+ *
+ * @jvms 4.9.1 Static Constraints
+ * @sealedGraph
  * @since 24
  */
 public sealed interface DiscontinuedInstruction extends Instruction {
 
     /**
-     * Models JSR and JSR_W instructions discontinued from the {@code code}
-     * array of a {@code Code} attribute since class file version 51.0.
-     * Corresponding opcodes will have a {@code kind} of
-     * {@link Opcode.Kind#DISCONTINUED_JSR}.  Delivered as a {@link CodeElement}
-     * when traversing the elements of a {@link CodeModel}.
+     * Models jump subroutine instructions discontinued from the {@code code}
+     * array of a {@code Code} attribute since class file major version {@value
+     * ClassFile#JAVA_7_VERSION} (JVMS {@jvms 4.9.1}).  Corresponding opcodes
+     * have a {@linkplain Opcode#kind() kind} of {@link Opcode.Kind#DISCONTINUED_JSR}.
+     * Delivered as a {@link CodeElement} when traversing the elements of a
+     * {@link CodeModel}.
+     * <p>
+     * A jump subroutine instruction is composite:
+     * {@snippet lang=text :
+     * // @link substring="JsrInstruction" target="#of(Label)" :
+     * JsrInstruction(Label target) // @link substring="target" target="#target()"
+     * }
+     * <p>
+     * Due to physical restrictions, {@link Opcode#JSR jsr} instructions cannot
+     * encode labels too far away in the list of code elements.  In such cases,
+     * the {@link ClassFile.ShortJumpsOption} controls how an invalid {@code jsr}
+     * instruction model is written by a {@link CodeBuilder}.
+     * <p>
+     * Jump subroutine instructions push a {@link TypeKind##returnAddress
+     * returnAddress} value to the operand stack, and {@link StoreInstruction
+     * astore} series of instructions can then store this value to a local
+     * variable slot.
      *
+     * @see Opcode.Kind#DISCONTINUED_JSR
      * @since 24
      */
     sealed interface JsrInstruction extends DiscontinuedInstruction
@@ -57,14 +79,18 @@ sealed interface JsrInstruction extends DiscontinuedInstruction
                     AbstractInstruction.UnboundJsrInstruction {
 
         /**
-         * {@return the target of the JSR instruction}
+         * {@return the target of the jump subroutine instruction}
          */
         Label target();
 
         /**
-         * {@return a JSR instruction}
+         * {@return a jump subroutine instruction}
          *
-         * @param op the opcode for the specific type of JSR instruction,
+         * @apiNote
+         * The explicit {@code op} argument allows creating {@link Opcode#JSR_W
+         * jsr_w} instructions to avoid short jumps.
+         *
+         * @param op the opcode for the specific type of jump subroutine instruction,
          *           which must be of kind {@link Opcode.Kind#DISCONTINUED_JSR}
          * @param target target label of the subroutine
          * @throws IllegalArgumentException if the opcode kind is not
@@ -76,7 +102,7 @@ static JsrInstruction of(Opcode op, Label target) {
         }
 
         /**
-         * {@return a JSR instruction}
+         * {@return a jump subroutine instruction}
          *
          * @param target target label of the subroutine
          */
@@ -86,12 +112,26 @@ static JsrInstruction of(Label target) {
     }
 
     /**
-     * Models RET and RET_W instructions discontinued from the {@code code}
-     * array of a {@code Code} attribute since class file version 51.0.
-     * Corresponding opcodes will have a {@code kind} of
+     * Models return from subroutine instructions discontinued from the {@code
+     * code} array of a {@code Code} attribute since class file major version
+     * {@value ClassFile#JAVA_7_VERSION} (JVMS {@jvms 4.9.1}).
+     * Corresponding opcodes have a {@linkplain Opcode#kind() kind} of
      * {@link Opcode.Kind#DISCONTINUED_RET}.  Delivered as a {@link CodeElement}
      * when traversing the elements of a {@link CodeModel}.
+     * <p>
+     * A return from subroutine instruction is composite:
+     * {@snippet lang=text :
+     * // @link substring="RetInstruction" target="#of(int)" :
+     * RetInstruction(int slot) // @link substring="slot" target="#slot()"
+     * }
+     * where {@code slot} must be within {@code [0, 65535]}.
+     * <p>
+     * {@link StoreInstruction astore} series of instructions store a {@link
+     * TypeKind##returnAddress returnAddress} value to a local variable slot,
+     * making the slot usable by a return from subroutine instruction.
      *
+     * @jvms 6.5.ret <em>ret</em>
+     * @see Opcode.Kind#DISCONTINUED_RET
      * @since 24
      */
     sealed interface RetInstruction extends DiscontinuedInstruction
@@ -100,13 +140,23 @@ sealed interface RetInstruction extends DiscontinuedInstruction
 
         /**
          * {@return the local variable slot with return address}
+         * The value is within {@code [0, 65535]}.
          */
         int slot();
 
         /**
-         * {@return a RET or RET_W instruction}
+         * {@return a return from subroutine instruction}
+         * <p>
+         * {@code slot} must be in the closed range of {@code [0, 255]} for
+         * {@link Opcode#RET ret}, or within {@code [0, 65535]} for {@link
+         * Opcode#RET_W wide ret}.
+         *
+         * @apiNote
+         * The explicit {@code op} argument allows creating {@code wide ret}
+         * instructions with {@code slot} in the range of regular {@code ret}
+         * instructions.
          *
-         * @param op the opcode for the specific type of RET instruction,
+         * @param op the opcode for the specific type of return from subroutine instruction,
          *           which must be of kind {@link Opcode.Kind#DISCONTINUED_RET}
          * @param slot the local variable slot to load return address from
          * @throws IllegalArgumentException if the opcode kind is not
@@ -118,7 +168,9 @@ static RetInstruction of(Opcode op, int slot) {
         }
 
         /**
-         * {@return a RET instruction}
+         * {@return a return from subroutine instruction}
+         * <p>
+         * {@code slot} must be within {@code [0, 65535]}.
          *
          * @param slot the local variable slot to load return address from
          * @throws IllegalArgumentException if {@code slot} is out of range
diff --git a/src/main/java/io/github/dmlloyd/classfile/instruction/ExceptionCatch.java b/src/main/java/io/github/dmlloyd/classfile/instruction/ExceptionCatch.java
index 368ae33..480adef 100644
--- a/src/main/java/io/github/dmlloyd/classfile/instruction/ExceptionCatch.java
+++ b/src/main/java/io/github/dmlloyd/classfile/instruction/ExceptionCatch.java
@@ -24,23 +24,37 @@
  */
 package io.github.dmlloyd.classfile.instruction;
 
+import io.github.dmlloyd.classfile.CodeBuilder;
 import io.github.dmlloyd.classfile.CodeElement;
 import io.github.dmlloyd.classfile.CodeModel;
 import io.github.dmlloyd.classfile.Label;
 import io.github.dmlloyd.classfile.PseudoInstruction;
+import io.github.dmlloyd.classfile.attribute.CodeAttribute;
 import io.github.dmlloyd.classfile.constantpool.ClassEntry;
 import java.util.Optional;
 
 import io.github.dmlloyd.classfile.impl.AbstractPseudoInstruction;
 
 /**
- * A pseudo-instruction modeling an entry in the exception table of a code
- * attribute.  Entries in the exception table model catch and finally blocks.
- * Delivered as a {@link CodeElement} when traversing the contents
- * of a {@link CodeModel}.
- *
- * @see PseudoInstruction
+ * A pseudo-instruction modeling an entry in the {@code exception_table} array
+ * of a {@link CodeAttribute Code} attribute.  Catch (JVMS {@jvms 3.12}) and
+ * finally (JVMS {@jvms 3.14}) blocks in Java source code compile to exception
+ * table entries.  Delivered as a {@link CodeElement} when traversing the
+ * contents of a {@link CodeModel}.
+ * <p>
+ * An exception table entry is composite:
+ * {@snippet lang=text :
+ * // @link substring="ExceptionCatch" target="#of(Label, Label, Label, Optional)" :
+ * ExceptionCatch(
+ *     Label handler, // @link substring="handler" target="#handler"
+ *     Label tryStart, // @link substring="tryStart" target="#tryStart"
+ *     Label tryEnd, // @link substring="tryEnd" target="#tryEnd"
+ *     Optional<ClassEntry> catchType // @link substring="catchType" target="#catchType"
+ * )
+ * }
  *
+ * @see CodeBuilder#exceptionCatch CodeBuilder::exceptionCatch
+ * @jvms 4.7.3 The {@code Code} Attribute
  * @since 24
  */
 public sealed interface ExceptionCatch extends PseudoInstruction
@@ -61,8 +75,8 @@ public sealed interface ExceptionCatch extends PseudoInstruction
     Label tryEnd();
 
     /**
-     * {@return the type of the exception to catch, or empty if this handler is
-     * unconditional}
+     * {@return the type of the exception to catch, or empty if this handler
+     * catches everything}
      */
     Optional<ClassEntry> catchType();
 
@@ -80,10 +94,10 @@ static ExceptionCatch of(Label handler, Label tryStart, Label tryEnd,
     }
 
     /**
-     * {@return an exception table pseudo-instruction for an unconditional handler}
+     * {@return an exception table pseudo-instruction to catch everything}
      * @param handler the handler for the exception
-     * @param tryStart the beginning of the instruction range for the gaurded instructions
-     * @param tryEnd the end of the instruction range for the gaurded instructions
+     * @param tryStart the beginning of the instruction range for the guarded instructions
+     * @param tryEnd the end of the instruction range for the guarded instructions
      */
     static ExceptionCatch of(Label handler, Label tryStart, Label tryEnd) {
         return new AbstractPseudoInstruction.ExceptionCatchImpl(handler, tryStart, tryEnd, (ClassEntry) null);
diff --git a/src/main/java/io/github/dmlloyd/classfile/instruction/FieldInstruction.java b/src/main/java/io/github/dmlloyd/classfile/instruction/FieldInstruction.java
index 4426205..f4f03f3 100644
--- a/src/main/java/io/github/dmlloyd/classfile/instruction/FieldInstruction.java
+++ b/src/main/java/io/github/dmlloyd/classfile/instruction/FieldInstruction.java
@@ -24,6 +24,7 @@
  */
 package io.github.dmlloyd.classfile.instruction;
 
+import io.github.dmlloyd.classfile.CodeBuilder;
 import io.github.dmlloyd.classfile.CodeElement;
 import io.github.dmlloyd.classfile.CodeModel;
 import io.github.dmlloyd.classfile.Instruction;
@@ -40,10 +41,21 @@
 
 /**
  * Models a field access instruction in the {@code code} array of a {@code Code}
- * attribute.  Corresponding opcodes will have a {@code kind} of {@link
- * Opcode.Kind#FIELD_ACCESS}.  Delivered as a {@link CodeElement} when
+ * attribute.  Corresponding opcodes have a {@linkplain Opcode#kind() kind}
+ * of {@link Opcode.Kind#FIELD_ACCESS}.  Delivered as a {@link CodeElement} when
  * traversing the elements of a {@link CodeModel}.
+ * <p>
+ * A field access instruction is composite:
+ * {@snippet lang=text :
+ * // @link substring="FieldInstruction" target="#of(Opcode, FieldRefEntry)" :
+ * FieldInstruction(
+ *     Opcode opcode, // @link substring="opcode" target="#opcode()"
+ *     FieldRefEntry field, // @link substring="field" target="#field()"
+ * )
+ * }
  *
+ * @see Opcode.Kind#FIELD_ACCESS
+ * @see CodeBuilder#fieldAccess CodeBuilder::fieldAccess
  * @since 24
  */
 public sealed interface FieldInstruction extends Instruction
@@ -68,7 +80,11 @@ default Utf8Entry name() {
     }
 
     /**
-     * {@return the field descriptor of the field}
+     * {@return the field descriptor string of the field}
+     *
+     * @apiNote
+     * A symbolic descriptor for the type of the field is available through
+     * {@link #typeSymbol() typeSymbol()}.
      */
     default Utf8Entry type() {
         return field().nameAndType().type();
@@ -103,6 +119,8 @@ static FieldInstruction of(Opcode op, FieldRefEntry field) {
      * @param owner the class holding the field
      * @param name the name of the field
      * @param type the field descriptor
+     * @throws IllegalArgumentException if the opcode kind is not
+     *         {@link Opcode.Kind#FIELD_ACCESS}.
      */
     static FieldInstruction of(Opcode op,
                                ClassEntry owner,
@@ -118,6 +136,8 @@ static FieldInstruction of(Opcode op,
      *           which must be of kind {@link Opcode.Kind#FIELD_ACCESS}
      * @param owner the class holding the field
      * @param nameAndType the name and field descriptor of the field
+     * @throws IllegalArgumentException if the opcode kind is not
+     *         {@link Opcode.Kind#FIELD_ACCESS}.
      */
     static FieldInstruction of(Opcode op,
                                ClassEntry owner,
diff --git a/src/main/java/io/github/dmlloyd/classfile/instruction/IncrementInstruction.java b/src/main/java/io/github/dmlloyd/classfile/instruction/IncrementInstruction.java
index d3a9791..669cee4 100644
--- a/src/main/java/io/github/dmlloyd/classfile/instruction/IncrementInstruction.java
+++ b/src/main/java/io/github/dmlloyd/classfile/instruction/IncrementInstruction.java
@@ -24,6 +24,7 @@
  */
 package io.github.dmlloyd.classfile.instruction;
 
+import io.github.dmlloyd.classfile.CodeBuilder;
 import io.github.dmlloyd.classfile.CodeElement;
 import io.github.dmlloyd.classfile.CodeModel;
 import io.github.dmlloyd.classfile.Instruction;
@@ -33,10 +34,27 @@
 
 /**
  * Models a local variable increment instruction in the {@code code} array of a
- * {@code Code} attribute.  Corresponding opcodes will have a {@code kind} of
- * {@link Opcode.Kind#INCREMENT}.  Delivered as a {@link CodeElement} when
+ * {@code Code} attribute.  Corresponding opcodes have a {@linkplain Opcode#kind()
+ * kind} of {@link Opcode.Kind#INCREMENT}.  Delivered as a {@link CodeElement} when
  * traversing the elements of a {@link CodeModel}.
+ * <p>
+ * A local variable increment instruction is composite:
+ * {@snippet lang=text :
+ * // @link substring="IncrementInstruction" target="#of" :
+ * IncrementInstruction(
+ *     int slot, // @link substring="slot" target="#slot()"
+ *     int constant // @link substring="constant" target="#constant()"
+ * )
+ * }
+ * where
+ * <ul>
+ * <li>{@code slot} must be within {@code [0, 65535]}.
+ * <li>{@code constant} must be within {@code [-32768, 32767]}.
+ * </ul>
  *
+ * @see Opcode.Kind#INCREMENT
+ * @see CodeBuilder#iinc CodeBuilder::iinc
+ * @jvms 6.5.iinc <em>iinc</em>
  * @since 24
  */
 public sealed interface IncrementInstruction extends Instruction
@@ -54,6 +72,10 @@ public sealed interface IncrementInstruction extends Instruction
 
     /**
      * {@return an increment instruction}
+     * <ul>
+     * <li>{@code slot} must be within {@code [0, 65535]}.
+     * <li>{@code constant} must be within {@code [-32768, 32767]}.
+     * </ul>
      *
      * @param slot the local variable slot to increment
      * @param constant the value to increment by
diff --git a/src/main/java/io/github/dmlloyd/classfile/instruction/InvokeDynamicInstruction.java b/src/main/java/io/github/dmlloyd/classfile/instruction/InvokeDynamicInstruction.java
index 1c71c73..a13c866 100644
--- a/src/main/java/io/github/dmlloyd/classfile/instruction/InvokeDynamicInstruction.java
+++ b/src/main/java/io/github/dmlloyd/classfile/instruction/InvokeDynamicInstruction.java
@@ -24,9 +24,11 @@
  */
 package io.github.dmlloyd.classfile.instruction;
 
+import io.github.dmlloyd.classfile.CodeBuilder;
 import io.github.dmlloyd.classfile.CodeElement;
 import io.github.dmlloyd.classfile.CodeModel;
 import io.github.dmlloyd.classfile.Instruction;
+import io.github.dmlloyd.classfile.Opcode;
 import io.github.dmlloyd.classfile.constantpool.InvokeDynamicEntry;
 import io.github.dmlloyd.classfile.constantpool.LoadableConstantEntry;
 import io.github.dmlloyd.classfile.constantpool.Utf8Entry;
@@ -40,10 +42,20 @@
 import io.github.dmlloyd.classfile.impl.Util;
 
 /**
- * Models an {@code invokedynamic} instruction in the {@code code} array of a
- * {@code Code} attribute.  Delivered as a {@link CodeElement} when traversing
- * the elements of a {@link CodeModel}.
+ * Models a dynamically-computed call site invocation instruction in the
+ * {@code code} array of a {@code Code} attribute.  The corresponding opcode is
+ * {@link Opcode#INVOKEDYNAMIC invokedynamic}.  Delivered as a {@link
+ * CodeElement} when traversing the elements of a {@link CodeModel}.
+ * <p>
+ * A dynamically-computed call site invocation instruction is composite:
+ * {@snippet lang=text :
+ * // @link substring="InvokeDynamicInstruction" target="#of" :
+ * InvokeDynamicInstruction(InvokeDynamicEntry invokedynamic) // @link substring="invokedynamic" target="#invokedynamic()"
+ * }
  *
+ * @see Opcode.Kind#INVOKE_DYNAMIC
+ * @see CodeBuilder#invokedynamic CodeBuilder::invokedynamic
+ * @jvms 6.5.invokedynamic <em>invokedynamic</em>
  * @since 24
  */
 public sealed interface InvokeDynamicInstruction extends Instruction
@@ -62,6 +74,10 @@ default Utf8Entry name() {
 
     /**
      * {@return the invocation type of the call site}
+     *
+     * @apiNote
+     * A symbolic descriptor for the invocation typeis available through {@link
+     * #typeSymbol() typeSymbol()}.
      */
     default Utf8Entry type() {
         return invokedynamic().type();
diff --git a/src/main/java/io/github/dmlloyd/classfile/instruction/InvokeInstruction.java b/src/main/java/io/github/dmlloyd/classfile/instruction/InvokeInstruction.java
index cf34323..ecd1cd5 100644
--- a/src/main/java/io/github/dmlloyd/classfile/instruction/InvokeInstruction.java
+++ b/src/main/java/io/github/dmlloyd/classfile/instruction/InvokeInstruction.java
@@ -24,10 +24,12 @@
  */
 package io.github.dmlloyd.classfile.instruction;
 
+import io.github.dmlloyd.classfile.CodeBuilder;
 import io.github.dmlloyd.classfile.CodeElement;
 import io.github.dmlloyd.classfile.CodeModel;
 import io.github.dmlloyd.classfile.Instruction;
 import io.github.dmlloyd.classfile.Opcode;
+import io.github.dmlloyd.classfile.TypeKind;
 import io.github.dmlloyd.classfile.constantpool.ClassEntry;
 import io.github.dmlloyd.classfile.constantpool.InterfaceMethodRefEntry;
 import io.github.dmlloyd.classfile.constantpool.MemberRefEntry;
@@ -42,10 +44,26 @@
 
 /**
  * Models a method invocation instruction in the {@code code} array of a {@code
- * Code} attribute, other than {@code invokedynamic}.  Corresponding opcodes
- * will have a {@code kind} of {@link Opcode.Kind#INVOKE}.  Delivered as a
- * {@link CodeElement} when traversing the elements of a {@link CodeModel}.
+ * Code} attribute, other than {@link InvokeDynamicInstruction invokedynamic}.
+ * Corresponding opcodes have a {@linkplain Opcode#kind() kind} of {@link Opcode.Kind#INVOKE}.
+ * Delivered as a {@link CodeElement} when traversing the elements of a {@link CodeModel}.
+ * <p>
+ * A method invocation instruction is composite:
+ * {@snippet lang=text :
+ * // @link substring="InvokeInstruction" target="#of(Opcode, MemberRefEntry)" :
+ * InvokeInstruction(
+ *     Opcode opcode, // @link substring="opcode" target="#opcode()"
+ *     MethodRefEntry | InterfaceMethodRefEntry method) // @link substring="method" target="#method()"
+ * )
+ * }
+ * where {@code method} must be an {@code InterfaceMethodRefEntry} for {@link
+ * Opcode#INVOKEINTERFACE invokeinterface} opcode, and must be a {@code
+ * MethodRefEntry} for {@link Opcode#INVOKEVIRTUAL invokevirtual} opcode.
+ * {@link Opcode#INVOKESTATIC invokestatic} and {@link Opcode#INVOKESPECIAL
+ * invokespecial} can have either type of entry for {@code method}.
  *
+ * @see Opcode.Kind#INVOKE
+ * @see CodeBuilder#invoke CodeBuilder::invoke
  * @since 24
  */
 public sealed interface InvokeInstruction extends Instruction
@@ -57,18 +75,25 @@ public sealed interface InvokeInstruction extends Instruction
     MemberRefEntry method();
 
     /**
-     * {@return whether the class holding the method is an interface}
+     * {@return whether the class or interface holding the method is an interface}
      */
     boolean isInterface();
 
     /**
-     * {@return the {@code count} value of an {@code invokeinterface} instruction, as defined in JVMS {@jvms 6.5}
-     * or {@code 0} for {@code invokespecial}, {@code invokestatic} and {@code invokevirtual} instructions}
+     * {@return the {@code count} value of an {@code invokeinterface} instruction,
+     * or {@code 0} for other instructions}
+     * <p>
+     * For an {@code invokeinterface} instruction, this value must be equivalent
+     * to the sum of {@linkplain TypeKind#slotSize() slot sizes} of all arguments
+     * plus one, which is equal to the number of operand stack depth consumed by
+     * this interface method invocation instruction.
+     *
+     * @jvms 6.5.invokeinterface <em>invokeinterface</em>
      */
     int count();
 
     /**
-     * {@return the class holding the method}
+     * {@return the class or interface holding the method}
      */
     default ClassEntry owner() {
         return method().owner();
@@ -82,7 +107,11 @@ default Utf8Entry name() {
     }
 
     /**
-     * {@return the method descriptor of the method}
+     * {@return the method descriptor string of the method}
+     *
+     * @apiNote
+     * A symbolic descriptor for the type of the method is available through
+     * {@link #typeSymbol() typeSymbol()}.
      */
     default Utf8Entry type() {
         return method().nameAndType().type();
@@ -95,7 +124,6 @@ default MethodTypeDesc typeSymbol() {
         return Util.methodTypeSymbol(method().type());
     }
 
-
     /**
      * {@return an invocation instruction}
      *
@@ -103,7 +131,7 @@ default MethodTypeDesc typeSymbol() {
      *           which must be of kind {@link Opcode.Kind#INVOKE}
      * @param method a constant pool entry describing the method
      * @throws IllegalArgumentException if the opcode kind is not
-     *         {@link Opcode.Kind#INVOKE}.
+     *         {@link Opcode.Kind#INVOKE}
      */
     static InvokeInstruction of(Opcode op, MemberRefEntry method) {
         Util.checkKind(op, Opcode.Kind.INVOKE);
@@ -119,6 +147,8 @@ static InvokeInstruction of(Opcode op, MemberRefEntry method) {
      * @param name the name of the method
      * @param type the method descriptor
      * @param isInterface whether the class holding the method is an interface
+     * @throws IllegalArgumentException if the opcode kind is not
+     *         {@link Opcode.Kind#INVOKE}
      */
     static InvokeInstruction of(Opcode op,
                                 ClassEntry owner,
@@ -136,6 +166,8 @@ static InvokeInstruction of(Opcode op,
      * @param owner the class holding the method
      * @param nameAndType the name and type of the method
      * @param isInterface whether the class holding the method is an interface
+     * @throws IllegalArgumentException if the opcode kind is not
+     *         {@link Opcode.Kind#INVOKE}
      */
     static InvokeInstruction of(Opcode op,
                                 ClassEntry owner,
diff --git a/src/main/java/io/github/dmlloyd/classfile/instruction/LabelTarget.java b/src/main/java/io/github/dmlloyd/classfile/instruction/LabelTarget.java
index 100feba..b82bf72 100644
--- a/src/main/java/io/github/dmlloyd/classfile/instruction/LabelTarget.java
+++ b/src/main/java/io/github/dmlloyd/classfile/instruction/LabelTarget.java
@@ -24,10 +24,13 @@
  */
 package io.github.dmlloyd.classfile.instruction;
 
+import io.github.dmlloyd.classfile.CodeBuilder;
 import io.github.dmlloyd.classfile.CodeElement;
 import io.github.dmlloyd.classfile.CodeModel;
+import io.github.dmlloyd.classfile.CodeTransform;
 import io.github.dmlloyd.classfile.Label;
 import io.github.dmlloyd.classfile.PseudoInstruction;
+import io.github.dmlloyd.classfile.attribute.CodeAttribute;
 
 import io.github.dmlloyd.classfile.impl.LabelImpl;
 
@@ -35,9 +38,28 @@
  * A pseudo-instruction which indicates that the specified label corresponds to
  * the current position in the {@code Code} attribute.  Delivered as a {@link
  * CodeElement} during traversal of the elements of a {@link CodeModel}.
+ * <p>
+ * This can be used to inspect the target position of labels across {@linkplain
+ * CodeTransform transformations}, as {@linkplain CodeAttribute#labelToBci bci}
+ * is not stable.
+ * <p>
+ * When passed to a {@link CodeBuilder}, this pseudo-instruction sets the
+ * specified label to be bound at the current position in the builder.
+ * <p>
+ * By design, {@code LabelTarget} cannot be created by users and can only be
+ * read from a code model.  Use {@link CodeBuilder#labelBinding
+ * CodeBuilder::labelBinding} to bind arbitrary labels to a {@code CodeBuilder}.
+ * <p>
+ * For a {@code CodeBuilder cob}, a {@code LabelTarget lt}, these two calls are
+ * equivalent:
+ * {@snippet lang=java :
+ * cob.with(lt); // @link substring="with" target="CodeBuilder#with"
+ * // @link substring="labelBinding" target="CodeBuilder#labelBinding" :
+ * cob.labelBinding(lt.label()); // @link substring="label" target="#label"
+ * }
  *
- * @see PseudoInstruction
- *
+ * @see Label
+ * @see CodeBuilder#labelBinding CodeBuilder::labelBinding
  * @since 24
  */
 public sealed interface LabelTarget extends PseudoInstruction
diff --git a/src/main/java/io/github/dmlloyd/classfile/instruction/LineNumber.java b/src/main/java/io/github/dmlloyd/classfile/instruction/LineNumber.java
index 300cffa..79c4c8e 100644
--- a/src/main/java/io/github/dmlloyd/classfile/instruction/LineNumber.java
+++ b/src/main/java/io/github/dmlloyd/classfile/instruction/LineNumber.java
@@ -25,21 +25,42 @@
 package io.github.dmlloyd.classfile.instruction;
 
 import io.github.dmlloyd.classfile.ClassFile;
+import io.github.dmlloyd.classfile.CodeBuilder;
 import io.github.dmlloyd.classfile.CodeElement;
 import io.github.dmlloyd.classfile.CodeModel;
 import io.github.dmlloyd.classfile.PseudoInstruction;
+import io.github.dmlloyd.classfile.attribute.CodeAttribute;
+import io.github.dmlloyd.classfile.attribute.LineNumberInfo;
 import io.github.dmlloyd.classfile.attribute.LineNumberTableAttribute;
 
 import io.github.dmlloyd.classfile.impl.LineNumberImpl;
 
 /**
- * A pseudo-instruction which models a single entry in the
- * {@link LineNumberTableAttribute}.  Delivered as a {@link CodeElement}
- * during traversal of the elements of a {@link CodeModel}, according to
- * the setting of the {@link ClassFile.LineNumbersOption} option.
+ * A pseudo-instruction which indicates the code for a given line number starts
+ * after the current position in a {@link CodeAttribute Code} attribute.  This
+ * models a single entry in the {@link LineNumberTableAttribute LineNumberTable}
+ * attribute.  Delivered as a {@link CodeElement} during traversal of the
+ * elements of a {@link CodeModel}, according to the setting of the {@link
+ * ClassFile.LineNumbersOption} option.
+ * <p>
+ * A line number entry is composite:
+ * {@snippet lang=text :
+ * // @link substring="LineNumber" target="#of" :
+ * LineNumber(int line) // @link substring="int line" target="#line"
+ * }
+ * <p>
+ * Another model, {@link LineNumberInfo}, also models a line number entry; it
+ * has no dependency on a {@code CodeModel} and represents of bci values as
+ * {@code int}s instead of order of pseudo-instructions in the elements of a
+ * {@code CodeModel}, and is used as components of a {@link LineNumberTableAttribute}.
  *
- * @see PseudoInstruction
+ * @apiNote
+ * Line numbers are represented with custom pseudo-instructions to avoid using
+ * labels, which usually indicate branching targets for the control flow.
  *
+ * @see LineNumberInfo
+ * @see CodeBuilder#lineNumber CodeBuilder::lineNumber
+ * @see ClassFile.LineNumbersOption
  * @since 24
  */
 public sealed interface LineNumber extends PseudoInstruction
diff --git a/src/main/java/io/github/dmlloyd/classfile/instruction/LoadInstruction.java b/src/main/java/io/github/dmlloyd/classfile/instruction/LoadInstruction.java
index 673a368..68329f4 100644
--- a/src/main/java/io/github/dmlloyd/classfile/instruction/LoadInstruction.java
+++ b/src/main/java/io/github/dmlloyd/classfile/instruction/LoadInstruction.java
@@ -24,6 +24,7 @@
  */
 package io.github.dmlloyd.classfile.instruction;
 
+import io.github.dmlloyd.classfile.CodeBuilder;
 import io.github.dmlloyd.classfile.CodeElement;
 import io.github.dmlloyd.classfile.CodeModel;
 import io.github.dmlloyd.classfile.Instruction;
@@ -36,10 +37,23 @@
 
 /**
  * Models a local variable load instruction in the {@code code} array of a
- * {@code Code} attribute.  Corresponding opcodes will have a {@code kind} of
- * {@link Opcode.Kind#LOAD}.  Delivered as a {@link CodeElement} when
- * traversing the elements of a {@link CodeModel}.
+ * {@code Code} attribute.  Corresponding opcodes have a {@linkplain
+ * Opcode#kind() kind} of {@link Opcode.Kind#LOAD}.  Delivered as a {@link
+ * CodeElement} when traversing the elements of a {@link CodeModel}.
+ * <p>
+ * A local variable load instruction is composite:
+ * {@snippet lang=text :
+ * // @link substring="LoadInstruction" target="#of(TypeKind, int)" :
+ * LoadInstruction(
+ *     TypeKind typeKind, // @link substring="typeKind" target="#typeKind"
+ *     int slot // @link substring="slot" target="#slot"
+ * )
+ * }
+ * where {@code TypeKind} is {@linkplain TypeKind##computational-type
+ * computational}, and {@code slot} is within {@code [0, 65535]}.
  *
+ * @see Opcode.Kind#LOAD
+ * @see CodeBuilder#loadLocal CodeBuilder::loadLocal
  * @since 24
  */
 public sealed interface LoadInstruction extends Instruction
@@ -48,16 +62,21 @@ public sealed interface LoadInstruction extends Instruction
 
     /**
      * {@return the local variable slot to load from}
+     * The value is within {@code [0, 65535]}.
      */
     int slot();
 
     /**
-     * {@return the type of the value to be loaded}
+     * {@return the {@linkplain TypeKind##computational-type computational type}
+     * of the value to be loaded}
      */
     TypeKind typeKind();
 
     /**
      * {@return a local variable load instruction}
+     * {@code kind} is {@linkplain TypeKind#asLoadable() converted} to its
+     * computational type.
+     * {@code slot} must be within {@code [0, 65535]}.
      *
      * @param kind the type of the value to be loaded
      * @param slot the local variable slot to load from
@@ -71,6 +90,20 @@ static LoadInstruction of(TypeKind kind, int slot) {
 
     /**
      * {@return a local variable load instruction}
+     * <p>
+     * The range of {@code slot} is restricted by the {@code op} and its
+     * {@linkplain Opcode#sizeIfFixed() size}:
+     * <ul>
+     * <li>If {@code op} has size 1, {@code slot} must be exactly the slot value
+     * implied by the opcode.
+     * <li>If {@code op} has size 2, {@code slot} must be within {@code [0, 255]}.
+     * <li>If {@code op} has size 4, {@code slot} must be within {@code [0, 65535]}.
+     * </ul>
+     *
+     * @apiNote
+     * The explicit {@code op} argument allows creating {@code wide} or
+     * regular load instructions when the {@code slot} can be encoded
+     * with more optimized load instructions.
      *
      * @param op the opcode for the specific type of load instruction,
      *           which must be of kind {@link Opcode.Kind#LOAD}
diff --git a/src/main/java/io/github/dmlloyd/classfile/instruction/LocalVariable.java b/src/main/java/io/github/dmlloyd/classfile/instruction/LocalVariable.java
index f902dd6..96f15d8 100644
--- a/src/main/java/io/github/dmlloyd/classfile/instruction/LocalVariable.java
+++ b/src/main/java/io/github/dmlloyd/classfile/instruction/LocalVariable.java
@@ -25,10 +25,12 @@
 package io.github.dmlloyd.classfile.instruction;
 
 import io.github.dmlloyd.classfile.ClassFile;
+import io.github.dmlloyd.classfile.CodeBuilder;
 import io.github.dmlloyd.classfile.CodeElement;
 import io.github.dmlloyd.classfile.CodeModel;
 import io.github.dmlloyd.classfile.Label;
 import io.github.dmlloyd.classfile.PseudoInstruction;
+import io.github.dmlloyd.classfile.attribute.LocalVariableInfo;
 import io.github.dmlloyd.classfile.attribute.LocalVariableTableAttribute;
 import io.github.dmlloyd.classfile.constantpool.Utf8Entry;
 import java.lang.constant.ClassDesc;
@@ -39,19 +41,45 @@
 import io.github.dmlloyd.classfile.impl.Util;
 
 /**
- * A pseudo-instruction which models a single entry in the
- * {@link LocalVariableTableAttribute}.  Delivered as a {@link CodeElement}
- * during traversal of the elements of a {@link CodeModel}, according to
- * the setting of the {@link ClassFile.DebugElementsOption} option.
+ * A pseudo-instruction which models a single entry in the {@link
+ * LocalVariableTableAttribute LocalVariableTable} attribute.  Delivered as a
+ * {@link CodeElement} during traversal of the elements of a {@link CodeModel},
+ * according to the setting of the {@link ClassFile.DebugElementsOption} option.
+ * <p>
+ * A local variable entry is composite:
+ * {@snippet lang=text :
+ * // @link substring="LocalVariable" target="#of(int, String, ClassDesc, Label, Label)" :
+ * LocalVariable(
+ *     int slot, // @link substring="slot" target="#slot"
+ *     String name, // @link substring="name" target="#name"
+ *     ClassDesc type, // @link substring="type" target="#type"
+ *     Label startScope, // @link substring="startScope" target="#startScope"
+ *     Label endScope // @link substring="endScope" target="#endScope"
+ * )
+ * }
+ * Where {@code slot} is within {@code [0, 65535]}.
+ * <p>
+ * Another model, {@link LocalVariableInfo}, also models a local variable
+ * entry; it has no dependency on a {@code CodeModel} and represents of bci
+ * values as {@code int}s instead of {@code Label}s, and is used as components
+ * of a {@link LocalVariableTableAttribute}.
  *
- * @see PseudoInstruction
+ * @apiNote
+ * {@code LocalVariable} is used for all local variables in Java source code.
+ * If a local variable has a parameterized type, a type argument, or an array
+ * type of one of the previous types, a {@link LocalVariableType} should be
+ * created for that local variable as well.
  *
+ * @see LocalVariableInfo
+ * @see CodeBuilder#localVariable CodeBuilder::localVariable
+ * @see ClassFile.DebugElementsOption
  * @since 24
  */
 public sealed interface LocalVariable extends PseudoInstruction
         permits AbstractPseudoInstruction.UnboundLocalVariable, BoundLocalVariable {
     /**
      * {@return the local variable slot}
+     * The value is within {@code [0, 65535]}.
      */
     int slot();
 
@@ -61,7 +89,11 @@ public sealed interface LocalVariable extends PseudoInstruction
     Utf8Entry name();
 
     /**
-     * {@return the local variable field descriptor}
+     * {@return the local variable field descriptor string}
+     *
+     * @apiNote
+     * A symbolic descriptor for the type of the local variable is available
+     * through {@link #typeSymbol() typeSymbol()}.
      */
     Utf8Entry type();
 
@@ -84,6 +116,7 @@ default ClassDesc typeSymbol() {
 
     /**
      * {@return a local variable pseudo-instruction}
+     * {@code slot} must be within {@code [0, 65535]}.
      *
      * @param slot the local variable slot
      * @param nameEntry the local variable name
@@ -99,6 +132,7 @@ static LocalVariable of(int slot, Utf8Entry nameEntry, Utf8Entry descriptorEntry
 
     /**
      * {@return a local variable pseudo-instruction}
+     * {@code slot} must be within {@code [0, 65535]}.
      *
      * @param slot the local variable slot
      * @param name the local variable name
diff --git a/src/main/java/io/github/dmlloyd/classfile/instruction/LocalVariableType.java b/src/main/java/io/github/dmlloyd/classfile/instruction/LocalVariableType.java
index d9111ab..951f9fd 100644
--- a/src/main/java/io/github/dmlloyd/classfile/instruction/LocalVariableType.java
+++ b/src/main/java/io/github/dmlloyd/classfile/instruction/LocalVariableType.java
@@ -24,12 +24,8 @@
  */
 package io.github.dmlloyd.classfile.instruction;
 
-import io.github.dmlloyd.classfile.ClassFile;
-import io.github.dmlloyd.classfile.CodeElement;
-import io.github.dmlloyd.classfile.CodeModel;
-import io.github.dmlloyd.classfile.Label;
-import io.github.dmlloyd.classfile.PseudoInstruction;
-import io.github.dmlloyd.classfile.Signature;
+import io.github.dmlloyd.classfile.*;
+import io.github.dmlloyd.classfile.attribute.LocalVariableTypeInfo;
 import io.github.dmlloyd.classfile.attribute.LocalVariableTypeTableAttribute;
 import io.github.dmlloyd.classfile.constantpool.Utf8Entry;
 
@@ -39,16 +35,44 @@
 
 /**
  * A pseudo-instruction which models a single entry in the {@link
- * LocalVariableTypeTableAttribute}.  Delivered as a {@link CodeElement} during
- * traversal of the elements of a {@link CodeModel}, according to the setting of
- * the {@link ClassFile.DebugElementsOption} option.
+ * LocalVariableTypeTableAttribute LocalVariableTypeTable} attribute.  Delivered
+ * as a {@link CodeElement} during traversal of the elements of a {@link CodeModel},
+ * according to the setting of the {@link ClassFile.DebugElementsOption} option.
+ * <p>
+ * A local variable type entry is composite:
+ * {@snippet lang=text :
+ * // @link substring="LocalVariableType" target="#of(int, String, Signature, Label, Label)" :
+ * LocalVariableType(
+ *     int slot, // @link substring="slot" target="#slot"
+ *     String name, // @link substring="name" target="#name"
+ *     Signature signature, // @link substring="signature" target="#signatureSymbol"
+ *     Label startScope, // @link substring="startScope" target="#startScope"
+ *     Label endScope // @link substring="endScope" target="#endScope"
+ * )
+ * }
+ * Where {@code slot} is within {@code [0, 65535]}.
+ * <p>
+ * Another model, {@link LocalVariableTypeInfo}, also models a local variable
+ * type entry; it has no dependency on a {@code CodeModel} and represents of bci
+ * values as {@code int}s instead of {@code Label}s, and is used as components
+ * of a {@link LocalVariableTypeTableAttribute}.
  *
+ * @apiNote
+ * {@code LocalVariableType} is used if a local variable has a parameterized
+ * type, a type argument, or an array type of one of the previous types as its
+ * type.  A {@link LocalVariable} with the erased type should still be created
+ * for that local variable.
+ *
+ * @see LocalVariableTypeInfo
+ * @see CodeBuilder#localVariableType CodeBuilder::localVariableType
+ * @see ClassFile.DebugElementsOption
  * @since 24
  */
 public sealed interface LocalVariableType extends PseudoInstruction
         permits AbstractPseudoInstruction.UnboundLocalVariableType, BoundLocalVariableType {
     /**
      * {@return the local variable slot}
+     * The value is within {@code [0, 65535]}.
      */
     int slot();
 
@@ -58,12 +82,16 @@ public sealed interface LocalVariableType extends PseudoInstruction
     Utf8Entry name();
 
     /**
-     * {@return the local variable signature}
+     * {@return the local variable generic signature string}
+     *
+     * @apiNote
+     * A symbolic generic signature of the local variable is available
+     * through {@link #signatureSymbol() signatureSymbol()}.
      */
     Utf8Entry signature();
 
     /**
-     * {@return the local variable signature}
+     * {@return the local variable generic signature}
      */
     default Signature signatureSymbol() {
         return Signature.parseFrom(signature().stringValue());
@@ -81,6 +109,7 @@ default Signature signatureSymbol() {
 
     /**
      * {@return a local variable type pseudo-instruction}
+     * {@code slot} must be within {@code [0, 65535]}.
      *
      * @param slot the local variable slot
      * @param nameEntry the local variable name
@@ -96,6 +125,7 @@ static LocalVariableType of(int slot, Utf8Entry nameEntry, Utf8Entry signatureEn
 
     /**
      * {@return a local variable type pseudo-instruction}
+     * {@code slot} must be within {@code [0, 65535]}.
      *
      * @param slot the local variable slot
      * @param name the local variable name
diff --git a/src/main/java/io/github/dmlloyd/classfile/instruction/LookupSwitchInstruction.java b/src/main/java/io/github/dmlloyd/classfile/instruction/LookupSwitchInstruction.java
index f11b680..6d8a1aa 100644
--- a/src/main/java/io/github/dmlloyd/classfile/instruction/LookupSwitchInstruction.java
+++ b/src/main/java/io/github/dmlloyd/classfile/instruction/LookupSwitchInstruction.java
@@ -24,19 +24,36 @@
  */
 package io.github.dmlloyd.classfile.instruction;
 
+import io.github.dmlloyd.classfile.CodeBuilder;
 import io.github.dmlloyd.classfile.CodeElement;
 import io.github.dmlloyd.classfile.CodeModel;
 import io.github.dmlloyd.classfile.Instruction;
 import io.github.dmlloyd.classfile.Label;
+import io.github.dmlloyd.classfile.Opcode;
 import java.util.List;
 
 import io.github.dmlloyd.classfile.impl.AbstractInstruction;
 
 /**
- * Models a {@code lookupswitch} instruction in the {@code code} array of a
- * {@code Code} attribute.  Delivered as a {@link CodeElement} when traversing
- * the elements of a {@link CodeModel}.
+ * Models a {@link Opcode#LOOKUPSWITCH lookupswitch} instruction in the {@code
+ * code} array of a {@code Code} attribute.  Delivered as a {@link CodeElement}
+ * when traversing the elements of a {@link CodeModel}.
+ * <p>
+ * A lookup switch instruction is composite:
+ * {@snippet lang=text :
+ * // @link substring="LookupSwitchInstruction" target="#of" :
+ * LookupSwitchInstruction(
+ *     Label defaultTarget, // @link substring="defaultTarget" target="#defaultTarget"
+ *     List<SwitchCase> cases // @link substring="cases" target="#cases()"
+ * )
+ * }
+ * If elements in {@code cases} are not sorted ascending by their {@link
+ * SwitchCase#caseValue caseValue}, a sorted version of the {@code cases} list
+ * will be written instead.
  *
+ * @see Opcode.Kind#LOOKUP_SWITCH
+ * @see CodeBuilder#lookupswitch CodeBuilder::lookupswitch
+ * @jvms 6.5.lookupswitch <em>lookupswitch</em>
  * @since 24
  */
 public sealed interface LookupSwitchInstruction extends Instruction
diff --git a/src/main/java/io/github/dmlloyd/classfile/instruction/MonitorInstruction.java b/src/main/java/io/github/dmlloyd/classfile/instruction/MonitorInstruction.java
index e66f970..dbdd500 100644
--- a/src/main/java/io/github/dmlloyd/classfile/instruction/MonitorInstruction.java
+++ b/src/main/java/io/github/dmlloyd/classfile/instruction/MonitorInstruction.java
@@ -24,6 +24,7 @@
  */
 package io.github.dmlloyd.classfile.instruction;
 
+import io.github.dmlloyd.classfile.CodeBuilder;
 import io.github.dmlloyd.classfile.CodeElement;
 import io.github.dmlloyd.classfile.CodeModel;
 import io.github.dmlloyd.classfile.Instruction;
@@ -33,9 +34,17 @@
 import io.github.dmlloyd.classfile.impl.Util;
 
 /**
- * Models a {@code monitorenter} or {@code monitorexit} instruction in the
- * {@code code} array of a {@code Code} attribute.  Delivered as a {@link
- * CodeElement} when traversing the elements of a {@link CodeModel}.
+ * Models a {@link Opcode#MONITORENTER monitorenter} or {@link Opcode#MONITOREXIT
+ * monitorexit} instruction in the {@code code} array of a {@code Code} attribute.
+ * Corresponding opcodes have a {@linkplain Opcode#kind() kind} of {@link
+ * Opcode.Kind#MONITOR}.  Delivered as a {@link CodeElement} when traversing the
+ * elements of a {@link CodeModel}.
+ * <p>
+ * A monitor instruction is composite:
+ * {@snippet lang=text :
+ * // @link substring="MonitorInstruction" target="#of(Opcode)" :
+ * MonitorInstruction(Opcode opcode) // @link substring="opcode" target="#opcode"
+ * }
  *
  * @since 24
  */
diff --git a/src/main/java/io/github/dmlloyd/classfile/instruction/NewMultiArrayInstruction.java b/src/main/java/io/github/dmlloyd/classfile/instruction/NewMultiArrayInstruction.java
index b4371a1..41ef73a 100644
--- a/src/main/java/io/github/dmlloyd/classfile/instruction/NewMultiArrayInstruction.java
+++ b/src/main/java/io/github/dmlloyd/classfile/instruction/NewMultiArrayInstruction.java
@@ -24,19 +24,34 @@
  */
 package io.github.dmlloyd.classfile.instruction;
 
+import io.github.dmlloyd.classfile.CodeBuilder;
 import io.github.dmlloyd.classfile.CodeElement;
 import io.github.dmlloyd.classfile.CodeModel;
 import io.github.dmlloyd.classfile.Instruction;
+import io.github.dmlloyd.classfile.Opcode;
 import io.github.dmlloyd.classfile.constantpool.ClassEntry;
 
 import io.github.dmlloyd.classfile.impl.AbstractInstruction;
 import io.github.dmlloyd.classfile.impl.BytecodeHelpers;
 
 /**
- * Models a {@code multianewarray} invocation instruction in the {@code code}
+ * Models a {@link Opcode#MULTIANEWARRAY multianewarray} instruction in the {@code code}
  * array of a {@code Code} attribute.  Delivered as a {@link CodeElement}
  * when traversing the elements of a {@link CodeModel}.
+ * <p>
+ * A new multi-dimensional array instruction is composite:
+ * {@snippet lang=text :
+ * // @link substring="NewMultiArrayInstruction" target="#of" :
+ * NewMultiArrayInstruction(
+ *     ClassEntry arrayType, // @link substring="arrayType" target="#arrayType"
+ *     int dimensions // @link substring="dimensions" target="#dimensions"
+ * )
+ * }
+ * where the {@code arrayType} is an array class.
  *
+ * @see Opcode.Kind#NEW_MULTI_ARRAY
+ * @see CodeBuilder#multianewarray CodeBuilder::multianewarray
+ * @jvms 6.5.multianewarray <em>multianewarray</em>
  * @since 24
  */
 public sealed interface NewMultiArrayInstruction extends Instruction
@@ -44,7 +59,7 @@ public sealed interface NewMultiArrayInstruction extends Instruction
                 AbstractInstruction.UnboundNewMultidimensionalArrayInstruction {
 
     /**
-     * {@return the type of the array, as a symbolic descriptor}
+     * {@return the type of the array}
      */
     ClassEntry arrayType();
 
diff --git a/src/main/java/io/github/dmlloyd/classfile/instruction/NewObjectInstruction.java b/src/main/java/io/github/dmlloyd/classfile/instruction/NewObjectInstruction.java
index 3a2d638..4ae1a31 100644
--- a/src/main/java/io/github/dmlloyd/classfile/instruction/NewObjectInstruction.java
+++ b/src/main/java/io/github/dmlloyd/classfile/instruction/NewObjectInstruction.java
@@ -24,18 +24,30 @@
  */
 package io.github.dmlloyd.classfile.instruction;
 
+import io.github.dmlloyd.classfile.CodeBuilder;
 import io.github.dmlloyd.classfile.CodeElement;
 import io.github.dmlloyd.classfile.CodeModel;
 import io.github.dmlloyd.classfile.Instruction;
+import io.github.dmlloyd.classfile.Opcode;
 import io.github.dmlloyd.classfile.constantpool.ClassEntry;
 
 import io.github.dmlloyd.classfile.impl.AbstractInstruction;
 
 /**
- * Models a {@code new} instruction in the {@code code} array of a {@code Code}
+ * Models a {@link Opcode#NEW new} instruction in the {@code code} array of a {@code Code}
  * attribute.  Delivered as a {@link CodeElement} when traversing the elements
  * of a {@link CodeModel}.
+ * <p>
+ * A new object instruction is composite:
+ * {@snippet lang=text :
+ * // @link substring="NewObjectInstruction" target="#of" :
+ * NewObjectInstruction(ClassEntry className) // @link substring="className" target="#className"
+ * }
+ * where the {@code className} is a non-abstract class.
  *
+ * @see Opcode.Kind#NEW_OBJECT
+ * @see CodeBuilder#new_ CodeBuilder::new_
+ * @jvms 6.5.new <em>new</em>
  * @since 24
  */
 public sealed interface NewObjectInstruction extends Instruction
diff --git a/src/main/java/io/github/dmlloyd/classfile/instruction/NewPrimitiveArrayInstruction.java b/src/main/java/io/github/dmlloyd/classfile/instruction/NewPrimitiveArrayInstruction.java
index 0a5e00d..7fabba7 100644
--- a/src/main/java/io/github/dmlloyd/classfile/instruction/NewPrimitiveArrayInstruction.java
+++ b/src/main/java/io/github/dmlloyd/classfile/instruction/NewPrimitiveArrayInstruction.java
@@ -24,18 +24,30 @@
  */
 package io.github.dmlloyd.classfile.instruction;
 
+import io.github.dmlloyd.classfile.CodeBuilder;
 import io.github.dmlloyd.classfile.CodeElement;
 import io.github.dmlloyd.classfile.CodeModel;
 import io.github.dmlloyd.classfile.Instruction;
+import io.github.dmlloyd.classfile.Opcode;
 import io.github.dmlloyd.classfile.TypeKind;
 
 import io.github.dmlloyd.classfile.impl.AbstractInstruction;
 
 /**
- * Models a {@code newarray} invocation instruction in the {@code code}
+ * Models a {@link Opcode#NEWARRAY newarray} instruction in the {@code code}
  * array of a {@code Code} attribute.  Delivered as a {@link CodeElement}
  * when traversing the elements of a {@link CodeModel}.
+ * <p>
+ * A new primitive array instruction is composite:
+ * {@snippet lang=text :
+ * // @link substring="NewPrimitiveArrayInstruction" target="#of" :
+ * NewPrimitiveArrayInstruction(TypeKind typeKind) // @link substring="typeKind" target="#typeKind"
+ * }
+ * where {@code typeKind} is primitive and not {@code void}.
  *
+ * @see Opcode.Kind#NEW_PRIMITIVE_ARRAY
+ * @see CodeBuilder#newarray CodeBuilder::newarray
+ * @jvms 6.5.newarray <em>newarray</em>
  * @since 24
  */
 public sealed interface NewPrimitiveArrayInstruction extends Instruction
@@ -43,6 +55,10 @@ public sealed interface NewPrimitiveArrayInstruction extends Instruction
                 AbstractInstruction.UnboundNewPrimitiveArrayInstruction {
     /**
      * {@return the component type of the array}
+     *
+     * @apiNote
+     * The backing array code for this instruction is available through
+     * {@link TypeKind#newarrayCode() typeKind().newarrayCode()}.
      */
     TypeKind typeKind();
 
@@ -50,8 +66,9 @@ public sealed interface NewPrimitiveArrayInstruction extends Instruction
      * {@return a new primitive array instruction}
      *
      * @param typeKind the component type of the array
-     * @throws IllegalArgumentException when the {@code typeKind} is not a legal
-     *                                  primitive array component type
+     * @throws IllegalArgumentException when {@code typeKind} is not primitive
+     *         or is {@code void}
+     * @see TypeKind#fromNewarrayCode(int) TypeKind::fromNewarrayCode
      */
     static NewPrimitiveArrayInstruction of(TypeKind typeKind) {
         // Implicit null-check:
diff --git a/src/main/java/io/github/dmlloyd/classfile/instruction/NewReferenceArrayInstruction.java b/src/main/java/io/github/dmlloyd/classfile/instruction/NewReferenceArrayInstruction.java
index 29349e0..568cc99 100644
--- a/src/main/java/io/github/dmlloyd/classfile/instruction/NewReferenceArrayInstruction.java
+++ b/src/main/java/io/github/dmlloyd/classfile/instruction/NewReferenceArrayInstruction.java
@@ -24,18 +24,29 @@
  */
 package io.github.dmlloyd.classfile.instruction;
 
+import io.github.dmlloyd.classfile.CodeBuilder;
 import io.github.dmlloyd.classfile.CodeElement;
 import io.github.dmlloyd.classfile.CodeModel;
 import io.github.dmlloyd.classfile.Instruction;
+import io.github.dmlloyd.classfile.Opcode;
 import io.github.dmlloyd.classfile.constantpool.ClassEntry;
 
 import io.github.dmlloyd.classfile.impl.AbstractInstruction;
 
 /**
- * Models a {@code anewarray} invocation instruction in the {@code code}
+ * Models a {@link Opcode#ANEWARRAY anewarray} instruction in the {@code code}
  * array of a {@code Code} attribute.  Delivered as a {@link CodeElement}
  * when traversing the elements of a {@link CodeModel}.
+ * <p>
+ * A new reference array instruction is composite:
+ * {@snippet lang=text :
+ * // @link substring="NewReferenceArrayInstruction" target="#of" :
+ * NewReferenceArrayInstruction(ClassEntry componentType) // @link substring="componentType" target="#componentType"
+ * }
  *
+ * @see Opcode.Kind#NEW_REF_ARRAY
+ * @see CodeBuilder#newarray CodeBuilder::anewarray
+ * @jvms 6.5.anewarray <em>anewarray</em>
  * @since 24
  */
 public sealed interface NewReferenceArrayInstruction extends Instruction
diff --git a/src/main/java/io/github/dmlloyd/classfile/instruction/NopInstruction.java b/src/main/java/io/github/dmlloyd/classfile/instruction/NopInstruction.java
index 95b065c..afd5921 100644
--- a/src/main/java/io/github/dmlloyd/classfile/instruction/NopInstruction.java
+++ b/src/main/java/io/github/dmlloyd/classfile/instruction/NopInstruction.java
@@ -24,17 +24,23 @@
  */
 package io.github.dmlloyd.classfile.instruction;
 
+import io.github.dmlloyd.classfile.CodeBuilder;
 import io.github.dmlloyd.classfile.CodeElement;
 import io.github.dmlloyd.classfile.CodeModel;
 import io.github.dmlloyd.classfile.Instruction;
+import io.github.dmlloyd.classfile.Opcode;
 
 import io.github.dmlloyd.classfile.impl.AbstractInstruction;
 
 /**
- * Models a {@code nop} invocation instruction in the {@code code}
+ * Models a {@link Opcode#NOP nop} instruction in the {@code code}
  * array of a {@code Code} attribute.  Delivered as a {@link CodeElement}
  * when traversing the elements of a {@link CodeModel}.
+ * <p>
+ * A no-op instruction has no visible state.
  *
+ * @see CodeBuilder#nop CodeBuilder::nop
+ * @jvms 6.5.nop <em>nop</em>
  * @since 24
  */
 public sealed interface NopInstruction extends Instruction
diff --git a/src/main/java/io/github/dmlloyd/classfile/instruction/OperatorInstruction.java b/src/main/java/io/github/dmlloyd/classfile/instruction/OperatorInstruction.java
index da1007a..c50f327 100644
--- a/src/main/java/io/github/dmlloyd/classfile/instruction/OperatorInstruction.java
+++ b/src/main/java/io/github/dmlloyd/classfile/instruction/OperatorInstruction.java
@@ -35,23 +35,31 @@
 
 /**
  * Models an arithmetic operator instruction in the {@code code} array of a
- * {@code Code} attribute.  Corresponding opcodes will have a {@code kind} of
+ * {@code Code} attribute.  Corresponding opcodes have a {@linkplain Opcode#kind() kind} of
  * {@link Opcode.Kind#OPERATOR}.  Delivered as a {@link CodeElement} when
  * traversing the elements of a {@link CodeModel}.
+ * <p>
+ * An operator instruction is composite:
+ * {@snippet lang=text :
+ * // @link substring="OperatorInstruction" target="#of" :
+ * OperatorInstruction(Opcode opcode) // @link substring="opcode" target="#opcode()"
+ * }
  *
+ * @see Opcode.Kind#OPERATOR
  * @since 24
  */
 public sealed interface OperatorInstruction extends Instruction
         permits AbstractInstruction.UnboundOperatorInstruction {
     /**
      * {@return the operand type of the instruction}
+     * This is derived from the {@link #opcode opcode}.
      */
     TypeKind typeKind();
 
     /**
      * {@return an operator instruction}
      *
-     * @param op the opcode for the specific type of array load instruction,
+     * @param op the opcode for the specific type of operator instruction,
      *           which must be of kind {@link Opcode.Kind#OPERATOR}
      * @throws IllegalArgumentException if the opcode kind is not
      *         {@link Opcode.Kind#OPERATOR}.
diff --git a/src/main/java/io/github/dmlloyd/classfile/instruction/ReturnInstruction.java b/src/main/java/io/github/dmlloyd/classfile/instruction/ReturnInstruction.java
index b8d437c..cfa0127 100644
--- a/src/main/java/io/github/dmlloyd/classfile/instruction/ReturnInstruction.java
+++ b/src/main/java/io/github/dmlloyd/classfile/instruction/ReturnInstruction.java
@@ -24,6 +24,7 @@
  */
 package io.github.dmlloyd.classfile.instruction;
 
+import io.github.dmlloyd.classfile.CodeBuilder;
 import io.github.dmlloyd.classfile.CodeElement;
 import io.github.dmlloyd.classfile.CodeModel;
 import io.github.dmlloyd.classfile.Instruction;
@@ -36,22 +37,35 @@
 
 /**
  * Models a return-from-method instruction in the {@code code} array of a
- * {@code Code} attribute.  Corresponding opcodes will have a {@code kind} of
+ * {@code Code} attribute.  Corresponding opcodes have a {@linkplain Opcode#kind() kind} of
  * {@link Opcode.Kind#RETURN}.  Delivered as a {@link CodeElement} when
  * traversing the elements of a {@link CodeModel}.
+ * <p>
+ * A return-from-method instruction is composite:
+ * {@snippet lang=text :
+ * // @link substring="ReturnInstruction" target="#of(TypeKind)" :
+ * ReturnInstruction(TypeKind typeKind) // @link substring="typeKind" target="#typeKind()"
+ * }
+ * where {@code typeKind} is {@linkplain TypeKind##computational-type
+ * computational} or {@link TypeKind#VOID void}.
  *
+ * @see Opcode.Kind#RETURN
+ * @see CodeBuilder#return_(TypeKind) CodeBuilder::return_
  * @since 24
  */
 public sealed interface ReturnInstruction extends Instruction
         permits AbstractInstruction.UnboundReturnInstruction {
 
     /**
-     * {@return the type of the return instruction}
+     * {@return the {@linkplain TypeKind##computational-type computational type}, including
+     * {@link TypeKind#VOID void}, of the return instruction}
      */
     TypeKind typeKind();
 
     /**
      * {@return a return instruction}
+     * {@code typeKind} is {@linkplain TypeKind#asLoadable() converted} to its
+     * computational type.
      *
      * @param typeKind the type of the return instruction
      */
diff --git a/src/main/java/io/github/dmlloyd/classfile/instruction/StackInstruction.java b/src/main/java/io/github/dmlloyd/classfile/instruction/StackInstruction.java
index be031f4..98b6d69 100644
--- a/src/main/java/io/github/dmlloyd/classfile/instruction/StackInstruction.java
+++ b/src/main/java/io/github/dmlloyd/classfile/instruction/StackInstruction.java
@@ -34,10 +34,17 @@
 
 /**
  * Models a stack manipulation instruction in the {@code code} array of a
- * {@code Code} attribute.  Corresponding opcodes will have a {@code kind} of
+ * {@code Code} attribute.  Corresponding opcodes have a {@linkplain Opcode#kind() kind} of
  * {@link Opcode.Kind#STACK}.  Delivered as a {@link CodeElement} when
  * traversing the elements of a {@link CodeModel}.
+ * <p>
+ * A stack manipulation instruction is composite:
+ * {@snippet lang=text :
+ * // @link substring="StackInstruction" target="#of" :
+ * StackInstruction(Opcode opcode) // @link substring="opcode" target="#opcode()"
+ * }
  *
+ * @see Opcode.Kind#STACK
  * @since 24
  */
 public sealed interface StackInstruction extends Instruction
diff --git a/src/main/java/io/github/dmlloyd/classfile/instruction/StoreInstruction.java b/src/main/java/io/github/dmlloyd/classfile/instruction/StoreInstruction.java
index bb36645..7767785 100644
--- a/src/main/java/io/github/dmlloyd/classfile/instruction/StoreInstruction.java
+++ b/src/main/java/io/github/dmlloyd/classfile/instruction/StoreInstruction.java
@@ -24,6 +24,7 @@
  */
 package io.github.dmlloyd.classfile.instruction;
 
+import io.github.dmlloyd.classfile.CodeBuilder;
 import io.github.dmlloyd.classfile.CodeElement;
 import io.github.dmlloyd.classfile.CodeModel;
 import io.github.dmlloyd.classfile.Instruction;
@@ -36,10 +37,28 @@
 
 /**
  * Models a local variable store instruction in the {@code code} array of a
- * {@code Code} attribute.  Corresponding opcodes will have a {@code kind} of
+ * {@code Code} attribute.  Corresponding opcodes have a {@linkplain Opcode#kind() kind} of
  * {@link Opcode.Kind#STORE}.  Delivered as a {@link CodeElement} when
  * traversing the elements of a {@link CodeModel}.
+ * <p>
+ * A local variable store instruction is composite:
+ * {@snippet lang=text :
+ * // @link substring="StoreInstruction" target="#of(TypeKind, int)" :
+ * StoreInstruction(
+ *     TypeKind typeKind, // @link substring="typeKind" target="#typeKind"
+ *     int slot // @link substring="slot" target="#slot"
+ * )
+ * }
+ * where {@code TypeKind} is {@linkplain TypeKind##computational-type
+ * computational}, and {@code slot} is within {@code [0, 65535]}.
+ * <p>
+ * {@code astore} series of instructions, or {@code reference} type store
+ * instructions, can also operate on the {@link TypeKind##returnAddress
+ * returnAddress} type from discontinued {@linkplain
+ * DiscontinuedInstruction.JsrInstruction jump subroutine instructions}.
  *
+ * @see Opcode.Kind#STORE
+ * @see CodeBuilder#storeLocal CodeBuilder::storeLocal
  * @since 24
  */
 public sealed interface StoreInstruction extends Instruction
@@ -47,16 +66,23 @@ public sealed interface StoreInstruction extends Instruction
 
     /**
      * {@return the local variable slot to store to}
+     * The value is within {@code [0, 65535]}.
      */
     int slot();
 
     /**
-     * {@return the type of the value to be stored}
+     * {@return the {@linkplain TypeKind##computational-type computational type}
+     * of the value to be stored}  The {@link TypeKind#REFERENCE reference}
+     * type store instructions also operate on the {@code returnAddress} type,
+     * which does not apply to {@code reference} type load instructions.
      */
     TypeKind typeKind();
 
     /**
      * {@return a local variable store instruction}
+     * {@code kind} is {@linkplain TypeKind#asLoadable() converted} to its
+     * computational type.
+     * {@code slot} must be within {@code [0, 65535]}.
      *
      * @param kind the type of the value to be stored
      * @param slot the local variable slot to store to
@@ -70,6 +96,20 @@ static StoreInstruction of(TypeKind kind, int slot) {
 
     /**
      * {@return a local variable store instruction}
+     * <p>
+     * The range of {@code slot} is restricted by the {@code op} and its
+     * {@linkplain Opcode#sizeIfFixed() size}:
+     * <ul>
+     * <li>If {@code op} has size 1, {@code slot} must be exactly the slot value
+     * implied by the opcode.
+     * <li>If {@code op} has size 2, {@code slot} must be within {@code [0, 255]}.
+     * <li>If {@code op} has size 4, {@code slot} must be within {@code [0, 65535]}.
+     * </ul>
+     *
+     * @apiNote
+     * The explicit {@code op} argument allows creating {@code wide} or
+     * regular store instructions when the {@code slot} can be encoded
+     * with more optimized store instructions.
      *
      * @param op the opcode for the specific type of store instruction,
      *           which must be of kind {@link Opcode.Kind#STORE}
diff --git a/src/main/java/io/github/dmlloyd/classfile/instruction/SwitchCase.java b/src/main/java/io/github/dmlloyd/classfile/instruction/SwitchCase.java
index f838bb6..9d8181c 100644
--- a/src/main/java/io/github/dmlloyd/classfile/instruction/SwitchCase.java
+++ b/src/main/java/io/github/dmlloyd/classfile/instruction/SwitchCase.java
@@ -29,12 +29,20 @@
 import io.github.dmlloyd.classfile.impl.AbstractInstruction;
 
 /**
- * Models a single case in a {@code lookupswitch} or {@code tableswitch}
- * instruction.
+ * Models a single case in a {@link LookupSwitchInstruction lookupswitch} or
+ * {@link TableSwitchInstruction tableswitch} instruction.
+ * <p>
+ * A switch case is composite:
+ * {@snippet lang=text :
+ * // @link substring="SwitchCase" target="#of" :
+ * SwitchCase(
+ *     int caseValue, // @link substring="caseValue" target="#caseValue"
+ *     Label target // @link substring="target" target="#target"
+ * )
+ * }
  *
  * @see LookupSwitchInstruction
  * @see TableSwitchInstruction
- *
  * @since 24
  */
 public sealed interface SwitchCase
@@ -47,11 +55,10 @@ public sealed interface SwitchCase
     Label target();
 
     /**
-     * Create a {@linkplain SwitchCase}
+     * {@return a new switch case}
      *
      * @param caseValue the integer value for the case
      * @param target the branch target for the case
-     * @return the {@linkplain SwitchCase}
      */
     static SwitchCase of(int caseValue, Label target) {
         return new AbstractInstruction.SwitchCaseImpl(caseValue, target);
diff --git a/src/main/java/io/github/dmlloyd/classfile/instruction/TableSwitchInstruction.java b/src/main/java/io/github/dmlloyd/classfile/instruction/TableSwitchInstruction.java
index 0b33a6d..0ea20c6 100644
--- a/src/main/java/io/github/dmlloyd/classfile/instruction/TableSwitchInstruction.java
+++ b/src/main/java/io/github/dmlloyd/classfile/instruction/TableSwitchInstruction.java
@@ -24,19 +24,45 @@
  */
 package io.github.dmlloyd.classfile.instruction;
 
+import io.github.dmlloyd.classfile.CodeBuilder;
 import io.github.dmlloyd.classfile.CodeElement;
 import io.github.dmlloyd.classfile.CodeModel;
 import io.github.dmlloyd.classfile.Instruction;
 import io.github.dmlloyd.classfile.Label;
+import io.github.dmlloyd.classfile.Opcode;
 import java.util.List;
 
 import io.github.dmlloyd.classfile.impl.AbstractInstruction;
 
 /**
- * Models a {@code tableswitch} instruction in the {@code code} array of a
+ * Models a {@link Opcode#TABLESWITCH tableswitch} instruction in the {@code code} array of a
  * {@code Code} attribute.  Delivered as a {@link CodeElement} when traversing
  * the elements of a {@link CodeModel}.
+ * <p>
+ * A table switch instruction is composite:
+ * {@snippet lang=text :
+ * // @link substring="TableSwitchInstruction" target="#of" :
+ * TableSwitchInstruction(
+ *     int lowValue, // @link substring="int lowValue" target="#lowValue"
+ *     int highValue, // @link substring="int highValue" target="#highValue"
+ *     Label defaultTarget, // @link substring="defaultTarget" target="#defaultTarget"
+ *     List<SwitchCase> cases // @link substring="cases" target="#cases()"
+ * )
+ * }
+ * <p>
+ * When read from {@code class} files, the {@code cases} may omit cases that
+ * duplicate the default target.  The list is sorted ascending by the {@link
+ * SwitchCase#caseValue() caseValue}.
+ * <p>
+ * When writing to {@code class} file, the order in the {@code cases} list does
+ * not matter, as there is only one valid order in the physical representation
+ * of table switch entries.  Treatment of elements in {@code cases} whose value
+ * is less than {@code lowValue} or greater than {@code highValue}, and elements
+ * whose value duplicates that of another, is not specified.
  *
+ * @see Opcode.Kind#TABLE_SWITCH
+ * @see CodeBuilder#tableswitch CodeBuilder::tableswitch
+ * @jvms 6.5.tableswitch <em>tableswitch</em>
  * @since 24
  */
 public sealed interface TableSwitchInstruction extends Instruction
@@ -67,7 +93,8 @@ public sealed interface TableSwitchInstruction extends Instruction
      * @param lowValue the low value of the switch target range, inclusive
      * @param highValue the high value of the switch target range, inclusive
      * @param defaultTarget the default target of the switch
-     * @param cases the cases of the switch
+     * @param cases the cases of the switch; duplicate or out of bound case
+     *              handling is not specified
      */
     static TableSwitchInstruction of(int lowValue, int highValue, Label defaultTarget, List<SwitchCase> cases) {
         return new AbstractInstruction.UnboundTableSwitchInstruction(lowValue, highValue, defaultTarget, cases);
diff --git a/src/main/java/io/github/dmlloyd/classfile/instruction/ThrowInstruction.java b/src/main/java/io/github/dmlloyd/classfile/instruction/ThrowInstruction.java
index 78b3b86..b56a56c 100644
--- a/src/main/java/io/github/dmlloyd/classfile/instruction/ThrowInstruction.java
+++ b/src/main/java/io/github/dmlloyd/classfile/instruction/ThrowInstruction.java
@@ -24,17 +24,23 @@
  */
 package io.github.dmlloyd.classfile.instruction;
 
+import io.github.dmlloyd.classfile.CodeBuilder;
 import io.github.dmlloyd.classfile.CodeElement;
 import io.github.dmlloyd.classfile.CodeModel;
 import io.github.dmlloyd.classfile.Instruction;
+import io.github.dmlloyd.classfile.Opcode;
 
 import io.github.dmlloyd.classfile.impl.AbstractInstruction;
 
 /**
- * Models an {@code athrow} instruction in the {@code code} array of a
+ * Models an {@link Opcode#ATHROW athrow} instruction in the {@code code} array of a
  * {@code Code} attribute.  Delivered as a {@link CodeElement} when traversing
  * the elements of a {@link CodeModel}.
+ * <p>
+ * A throw instruction has no visible state.
  *
+ * @see Opcode.Kind#THROW_EXCEPTION
+ * @see CodeBuilder#athrow CodeBuiler::athrow
  * @since 24
  */
 public sealed interface ThrowInstruction extends Instruction
diff --git a/src/main/java/io/github/dmlloyd/classfile/instruction/TypeCheckInstruction.java b/src/main/java/io/github/dmlloyd/classfile/instruction/TypeCheckInstruction.java
index 3660f55..8b2fe43 100644
--- a/src/main/java/io/github/dmlloyd/classfile/instruction/TypeCheckInstruction.java
+++ b/src/main/java/io/github/dmlloyd/classfile/instruction/TypeCheckInstruction.java
@@ -36,9 +36,24 @@
 import io.github.dmlloyd.classfile.impl.Util;
 
 /**
- * Models an {@code instanceof} or {@code checkcast} instruction in the {@code
- * code} array of a {@code Code} attribute.  Delivered as a {@link CodeElement}
- * when traversing the elements of a {@link CodeModel}.
+ * Models an {@link Opcode#INSTANCEOF instanceof} or a {@link Opcode#CHECKCAST checkcast}
+ * instruction in the {@code code} array of a {@code Code} attribute.  Corresponding
+ * opcodes have a {@linkplain Opcode#kind() kind} of {@link Opcode.Kind#TYPE_CHECK}.
+ * Delivered as a {@link CodeElement} when traversing the elements of a {@link CodeModel}.
+ * <p>
+ * An {@code instanceof} checks the type and pushes an integer to the operand stack.
+ * A {@code checkcast} checks the type and throws a {@link ClassCastException} if
+ * the check fails.  {@code instanceof} treat the {@code null} reference as a
+ * failure, while {@code checkcast} treat the {@code null} reference as a success.
+ * <p>
+ * A type check instruction is composite:
+ * {@snippet lang=text :
+ * // @link substring="TypeCheckInstruction" target="#of(Opcode, ClassEntry)" :
+ * TypeCheckInstruction(
+ *     Opcode opcode, // @link substring="opcode" target="#opcode"
+ *     ClassEntry type // @link substring="type" target="#type"
+ * )
+ * }
  *
  * @since 24
  */
@@ -47,7 +62,7 @@ public sealed interface TypeCheckInstruction extends Instruction
                 AbstractInstruction.UnboundTypeCheckInstruction {
 
     /**
-     * {@return the type against which the instruction checks or casts}
+     * {@return the type against which the instruction checks}
      */
     ClassEntry type();
 
@@ -58,7 +73,7 @@ public sealed interface TypeCheckInstruction extends Instruction
      *           which must be of kind {@link Opcode.Kind#TYPE_CHECK}
      * @param type the type against which to check or cast
      * @throws IllegalArgumentException if the opcode kind is not
-     *         {@link Opcode.Kind#TYPE_CHECK}.
+     *         {@link Opcode.Kind#TYPE_CHECK}
      */
     static TypeCheckInstruction of(Opcode op, ClassEntry type) {
         Util.checkKind(op, Opcode.Kind.TYPE_CHECK);
@@ -71,6 +86,8 @@ static TypeCheckInstruction of(Opcode op, ClassEntry type) {
      * @param op the opcode for the specific type of type check instruction,
      *           which must be of kind {@link Opcode.Kind#TYPE_CHECK}
      * @param type the type against which to check or cast
+     * @throws IllegalArgumentException if the opcode kind is not
+     *         {@link Opcode.Kind#TYPE_CHECK}, or if {@code type} is primitive
      */
     static TypeCheckInstruction of(Opcode op, ClassDesc type) {
         return of(op, TemporaryConstantPool.INSTANCE.classEntry(type));
diff --git a/src/main/java/io/github/dmlloyd/classfile/instruction/package-info.java b/src/main/java/io/github/dmlloyd/classfile/instruction/package-info.java
index 9a19d3e..c03d2c2 100644
--- a/src/main/java/io/github/dmlloyd/classfile/instruction/package-info.java
+++ b/src/main/java/io/github/dmlloyd/classfile/instruction/package-info.java
@@ -26,9 +26,45 @@
 /**
  * <h2>Provides interfaces describing code instructions for the {@link io.github.dmlloyd.classfile} library.</h2>
  *
- * The {@code io.github.dmlloyd.classfile.attribute} package contains interfaces describing code instructions.
+ * The {@code io.github.dmlloyd.classfile.instruction} package contains interfaces describing code instructions.
+ * Implementations of these interfaces are immutable.
+ * <p>
+ * Unless otherwise specified, passing {@code null} or an array or collection containing a {@code null} element as an
+ * argument to a constructor or method of any Class-File API class or interface will cause a {@link NullPointerException}
+ * to be thrown.
  *
+ * <h2 id="reading">Reading of instructions</h2>
+ * Instructions and pseudo-instructions are usually accessed from a {@link CodeModel}, such as {@link CodeModel#forEach
+ * CodeModel::forEach}, and categorized by pattern-matching.
+ * <p>
+ * When read from {@code class} files, instructions are lazily inflated; the contents of these instructions, besides the
+ * bare structure, are not evaluated to speed up parsing.  Instructions to users interest, such as those filtered by the
+ * pattern matching, have their contents read on demand, to avoid unnecessary reading of unrelated instructions in a code
+ * array.
+ * <p>
+ * Due to the lazy nature of {@code class} file parsing, {@link IllegalArgumentException} indicating malformed
+ * {@code class} file data can be thrown at any method invocation.  For example, an instruction object for a {@link
+ * TypeCheckInstruction} may be obtained from a {@code CodeModel}, but the subsequent invocation of {@link
+ * TypeCheckInstruction#type() .type()} may fail with {@code IllegalArgumentException} because the instruction refers
+ * to a bad constant pool index.
+ *
+ * <h2 id="writing">Writing of instructions</h2>
+ * Writing of instructions happen on {@link CodeBuilder}.  The most basic way to write instructions is to pass an
+ * instruction object to {@link CodeBuilder#with CodeBuilder::with}, which supports all valid instructions.
+ * Yet, {@code CodeBuilder} provides a lot of {@linkplain CodeBuilder##instruction-factories convenience factory methods}
+ * for easy creation of instructions, named by their mnemonic.  These accessors are more concise, and often more
+ * efficient at run-time than passing instruction objects.
+ * <p>
+ * Due to restrictions in the {@code class} file format, some instructions may not be representable in a {@code CodeBuilder}.
+ * In some scenarios, such as for {@link BranchInstruction}, Class-File API options control if alternatives can be used
+ * in code generation instead.  Otherwise, they can be configured to fail-fast to ensure the parity of {@code CodeBuilder}
+ * commands with the generated {@code code} array data.
+ *
+ * @jvms 6.5 Instructions
  * @since 24
  */
 package io.github.dmlloyd.classfile.instruction;
 
+import io.github.dmlloyd.classfile.CodeBuilder;
+import io.github.dmlloyd.classfile.CodeModel;
+