8338014: Improve usage of @jvms tags in class file API

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

@@ -66,7 +66,7 @@
 import jdk.internal.javac.PreviewFeature;
 
 /**
- * Models a classfile attribute JVMS {@jvms 4.7}.  Many, though not all, subtypes of
+ * Models a classfile attribute (JVMS {@jvms 4.7}).  Many, though not all, subtypes of
  * {@linkplain Attribute} will implement {@link ClassElement}, {@link
  * MethodElement}, {@link FieldElement}, or {@link CodeElement}; attributes that
  * are also elements will be delivered when traversing the elements of the

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

@@ -60,7 +60,7 @@
 import jdk.internal.javac.PreviewFeature;
 
 /**
- * Models an annotation on a type use, as defined in JVMS {@jvms 4.7.19} and JVMS {@jvms 4.7.20}.
+ * Models an annotation on a type use, as defined in JVMS {@jvms 4.7.19} and {@jvms 4.7.20}.
  *
  * @see RuntimeVisibleTypeAnnotationsAttribute
  * @see RuntimeInvisibleTypeAnnotationsAttribute

src/java.base/share/classes/java/lang/classfile/attribute/AnnotationDefaultAttribute.java

@@ -34,7 +34,7 @@
 import jdk.internal.javac.PreviewFeature;
 
 /**
- * Models the {@code AnnotationDefault} attribute JVMS {@jvms 4.7.22}, which can
+ * Models the {@code AnnotationDefault} attribute (JVMS {@jvms 4.7.22}), which can
  * appear on methods of annotation types, and records the default value
  * {@jls 9.6.2} for the element corresponding to this method.  Delivered as a
  * {@link MethodElement} when traversing the elements of a {@link MethodModel}.

src/java.base/share/classes/java/lang/classfile/attribute/BootstrapMethodsAttribute.java

@@ -35,7 +35,7 @@
 import jdk.internal.javac.PreviewFeature;
 
 /**
- * Models the {@code BootstrapMethods} attribute JVMS {@jvms 4.7.23}, which serves as
+ * Models the {@code BootstrapMethods} attribute (JVMS {@jvms 4.7.23}), which serves as
  * an extension to the constant pool of a classfile.  Elements of the bootstrap
  * method table are accessed through {@link ConstantPool}.
  * <p>

src/java.base/share/classes/java/lang/classfile/attribute/CodeAttribute.java

@@ -32,7 +32,7 @@
 import jdk.internal.javac.PreviewFeature;
 
 /**
- * Models the {@code Code} attribute JVMS {@jvms 4.7.3}, appears on non-native,
+ * Models the {@code Code} attribute (JVMS {@jvms 4.7.3}), appears on non-native,
  * non-abstract methods and contains the bytecode of the method body.  Delivered
  * as a {@link java.lang.classfile.MethodElement} when traversing the elements of a
  * {@link java.lang.classfile.MethodModel}.

src/java.base/share/classes/java/lang/classfile/attribute/ConstantValueAttribute.java

@@ -34,7 +34,7 @@
 import jdk.internal.javac.PreviewFeature;
 
 /**
- * Models the {@code ConstantValue} attribute JVMS {@jvms 4.7.2}, which can appear on
+ * Models the {@code ConstantValue} attribute (JVMS {@jvms 4.7.2}), which can appear on
  * fields and indicates that the field's value is a constant.  Delivered as a
  * {@link java.lang.classfile.FieldElement} when traversing the elements of a
  * {@link java.lang.classfile.FieldModel}.

src/java.base/share/classes/java/lang/classfile/attribute/DeprecatedAttribute.java

@@ -33,7 +33,7 @@
 import jdk.internal.javac.PreviewFeature;
 
 /**
- * Models the {@code Deprecated} attribute JVMS {@jvms 4.7.15}, which can appear on
+ * Models the {@code Deprecated} attribute (JVMS {@jvms 4.7.15}), which can appear on
  * classes, methods, and fields.  Delivered as a  {@link ClassElement},
  * {@link MethodElement}, or  {@link FieldElement} when traversing the elements
  * of a corresponding model.

src/java.base/share/classes/java/lang/classfile/attribute/EnclosingMethodAttribute.java

@@ -40,7 +40,7 @@
 import jdk.internal.javac.PreviewFeature;
 
 /**
- * Models the {@code EnclosingMethod} attribute JVMS {@jvms 4.7.7}, which can appear
+ * Models the {@code EnclosingMethod} attribute (JVMS {@jvms 4.7.7}), which can appear
  * on classes, and indicates that the class is a local or anonymous class.
  * Delivered as a {@link ClassElement} when traversing the elements of a {@link
  * java.lang.classfile.ClassModel}.

src/java.base/share/classes/java/lang/classfile/attribute/ExceptionsAttribute.java

@@ -37,7 +37,7 @@
 import jdk.internal.javac.PreviewFeature;
 
 /**
- * Models the {@code Exceptions} attribute JVMS {@jvms 4.7.5}, which can appear on
+ * Models the {@code Exceptions} attribute (JVMS {@jvms 4.7.5}), which can appear on
  * methods, and records the exceptions declared to be thrown by this method.
  * Delivered as a {@link MethodElement} when traversing the elements of a
  * {@link java.lang.classfile.MethodModel}.

src/java.base/share/classes/java/lang/classfile/attribute/InnerClassesAttribute.java

@@ -34,7 +34,7 @@
 import jdk.internal.javac.PreviewFeature;
 
 /**
- * Models the {@code InnerClasses} attribute JVMS {@jvms 4.7.6}, which can
+ * Models the {@code InnerClasses} attribute (JVMS {@jvms 4.7.6}), which can
  * appear on classes, and records which classes referenced by this classfile
  * are inner classes. Delivered as a {@link java.lang.classfile.ClassElement} when
  * traversing the elements of a {@link java.lang.classfile.ClassModel}.

src/java.base/share/classes/java/lang/classfile/attribute/LineNumberTableAttribute.java

@@ -32,7 +32,7 @@
 import jdk.internal.javac.PreviewFeature;
 
 /**
- * Models the {@code LineNumberTable} attribute JVMS {@jvms 4.7.12}, which can appear
+ * Models the {@code LineNumberTable} attribute (JVMS {@jvms 4.7.12}), which can appear
  * on a {@code Code} attribute, and records the mapping between indexes into
  * the code table and line numbers in the source file.
  * Delivered as a {@link java.lang.classfile.instruction.LineNumber} when traversing the

src/java.base/share/classes/java/lang/classfile/attribute/LocalVariableTableAttribute.java

@@ -32,7 +32,7 @@
 import jdk.internal.javac.PreviewFeature;
 
 /**
- * Models the {@code LocalVariableTable} attribute JVMS {@jvms 4.7.13}, which can appear
+ * Models the {@code LocalVariableTable} attribute (JVMS {@jvms 4.7.13}), which can appear
  * on a {@code Code} attribute, and records debug information about local
  * variables.
  * Delivered as a {@link java.lang.classfile.instruction.LocalVariable} when traversing the

src/java.base/share/classes/java/lang/classfile/attribute/LocalVariableTypeTableAttribute.java

@@ -33,7 +33,7 @@
 import jdk.internal.javac.PreviewFeature;
 
 /**
- * Models the {@code LocalVariableTypeTable} attribute JVMS {@jvms 4.7.14}, which can appear
+ * Models the {@code LocalVariableTypeTable} attribute (JVMS {@jvms 4.7.14}), which can appear
  * on a {@code Code} attribute, and records debug information about local
  * variables.
  * Delivered as a {@link java.lang.classfile.instruction.LocalVariable} when traversing the

src/java.base/share/classes/java/lang/classfile/attribute/MethodParametersAttribute.java

@@ -34,7 +34,7 @@
 import jdk.internal.javac.PreviewFeature;
 
 /**
- * Models the {@code MethodParameters} attribute JVMS {@jvms 4.7.24}, which can
+ * Models the {@code MethodParameters} attribute (JVMS {@jvms 4.7.24}), which can
  * appear on methods, and records optional information about the method's
  * parameters.  Delivered as a {@link java.lang.classfile.MethodElement} when
  * traversing the elements of a {@link java.lang.classfile.MethodModel}.

src/java.base/share/classes/java/lang/classfile/attribute/ModuleAttribute.java

@@ -46,7 +46,7 @@
 import jdk.internal.javac.PreviewFeature;
 
 /**
- * Models the {@code Module} attribute JVMS {@jvms 4.7.25}, which can
+ * Models the {@code Module} attribute (JVMS {@jvms 4.7.25}), which can
  * appear on classes that represent module descriptors.
  * Delivered as a {@link java.lang.classfile.ClassElement} when
  * traversing the elements of a {@link java.lang.classfile.ClassModel}.

src/java.base/share/classes/java/lang/classfile/attribute/ModuleMainClassAttribute.java

@@ -35,7 +35,7 @@
 import jdk.internal.javac.PreviewFeature;
 
 /**
- * Models the {@code ModuleMainClass} attribute JVMS {@jvms 4.7.27}, which can
+ * Models the {@code ModuleMainClass} attribute (JVMS {@jvms 4.7.27}), which can
  * appear on classes that represent module descriptors.
  * Delivered as a {@link java.lang.classfile.ClassElement} when
  * traversing the elements of a {@link java.lang.classfile.ClassModel}.

src/java.base/share/classes/java/lang/classfile/attribute/ModulePackagesAttribute.java

@@ -38,7 +38,7 @@
 import jdk.internal.javac.PreviewFeature;
 
 /**
- * Models the {@code ModulePackages} attribute JVMS {@jvms 4.7.26}, which can
+ * Models the {@code ModulePackages} attribute (JVMS {@jvms 4.7.26}), which can
  * appear on classes that represent module descriptors.
  * Delivered as a {@link java.lang.classfile.ClassElement} when
  * traversing the elements of a {@link java.lang.classfile.ClassModel}.

src/java.base/share/classes/java/lang/classfile/attribute/NestHostAttribute.java

@@ -35,7 +35,7 @@
 import jdk.internal.javac.PreviewFeature;
 
 /**
- * Models the {@code NestHost} attribute JVMS {@jvms 4.7.28}, which can
+ * Models the {@code NestHost} attribute (JVMS {@jvms 4.7.28}), which can
  * appear on classes to indicate that this class is a member of a nest.
  * Delivered as a {@link java.lang.classfile.ClassElement} when
  * traversing the elements of a {@link java.lang.classfile.ClassModel}.

src/java.base/share/classes/java/lang/classfile/attribute/NestMembersAttribute.java

@@ -37,7 +37,7 @@
 import jdk.internal.javac.PreviewFeature;
 
 /**
- * Models the {@code NestMembers} attribute JVMS {@jvms 4.7.29}, which can
+ * Models the {@code NestMembers} attribute (JVMS {@jvms 4.7.29}), which can
  * appear on classes to indicate that this class is the host of a nest.
  * Delivered as a {@link java.lang.classfile.ClassElement} when
  * traversing the elements of a {@link java.lang.classfile.ClassModel}.

src/java.base/share/classes/java/lang/classfile/attribute/PermittedSubclassesAttribute.java

@@ -37,7 +37,7 @@
 import jdk.internal.javac.PreviewFeature;
 
 /**
- * Models the {@code PermittedSubclasses} attribute JVMS {@jvms 4.7.31}, which can
+ * Models the {@code PermittedSubclasses} attribute (JVMS {@jvms 4.7.31}), which can
  * appear on classes to indicate which classes may extend this class.
  * Delivered as a {@link java.lang.classfile.ClassElement} when
  * traversing the elements of a {@link java.lang.classfile.ClassModel}.

src/java.base/share/classes/java/lang/classfile/attribute/RecordAttribute.java

@@ -34,7 +34,7 @@
 import jdk.internal.javac.PreviewFeature;
 
 /**
- * Models the {@code Record} attribute JVMS {@jvms 4.7.30}, which can
+ * Models the {@code Record} attribute (JVMS {@jvms 4.7.30}), which can
  * appear on classes to indicate that this class is a record class.
  * Delivered as a {@link java.lang.classfile.ClassElement} when
  * traversing the elements of a {@link java.lang.classfile.ClassModel}.

src/java.base/share/classes/java/lang/classfile/attribute/RuntimeInvisibleAnnotationsAttribute.java

@@ -33,7 +33,7 @@
 import jdk.internal.javac.PreviewFeature;
 
 /**
- * Models the {@code RuntimeInvisibleAnnotations} attribute JVMS {@jvms 4.7.17}, which
+ * Models the {@code RuntimeInvisibleAnnotations} attribute (JVMS {@jvms 4.7.17}), which
  * can appear on classes, methods, and fields. Delivered as a
  * {@link java.lang.classfile.ClassElement}, {@link java.lang.classfile.FieldElement}, or
  * {@link java.lang.classfile.MethodElement} when traversing the corresponding model type.

src/java.base/share/classes/java/lang/classfile/attribute/RuntimeInvisibleParameterAnnotationsAttribute.java

@@ -37,7 +37,7 @@
 
 /**
  * Models the {@code RuntimeInvisibleParameterAnnotations} attribute
- * JVMS {@jvms 4.7.19}, which can appear on methods. Delivered as a {@link
+ * (JVMS {@jvms 4.7.19}), which can appear on methods. Delivered as a {@link
  * java.lang.classfile.MethodElement} when traversing a {@link MethodModel}.
  * <p>
  * The attribute does not permit multiple instances in a given location.

src/java.base/share/classes/java/lang/classfile/attribute/RuntimeInvisibleTypeAnnotationsAttribute.java

@@ -38,7 +38,7 @@
 import jdk.internal.javac.PreviewFeature;
 
 /**
- * Models the {@code RuntimeInvisibleTypeAnnotations} attribute JVMS {@jvms 4.7.21}, which
+ * Models the {@code RuntimeInvisibleTypeAnnotations} attribute (JVMS {@jvms 4.7.21}), which
  * can appear on classes, methods, fields, and code attributes. Delivered as a
  * {@link java.lang.classfile.ClassElement}, {@link java.lang.classfile.FieldElement},
  * {@link java.lang.classfile.MethodElement}, or {@link CodeElement} when traversing

src/java.base/share/classes/java/lang/classfile/attribute/RuntimeVisibleAnnotationsAttribute.java

@@ -33,7 +33,7 @@
 import jdk.internal.javac.PreviewFeature;
 
 /**
- * Models the {@code RuntimeVisibleAnnotations} attribute JVMS {@jvms 4.7.16}, which
+ * Models the {@code RuntimeVisibleAnnotations} attribute (JVMS {@jvms 4.7.16}), which
  * can appear on classes, methods, and fields. Delivered as a
  * {@link java.lang.classfile.ClassElement}, {@link java.lang.classfile.FieldElement}, or
  * {@link java.lang.classfile.MethodElement} when traversing the corresponding model type.

src/java.base/share/classes/java/lang/classfile/attribute/RuntimeVisibleParameterAnnotationsAttribute.java

@@ -36,7 +36,7 @@
 import jdk.internal.javac.PreviewFeature;
 
 /**
- * Models the {@code RuntimeVisibleParameterAnnotations} attribute JVMS {@jvms 4.7.18}, which
+ * Models the {@code RuntimeVisibleParameterAnnotations} attribute (JVMS {@jvms 4.7.18}), which
  * can appear on methods. Delivered as a {@link java.lang.classfile.MethodElement}
  * when traversing a {@link MethodModel}.
  *

src/java.base/share/classes/java/lang/classfile/attribute/RuntimeVisibleTypeAnnotationsAttribute.java

@@ -38,7 +38,7 @@
 import jdk.internal.javac.PreviewFeature;
 
 /**
- * Models the {@code RuntimeVisibleTypeAnnotations} attribute JVMS {@jvms 4.7.20}, which
+ * Models the {@code RuntimeVisibleTypeAnnotations} attribute (JVMS {@jvms 4.7.20}), which
  * can appear on classes, methods, fields, and code attributes. Delivered as a
  * {@link java.lang.classfile.ClassElement}, {@link java.lang.classfile.FieldElement},
  * {@link java.lang.classfile.MethodElement}, or {@link CodeElement} when traversing

src/java.base/share/classes/java/lang/classfile/attribute/SignatureAttribute.java

@@ -39,7 +39,7 @@
 import jdk.internal.javac.PreviewFeature;
 
 /**
- * Models the {@code Signature} attribute JVMS {@jvms 4.7.9}, which
+ * Models the {@code Signature} attribute (JVMS {@jvms 4.7.9}), which
  * can appear on classes, methods, or fields. Delivered as a
  * {@link java.lang.classfile.ClassElement}, {@link java.lang.classfile.FieldElement}, or
  * {@link java.lang.classfile.MethodElement} when traversing

src/java.base/share/classes/java/lang/classfile/attribute/SourceFileAttribute.java

@@ -35,7 +35,7 @@
 import jdk.internal.javac.PreviewFeature;
 
 /**
- * Models the {@code SourceFile} attribute JVMS {@jvms 4.7.10}, which
+ * Models the {@code SourceFile} attribute (JVMS {@jvms 4.7.10}), which
  * can appear on classes. Delivered as a {@link java.lang.classfile.ClassElement}
  * when traversing a {@link ClassModel}.
  * <p>

src/java.base/share/classes/java/lang/classfile/attribute/StackMapFrameInfo.java

@@ -36,7 +36,7 @@
 import jdk.internal.javac.PreviewFeature;
 
 /**
- * Models stack map frame of {@code StackMapTable} attribute JVMS {@jvms 4.7.4}.
+ * Models stack map frame of {@code StackMapTable} attribute (JVMS {@jvms 4.7.4}).
  *
  * @since 22
  */

