Avoid using "record", other cleans

src/java.base/share/classes/java/lang/classfile/instruction/ArrayLoadInstruction.java

@@ -40,7 +40,7 @@
  * of {@link Opcode.Kind#ARRAY_LOAD}.  Delivered as a {@link CodeElement} when
  * traversing the elements of a {@link CodeModel}.
  * <p>
- * An array load instruction can be viewed as a record:
+ * An array load instruction is composite:
  * {@snippet lang=text :
  * // @link substring="ArrayLoadInstruction" target="CodeBuilder#arrayLoad(TypeKind)" :
  * ArrayLoadInstruction(TypeKind typeKind) // @link substring="typeKind" target="#typeKind"

src/java.base/share/classes/java/lang/classfile/instruction/ArrayStoreInstruction.java

@@ -40,7 +40,7 @@
  * of {@link Opcode.Kind#ARRAY_STORE}.  Delivered as a {@link CodeElement} when
  * traversing the elements of a {@link CodeModel}.
  * <p>
- * An array store instruction can be viewed as a record:
+ * An array store instruction is composite:
  * {@snippet lang=text :
  * // @link substring="ArrayStoreInstruction" target="CodeBuilder#arrayStore(TypeKind)" :
  * ArrayStoreInstruction(TypeKind typeKind) // @link substring="typeKind" target="#typeKind"

src/java.base/share/classes/java/lang/classfile/instruction/BranchInstruction.java

@@ -35,12 +35,12 @@
  * {@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 can be viewed as a record:
+ * 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="Label" target="#target()"
+ *     Opcode opcode, // @link substring="opcode" target="#opcode()"
+ *     Label target // @link substring="target" target="#target()"
  * )
  * }
  * <p>

src/java.base/share/classes/java/lang/classfile/instruction/CharacterRange.java

@@ -42,7 +42,7 @@
  * {@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 can be viewed a record:
+ * A character range entry is composite:
  * {@snippet lang=text :
  * // @link substring="CharacterRange" target="#of":
  * CharacterRange(

src/java.base/share/classes/java/lang/classfile/instruction/ConstantInstruction.java

@@ -46,7 +46,7 @@
  * Opcode.Kind#CONSTANT}.  Delivered as a {@link CodeElement} when traversing
  * the elements of a {@link CodeModel}.
  * <p>
- * A constant-load instruction can be viewed as a record:
+ * 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()"
@@ -76,7 +76,7 @@ public sealed interface ConstantInstruction extends Instruction {
      * Opcode#ACONST_NULL aconst_null} and {@link
      * Opcode#ICONST_0 iconst_0}.
      * <p>
-     * An intrinsic constant instruction can be viewed as a record:
+     * An intrinsic constant instruction is composite:
      * {@snippet lang=text :
      * // @link substring="IntrinsicConstantInstruction" target="#ofIntrinsic" :
      * IntrinsicConstantInstruction(Opcode opcode) // @link substring="opcode" target="#opcode()"
@@ -106,7 +106,7 @@ default TypeKind typeKind() {
      * constant value in the instruction directly. Includes {@link
      * Opcode#BIPUSH bipush} and {@link Opcode#SIPUSH sipush} instructions.
      * <p>
-     * An argument constant instruction can be viewed a record:
+     * An argument constant instruction is composite:
      * {@snippet lang=text :
      * // @link substring="ArgumentConstantInstruction" target="#ofArgument" :
      * ArgumentConstantInstruction(
@@ -143,21 +143,20 @@ default TypeKind typeKind() {
     }
 
     /**
-     * Models a "load constant" instruction, which encodes the  constant value
+     * 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 can be viewed as one of these records:
+     * A load constant instruction is composite:
      * {@snippet lang=text :
-     * // @link substring="LoadConstantInstruction" target="CodeBuilder#ldc(ConstantDesc)" :
-     * LoadConstantInstruction(ConstantDesc constantValue) // @link substring="constantValue" target="#constantValue()"
      * // @link substring="LoadConstantInstruction" target="CodeBuilder#ldc(LoadableConstantEntry)" :
      * LoadConstantInstruction(LoadableConstantEntry constantEntry) // @link substring="constantEntry" target="#constantEntry()"
      * }
      * <p>
-     * Though the generic constant-load model and the "load constant" model both
-     * hold a {@code constantValue}, the generic instruction may be more optimized,
-     * avoiding extra constant pool entries and using smaller-sized instructions.
+     * 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
@@ -198,7 +197,7 @@ 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
+     * 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,

src/java.base/share/classes/java/lang/classfile/instruction/ConvertInstruction.java

@@ -41,7 +41,7 @@
  * 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 can be viewed a record:
+ * A primitive conversion instruction is composite:
  * {@snippet lang=text :
  * // @link substring="ConvertInstruction" target="#of(TypeKind, TypeKind)" :
  * ConvertInstruction(

src/java.base/share/classes/java/lang/classfile/instruction/DiscontinuedInstruction.java

@@ -55,7 +55,7 @@ public sealed interface DiscontinuedInstruction extends Instruction {
      * Delivered as a {@link CodeElement} when traversing the elements of a
      * {@link CodeModel}.
      * <p>
-     * A jump subroutine instruction can be viewed as a record:
+     * A jump subroutine instruction is composite:
      * {@snippet lang=text :
      * // @link substring="JsrInstruction" target="#of(Label)" :
      * JsrInstruction(Label target) // @link substring="target" target="#target()"
@@ -119,7 +119,7 @@ static JsrInstruction of(Label target) {
      * {@link Opcode.Kind#DISCONTINUED_RET}.  Delivered as a {@link CodeElement}
      * when traversing the elements of a {@link CodeModel}.
      * <p>
-     * A return from subroutine instruction can be viewed as a record:
+     * A return from subroutine instruction is composite:
      * {@snippet lang=text :
      * // @link substring="RetInstruction" target="#of(int)" :
      * RetInstruction(int slot) // @link substring="slot" target="#slot()"

src/java.base/share/classes/java/lang/classfile/instruction/ExceptionCatch.java

@@ -42,7 +42,7 @@
  * table entries.  Delivered as a {@link CodeElement} when traversing the
  * contents of a {@link CodeModel}.
  * <p>
- * An exception table entry can be viewed as a record:
+ * An exception table entry is composite:
  * {@snippet lang=text :
  * // @link substring="ExceptionCatch" target="#of(Label, Label, Label, Optional)" :
  * ExceptionCatch(

src/java.base/share/classes/java/lang/classfile/instruction/FieldInstruction.java

@@ -45,7 +45,7 @@
  * of {@link Opcode.Kind#FIELD_ACCESS}.  Delivered as a {@link CodeElement} when
  * traversing the elements of a {@link CodeModel}.
  * <p>
- * A field access instruction can be viewed as a record:
+ * A field access instruction is composite:
  * {@snippet lang=text :
  * // @link substring="FieldInstruction" target="#of(Opcode, FieldRefEntry)" :
  * FieldInstruction(

src/java.base/share/classes/java/lang/classfile/instruction/IncrementInstruction.java

@@ -38,7 +38,7 @@
  * 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 can be viewed as a record:
+ * A local variable increment instruction is composite:
  * {@snippet lang=text :
  * // @link substring="IncrementInstruction" target="#of" :
  * IncrementInstruction(

src/java.base/share/classes/java/lang/classfile/instruction/InvokeDynamicInstruction.java

@@ -47,8 +47,7 @@
  * {@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 can be viewed as a
- * record:
+ * 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()"

src/java.base/share/classes/java/lang/classfile/instruction/InvokeInstruction.java

@@ -48,7 +48,7 @@
  * 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 can be viewed as a record:
+ * A method invocation instruction is composite:
  * {@snippet lang=text :
  * // @link substring="InvokeInstruction" target="#of(Opcode, MemberRefEntry)" :
  * InvokeInstruction(

src/java.base/share/classes/java/lang/classfile/instruction/LineNumber.java

@@ -43,7 +43,7 @@
  * elements of a {@link CodeModel}, according to the setting of the {@link
  * ClassFile.LineNumbersOption} option.
  * <p>
- * A line number entry can be viewed as a record:
+ * A line number entry is composite:
  * {@snippet lang=text :
  * // @link substring="LineNumber" target="#of" :
  * LineNumber(int line) // @link substring="int line" target="#line"

src/java.base/share/classes/java/lang/classfile/instruction/LoadInstruction.java

@@ -41,7 +41,7 @@
  * 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 can be viewed as a record:
+ * A local variable load instruction is composite:
  * {@snippet lang=text :
  * // @link substring="LoadInstruction" target="#of(TypeKind, int)" :
  * LoadInstruction(

src/java.base/share/classes/java/lang/classfile/instruction/LocalVariable.java

@@ -46,7 +46,7 @@
  * {@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 can be viewed a record:
+ * A local variable entry is composite:
  * {@snippet lang=text :
  * // @link substring="LocalVariable" target="#of(int, String, ClassDesc, Label, Label)" :
  * LocalVariable(

src/java.base/share/classes/java/lang/classfile/instruction/LocalVariableType.java

@@ -39,7 +39,7 @@
  * 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 can be viewed as a record:
+ * A local variable type entry is composite:
  * {@snippet lang=text :
  * // @link substring="LocalVariableType" target="#of(int, String, Signature, Label, Label)" :
  * LocalVariableType(

src/java.base/share/classes/java/lang/classfile/instruction/LookupSwitchInstruction.java

@@ -39,7 +39,7 @@
  * 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 can be viewed as a record:
+ * A lookup switch instruction is composite:
  * {@snippet lang=text :
  * // @link substring="LookupSwitchInstruction" target="#of" :
  * LookupSwitchInstruction(

src/java.base/share/classes/java/lang/classfile/instruction/MonitorInstruction.java

@@ -40,7 +40,7 @@
  * Opcode.Kind#MONITOR}.  Delivered as a {@link CodeElement} when traversing the
  * elements of a {@link CodeModel}.
  * <p>
- * A monitor instruction can be viewed record:
+ * A monitor instruction is composite:
  * {@snippet lang=text :
  * // @link substring="MonitorInstruction" target="#of(Opcode)" :
  * MonitorInstruction(Opcode opcode) // @link substring="opcode" target="#opcode"

src/java.base/share/classes/java/lang/classfile/instruction/NewMultiArrayInstruction.java

@@ -39,7 +39,7 @@
  * 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 can be viewed as a record:
+ * A new multi-dimensional array instruction is composite:
  * {@snippet lang=text :
  * // @link substring="NewMultiArrayInstruction" target="#of" :
  * NewMultiArrayInstruction(

src/java.base/share/classes/java/lang/classfile/instruction/NewObjectInstruction.java

@@ -38,7 +38,7 @@
  * attribute.  Delivered as a {@link CodeElement} when traversing the elements
  * of a {@link CodeModel}.
  * <p>
- * A new object instruction can be viewed as a record:
+ * A new object instruction is composite:
  * {@snippet lang=text :
  * // @link substring="NewObjectInstruction" target="#of" :
  * NewObjectInstruction(ClassEntry className) // @link substring="className" target="#className"

src/java.base/share/classes/java/lang/classfile/instruction/NewPrimitiveArrayInstruction.java

@@ -38,7 +38,7 @@
  * 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 can be viewed as a record:
+ * A new primitive array instruction is composite:
  * {@snippet lang=text :
  * // @link substring="NewPrimitiveArrayInstruction" target="#of" :
  * NewPrimitiveArrayInstruction(TypeKind typeKind) // @link substring="typeKind" target="#typeKind"

src/java.base/share/classes/java/lang/classfile/instruction/NewReferenceArrayInstruction.java

@@ -38,7 +38,7 @@
  * 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 can be viewed as a record:
+ * A new reference array instruction is composite:
  * {@snippet lang=text :
  * // @link substring="NewReferenceArrayInstruction" target="#of" :
  * NewReferenceArrayInstruction(ClassEntry componentType) // @link substring="componentType" target="#componentType"

src/java.base/share/classes/java/lang/classfile/instruction/NopInstruction.java

@@ -37,11 +37,7 @@
  * array of a {@code Code} attribute.  Delivered as a {@link CodeElement}
  * when traversing the elements of a {@link CodeModel}.
  * <p>
- * A no-op instruction can be viewed as a record:
- * {@snippet lang=text :
- * // @link substring="NopInstruction" target="#of" :
- * NopInstruction()
- * }
+ * A no-op instruction has no visible state.
  *
  * @see CodeBuilder#nop CodeBuilder::nop
  * @jvms 6.5.nop <em>nop</em>

src/java.base/share/classes/java/lang/classfile/instruction/OperatorInstruction.java

@@ -39,7 +39,7 @@
  * {@link Opcode.Kind#OPERATOR}.  Delivered as a {@link CodeElement} when
  * traversing the elements of a {@link CodeModel}.
  * <p>
- * An operator instruction can be viewed as a record:
+ * An operator instruction is composite:
  * {@snippet lang=text :
  * // @link substring="OperatorInstruction" target="#of" :
  * OperatorInstruction(Opcode opcode) // @link substring="opcode" target="#opcode()"

src/java.base/share/classes/java/lang/classfile/instruction/ReturnInstruction.java

@@ -41,7 +41,7 @@
  * {@link Opcode.Kind#RETURN}.  Delivered as a {@link CodeElement} when
  * traversing the elements of a {@link CodeModel}.
  * <p>
- * A return-from-method instruction can be viewed a record:
+ * A return-from-method instruction is composite:
  * {@snippet lang=text :
  * // @link substring="ReturnInstruction" target="#of(TypeKind)" :
  * ReturnInstruction(TypeKind typeKind) // @link substring="typeKind" target="#typeKind()"

src/java.base/share/classes/java/lang/classfile/instruction/StackInstruction.java

@@ -38,7 +38,7 @@
  * {@link Opcode.Kind#STACK}.  Delivered as a {@link CodeElement} when
  * traversing the elements of a {@link CodeModel}.
  * <p>
- * A stack manipulation instruction can be viewed as a record:
+ * A stack manipulation instruction is composite:
  * {@snippet lang=text :
  * // @link substring="StackInstruction" target="#of" :
  * StackInstruction(Opcode opcode) // @link substring="opcode" target="#opcode()"

src/java.base/share/classes/java/lang/classfile/instruction/StoreInstruction.java

@@ -41,7 +41,7 @@
  * {@link Opcode.Kind#STORE}.  Delivered as a {@link CodeElement} when
  * traversing the elements of a {@link CodeModel}.
  * <p>
- * A local variable store instruction can be viewed as a record:
+ * A local variable store instruction is composite:
  * {@snippet lang=text :
  * // @link substring="StoreInstruction" target="#of(TypeKind, int)" :
  * StoreInstruction(

src/java.base/share/classes/java/lang/classfile/instruction/SwitchCase.java

@@ -32,7 +32,7 @@
  * Models a single case in a {@link LookupSwitchInstruction lookupswitch} or
  * {@link TableSwitchInstruction tableswitch} instruction.
  * <p>
- * A switch case can be viewed as a record:
+ * A switch case is composite:
  * {@snippet lang=text :
  * // @link substring="SwitchCase" target="#of" :
  * SwitchCase(

src/java.base/share/classes/java/lang/classfile/instruction/TableSwitchInstruction.java

@@ -39,7 +39,7 @@
  * {@code Code} attribute.  Delivered as a {@link CodeElement} when traversing
  * the elements of a {@link CodeModel}.
  * <p>
- * A table switch instruction can be viewed a record:
+ * A table switch instruction is composite:
  * {@snippet lang=text :
  * // @link substring="TableSwitchInstruction" target="#of" :
  * TableSwitchInstruction(

src/java.base/share/classes/java/lang/classfile/instruction/ThrowInstruction.java

@@ -37,11 +37,7 @@
  * {@code Code} attribute.  Delivered as a {@link CodeElement} when traversing
  * the elements of a {@link CodeModel}.
  * <p>
- * A throw instruction can be viewed as a record:
- * {@snippet lang=text :
- * // @link substring="ThrowInstruction" target="#of" :
- * ThrowInstruction()
- * }
+ * A throw instruction has no visible state.
  *
  * @see Opcode.Kind#THROW_EXCEPTION
  * @see CodeBuilder#athrow CodeBuiler::athrow

src/java.base/share/classes/java/lang/classfile/instruction/TypeCheckInstruction.java

@@ -41,11 +41,12 @@
  * 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 a value to the operand stack.
+ * 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.
+ * 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 can be viewed as a record:
+ * A type check instruction is composite:
  * {@snippet lang=text :
  * // @link substring="TypeCheckInstruction" target="#of(Opcode, ClassEntry)" :
  * TypeCheckInstruction(

src/java.base/share/classes/java/lang/classfile/instruction/package-info.java

@@ -27,6 +27,7 @@
  * <h2>Provides interfaces describing code instructions for the {@link java.lang.classfile} library.</h2>
  *
  * The {@code java.lang.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}