src/java.base/share/classes/java/lang/classfile/attribute/StackMapTableAttribute.java

@@ -34,7 +34,7 @@
 import jdk.internal.javac.PreviewFeature;
 
 /**
- * Models the {@code StackMapTable} attribute JVMS {@jvms 4.7.4}, which can appear
+ * Models the {@code StackMapTable} attribute (JVMS {@jvms 4.7.4}), which can appear
  * on a {@code Code} attribute.
  * <p>
  * The attribute does not permit multiple instances in a given location.

src/java.base/share/classes/java/lang/classfile/attribute/SyntheticAttribute.java

@@ -34,7 +34,7 @@
 import jdk.internal.javac.PreviewFeature;
 
 /**
- * Models the {@code Synthetic} attribute JVMS {@jvms 4.7.8}, which can appear on
+ * Models the {@code Synthetic} attribute (JVMS {@jvms 4.7.8}), which can appear on
  * classes, methods, and fields.  Delivered as a  {@link ClassElement},
  * {@link MethodElement}, or  {@link FieldElement} when traversing the elements
  * of a corresponding model.

src/java.base/share/classes/java/lang/classfile/constantpool/ConstantPoolBuilder.java

@@ -365,7 +365,7 @@ default MethodHandleEntry methodHandleEntry(DirectMethodHandleDesc descriptor) {
      * it is returned; otherwise, a new entry is added and the new entry is
      * returned.
      *
-     * @param refKind the reference kind of the method handle JVMS {@jvms 4.4.8}
+     * @param refKind the reference kind of the method handle (JVMS {@jvms 4.4.8})
      * @param reference the constant pool entry describing the field or method
      */
     MethodHandleEntry methodHandleEntry(int refKind, MemberRefEntry reference);

src/java.base/share/classes/java/lang/classfile/constantpool/MethodHandleEntry.java

@@ -48,7 +48,7 @@ default ConstantDesc constantValue() {
     }
 
     /**
-     * {@return the reference kind of this method handle JVMS {@jvms 4.4.8}}
+     * {@return the reference kind of this method handle (JVMS {@jvms 4.4.8})}
      * @see java.lang.invoke.MethodHandleInfo
      */
     int kind();

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

@@ -26,7 +26,7 @@
 /**
  * <h2>Provides classfile parsing, generation, and transformation library.</h2>
  * The {@code java.lang.classfile} package contains classes for reading, writing, and
- * modifying Java class files, as specified in Chapter JVMS {@jvms 4} of the
+ * modifying Java class files, as specified in Chapter {@jvms 4} of the
  * <cite>Java Virtual Machine Specification</cite>.
  *
  * <h2>Reading classfiles</h2>
@@ -153,7 +153,7 @@
  * same kind are allowed on a single entity.
  * <p>
  * There are built-in attribute mappers (in {@link java.lang.classfile.Attributes}) for
- * each of the attribute types defined in section JVMS {@jvms 4.7} of <cite>The Java Virtual
+ * each of the attribute types defined in section {@jvms 4.7} of <cite>The Java Virtual
  * Machine Specification</cite>, as well as several common nonstandard attributes used by the
  * JDK such as {@code CharacterRangeTable}.
  * <p>