From 564e0a20763486cfc7bfce7cb14b2f947c69d8df Mon Sep 17 00:00:00 2001
From: Chen Liang <liach@openjdk.org>
Date: Fri, 24 Jan 2025 14:56:35 +0000
Subject: [PATCH 1/3] 8342466: Improve API documentation for
 java.lang.classfile.attribute 8347762: ClassFile attribute specification
 refers to non-SE modules

Reviewed-by: asotona
Backport-of: 973c630777d4075bc85c7ddc1eb02cc65904344d
---
 .../java/lang/classfile/Annotation.java       |  15 +-
 .../lang/classfile/AnnotationElement.java     |   6 +-
 .../java/lang/classfile/AnnotationValue.java  |   3 +-
 .../java/lang/classfile/Attribute.java        |  42 +++-
 .../java/lang/classfile/AttributeMapper.java  | 197 ++++++++++++++---
 .../lang/classfile/AttributedElement.java     |  35 ++-
 .../java/lang/classfile/Attributes.java       | 162 ++++++--------
 .../java/lang/classfile/BufWriter.java        | 122 +++++++---
 .../java/lang/classfile/ClassReader.java      | 125 +++++++----
 .../java/lang/classfile/ClassSignature.java   |  45 +++-
 .../java/lang/classfile/CustomAttribute.java  |  38 +++-
 .../java/lang/classfile/MethodSignature.java  |  77 +++++--
 .../java/lang/classfile/Signature.java        | 208 ++++++++++++++----
 .../java/lang/classfile/TypeAnnotation.java   |  90 +++++---
 .../attribute/AnnotationDefaultAttribute.java |  35 +--
 .../attribute/BootstrapMethodsAttribute.java  |  36 ++-
 .../attribute/CharacterRangeInfo.java         |  89 +++++---
 .../CharacterRangeTableAttribute.java         |  64 ++++--
 .../classfile/attribute/CodeAttribute.java    |  34 ++-
 .../attribute/CompilationIDAttribute.java     |  28 ++-
 .../attribute/ConstantValueAttribute.java     |  24 +-
 .../attribute/DeprecatedAttribute.java        |  32 ++-
 .../attribute/EnclosingMethodAttribute.java   |  72 ++++--
 .../attribute/ExceptionsAttribute.java        |  41 +++-
 .../classfile/attribute/InnerClassInfo.java   |  56 +++--
 .../attribute/InnerClassesAttribute.java      |  30 ++-
 .../classfile/attribute/LineNumberInfo.java   |  15 +-
 .../attribute/LineNumberTableAttribute.java   |  40 +++-
 .../attribute/LocalVariableInfo.java          |  12 +-
 .../LocalVariableTableAttribute.java          |  45 +++-
 .../attribute/LocalVariableTypeInfo.java      |  12 +-
 .../LocalVariableTypeTableAttribute.java      |  42 +++-
 .../attribute/MethodParameterInfo.java        |  34 +--
 .../attribute/MethodParametersAttribute.java  |  28 ++-
 .../classfile/attribute/ModuleAttribute.java  | 159 +++++++++----
 .../classfile/attribute/ModuleExportInfo.java |  79 +++++--
 .../classfile/attribute/ModuleHashInfo.java   |   3 +-
 .../attribute/ModuleHashesAttribute.java      |  31 ++-
 .../attribute/ModuleMainClassAttribute.java   |  28 ++-
 .../classfile/attribute/ModuleOpenInfo.java   |  73 ++++--
 .../attribute/ModulePackagesAttribute.java    |  32 ++-
 .../attribute/ModuleProvideInfo.java          |  31 ++-
 .../attribute/ModuleRequireInfo.java          |  40 +++-
 .../attribute/ModuleResolutionAttribute.java  |  39 ++--
 .../attribute/ModuleTargetAttribute.java      |  33 ++-
 .../attribute/NestHostAttribute.java          |  31 ++-
 .../attribute/NestMembersAttribute.java       |  37 +++-
 .../PermittedSubclassesAttribute.java         |  51 +++--
 .../classfile/attribute/RecordAttribute.java  |  30 ++-
 .../attribute/RecordComponentInfo.java        |  44 +++-
 .../RuntimeInvisibleAnnotationsAttribute.java |  41 ++--
 ...nvisibleParameterAnnotationsAttribute.java |  48 +++-
 ...timeInvisibleTypeAnnotationsAttribute.java |  49 +++--
 .../RuntimeVisibleAnnotationsAttribute.java   |  39 ++--
 ...eVisibleParameterAnnotationsAttribute.java |  52 +++--
 ...untimeVisibleTypeAnnotationsAttribute.java |  49 +++--
 .../attribute/SignatureAttribute.java         |  64 ++++--
 .../SourceDebugExtensionAttribute.java        |  27 ++-
 .../attribute/SourceFileAttribute.java        |  26 ++-
 .../attribute/SourceIDAttribute.java          |  31 ++-
 .../attribute/StackMapFrameInfo.java          |  57 +++--
 .../attribute/StackMapTableAttribute.java     |  33 ++-
 .../attribute/SyntheticAttribute.java         |  33 ++-
 .../classfile/attribute/UnknownAttribute.java |  18 +-
 .../classfile/attribute/package-info.java     |  74 ++++++-
 .../snippet-files/PackageSnippets.java        |  63 ++++++
 .../classfile/constantpool/DoubleEntry.java   |   4 +-
 .../classfile/constantpool/FloatEntry.java    |   4 +-
 .../instruction/DiscontinuedInstruction.java  |  15 +-
 test/jdk/jdk/classfile/SnippetsTest.java      |   1 +
 70 files changed, 2436 insertions(+), 967 deletions(-)
 create mode 100644 src/java.base/share/classes/java/lang/classfile/attribute/snippet-files/PackageSnippets.java

diff --git a/src/java.base/share/classes/java/lang/classfile/Annotation.java b/src/java.base/share/classes/java/lang/classfile/Annotation.java
index 98b6ea783d5..5c4ee630b08 100644
--- a/src/java.base/share/classes/java/lang/classfile/Annotation.java
+++ b/src/java.base/share/classes/java/lang/classfile/Annotation.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2022, 2024, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2022, 2025, 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
@@ -41,8 +41,9 @@
  * type_annotation} structure (JVMS {@jvms 4.7.20}). This model indicates the
  * interface of the annotation and a set of element-value pairs.
  * <p>
- * This model can reconstruct an annotation, given the location of the modeled structure
- * in the class file and the definition of the annotation interface.
+ * This model can reconstruct an annotation, given the location of the modeled
+ * structure in the {@code class} file and the definition of the annotation
+ * interface.
  * <p>
  * Two {@code Annotation} objects should be compared using the {@link
  * Object#equals(Object) equals} method.
@@ -54,8 +55,8 @@
  * elements with default values (JLS {@jls 9.6.2}), and whether the reconstructed annotation
  * is a container annotation for multiple annotations (JLS {@jls 9.7.5}).
  *
- * @see AnnotationElement
- * @see AnnotationValue
+ * @see java.lang.annotation.Annotation
+ * @see java.lang.reflect.AnnotatedElement Annotations in core reflection
  * @see TypeAnnotation
  * @see RuntimeVisibleAnnotationsAttribute
  * @see RuntimeInvisibleAnnotationsAttribute
@@ -70,11 +71,15 @@ public sealed interface Annotation
     /**
      * {@return the constant pool entry holding the {@linkplain Class#descriptorString
      * descriptor string} of the annotation interface}
+     *
+     * @see java.lang.annotation.Annotation#annotationType()
      */
     Utf8Entry className();
 
     /**
      * {@return the annotation interface, as a symbolic descriptor}
+     *
+     * @see java.lang.annotation.Annotation#annotationType()
      */
     default ClassDesc classSymbol() {
         return Util.fieldTypeSymbol(className());
diff --git a/src/java.base/share/classes/java/lang/classfile/AnnotationElement.java b/src/java.base/share/classes/java/lang/classfile/AnnotationElement.java
index 4381bb9733a..23f830f1512 100644
--- a/src/java.base/share/classes/java/lang/classfile/AnnotationElement.java
+++ b/src/java.base/share/classes/java/lang/classfile/AnnotationElement.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2022, 2024, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2022, 2025, 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
@@ -40,8 +40,8 @@
  * {@link Object#equals(Object) equals} method.
  *
  * @see Annotation
- * @see AnnotationValue
- *
+ * @see java.lang.reflect.AnnotatedElement Annotations in core reflection
+ * @jvms 4.7.16.1 The {@code element_value} structure
  * @since 24
  */
 public sealed interface AnnotationElement
diff --git a/src/java.base/share/classes/java/lang/classfile/AnnotationValue.java b/src/java.base/share/classes/java/lang/classfile/AnnotationValue.java
index 45ed2fbbe81..54a9ed80573 100644
--- a/src/java.base/share/classes/java/lang/classfile/AnnotationValue.java
+++ b/src/java.base/share/classes/java/lang/classfile/AnnotationValue.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2022, 2024, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2022, 2025, 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
@@ -45,6 +45,7 @@
  *
  * @see Annotation
  * @see AnnotationElement
+ * @see java.lang.reflect.AnnotatedElement Annotations in core reflection
  *
  * @sealedGraph
  * @since 24
diff --git a/src/java.base/share/classes/java/lang/classfile/Attribute.java b/src/java.base/share/classes/java/lang/classfile/Attribute.java
index bb5c7bdf8ea..02b9332bb79 100644
--- a/src/java.base/share/classes/java/lang/classfile/Attribute.java
+++ b/src/java.base/share/classes/java/lang/classfile/Attribute.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2022, 2024, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2022, 2025, 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
@@ -31,15 +31,31 @@
 import jdk.internal.classfile.impl.UnboundAttribute;
 
 /**
- * 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
- * corresponding model type. Additionally, all attributes are accessible
- * directly from the corresponding model type through {@link
- * AttributedElement#findAttribute(AttributeMapper)}.
- * @param <A> the attribute type
+ * Models an attribute (JVMS {@jvms 4.7}) in the {@code class} file format.
+ * Attributes exist on certain {@code class} file structures modeled by {@link
+ * AttributedElement}, which provides basic read access to the attributes.
+ * <p>
+ * This sealed interface hierarchy includes attributes predefined in the JVMS
+ * and JDK-specific nonstandard attributes.  Their {@linkplain #attributeMapper()
+ * mappers} are available in {@link Attributes}.  Two special subtypes of {@code
+ * Attribute} are {@link CustomAttribute}, which all user-defined attributes
+ * should extend from, and {@link UnknownAttribute}, representing attributes
+ * read from {@code class} file but are not recognized by the {@link
+ * ClassFile.AttributeMapperOption}.
+ * <p>
+ * Attributes are read through {@link AttributedElement} or element traversal of
+ * a {@link CompoundElement}; they are written through {@link ClassFileBuilder}.
+ * See {@linkplain java.lang.classfile.attribute##reading Reading Attributes}
+ * and {@linkplain java.lang.classfile.attribute##writing Writing Attributes}
+ * for more details.
  *
+ * @param <A> the attribute type
+ * @see java.lang.classfile.attribute
+ * @see AttributeMapper
+ * @see AttributedElement
+ * @see CustomAttribute
+ * @see UnknownAttribute
+ * @jvms 4.7 Attributes
  * @sealedGraph
  * @since 24
  */
@@ -62,7 +78,13 @@ public sealed interface Attribute<A extends Attribute<A>>
                 StackMapTableAttribute, SyntheticAttribute,
                 UnknownAttribute, BoundAttribute, UnboundAttribute, CustomAttribute {
     /**
-     * {@return the name of the attribute}
+     * {@return the name of the attribute}  The {@linkplain
+     * Utf8Entry#stringValue() string value} of the name is equivalent to the
+     * value of {@link AttributeMapper#name() attributeMapper().name()}.
+     * <p>
+     * If this attribute is read from a {@code class} file, this method returns
+     * the {@link Utf8Entry} indicating the attribute name in the {@code class}
+     * file.
      */
     Utf8Entry attributeName();
 
diff --git a/src/java.base/share/classes/java/lang/classfile/AttributeMapper.java b/src/java.base/share/classes/java/lang/classfile/AttributeMapper.java
index 993da9aa4a8..411da29b1e9 100644
--- a/src/java.base/share/classes/java/lang/classfile/AttributeMapper.java
+++ b/src/java.base/share/classes/java/lang/classfile/AttributeMapper.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2022, 2024, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2022, 2025, 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
@@ -24,54 +24,118 @@
  */
 package java.lang.classfile;
 
+import java.lang.classfile.attribute.BootstrapMethodsAttribute;
+import java.lang.classfile.attribute.CodeAttribute;
+import java.lang.classfile.attribute.UnknownAttribute;
+import java.lang.classfile.constantpool.ConstantPoolBuilder;
+import java.lang.classfile.constantpool.Utf8Entry;
+
 /**
- * Bidirectional mapper between the classfile representation of an attribute and
- * how that attribute is modeled in the API.  The attribute mapper is used
- * to parse the classfile representation into a model, and to write the model
- * representation back to a classfile.  For each standard attribute, there is a
- * predefined attribute mapper defined in {@link Attributes}. For nonstandard
- * attributes, clients can define their own {@linkplain AttributeMapper}.
- * Classes that model nonstandard attributes should extend {@link
- * CustomAttribute}.
- * @param <A> the attribute type
+ * Bidirectional mapper between the {@code class} file representation of an
+ * attribute and its API model.  The attribute mapper identifies an attribute
+ * by its {@linkplain Attribute#attributeName name}, and is used to parse the
+ * {@code class} file representation into a model, and to write the model
+ * representation back to a {@code class} file.
+ * <p>
+ * {@link Attributes} defines the mappers for predefined attributes in the JVMS
+ * and certain conventional attributes.  For other attributes (JVMS {@jvms
+ * 4.7.1}), users can define their own {@code AttributeMapper}; classes that
+ * model those attributes should extend {@link CustomAttribute}.  To read those
+ * attributes, user-defined {@code AttributeMapper}s must be registered to the
+ * {@link ClassFile.AttributeMapperOption}.
  *
+ * @param <A> the attribute type
+ * @see Attributes
+ * @see ClassFile.AttributeMapperOption
+ * @see java.lang.classfile.attribute
  * @since 24
  */
 public interface AttributeMapper<A extends Attribute<A>> {
 
     /**
-     * Attribute stability indicator
+     * Indicates the data dependency of the {@code class} file representation
+     * of an attribute.  Whether an attribute can be bulk-copied by its binary
+     * representation to a new {@code class} file depends on if its data refers
+     * to other parts of its enclosing {@code class} file.
      *
+     * @apiNote
+     * This dependency is called "stability" because it indicates the conditions
+     * for a {@code class} file attribute to be eligible for bulk-copying to
+     * another {@code class} file.
+     *
+     * @see AttributeMapper#stability()
      * @since 24
      */
     enum AttributeStability {
 
         /**
-         * The attribute contains only pure data, such as timestamps, and can always be bulk-copied.
+         * The attribute contains only standalone data, and has no reference to
+         * other parts of its enclosing {@code class} file, besides the name of
+         * the attribute.  Thus, its contents can always be bulk-copied to
+         * another {@code class} file.
+         * <p>
+         * For example, a bit mask is standalone data.
          */
         STATELESS,
 
         /**
-         * The attribute contains only pure data and CP refs, so can be bulk-copied when CP sharing is in effect,
-         * and need to be exploded and rewritten when CP sharing is not in effect.
+         * In addition to standalone data, the attribute refers to the constant
+         * pool, including the {@link BootstrapMethodsAttribute BootstrapMethods}
+         * attribute, of its enclosing {@code class} file.  Thus, it can be
+         * bulk-copied when the destination {@code class} file extends its
+         * constant pool from that of the original {@code class}.  It must be
+         * expanded to translate constant pool references and rewritten when
+         * constant pool indices are not compatible.
+         * <p>
+         * For example, a {@link Utf8Entry} is a reference to the constant pool.
+         *
+         * @see ConstantPoolBuilder#of(ClassModel)
+         * @see ClassFile.ConstantPoolSharingOption
          */
         CP_REFS,
 
         /**
-         * The attribute may contain labels, so need to be exploded and rewritten when the Code array is perturbed.
+         * In addition to standalone data and references to the constant pool,
+         * the attribute refers to positions into the {@code code} array of a
+         * {@link CodeAttribute Code} attribute.  Thus, it can be bulked-copied
+         * when the {@code code} array is unchanged, which requires that the
+         * destination {@code class} file extends its constant pool from that of
+         * the original {@code class}.  It must be expanded to translate {@link
+         * Label}s or constant pool references and rewritten if the {@code code}
+         * array is perturbed, including when constant pool indices are not
+         * compatible.
+         * <p>
+         * For example, a bci value, modeled by a {@link Label}, is a reference
+         * to a position in the {@code code} array.
          */
         LABELS,
 
         /**
-         * The attribute may contain indexes into structured not managed by the library (type variable lists, etc)
-         * and so we consult the {@link ClassFile.AttributesProcessingOption} option to determine whether to preserve
-         * or drop it during transformation.
+         * The attribute refers to structures not managed by the library (type
+         * variable lists, etc.).  As a result, even when the attribute is
+         * expanded, those references may not be correctly translated, and the
+         * rewritten results may be incorrect.
+         * <p>
+         * If the attribute is read from a {@code class} file, {@link
+         * ClassFile.AttributesProcessingOption} determines whether to preserve
+         * or drop the attribute during transformation.
+         *
+         * @see ClassFile.AttributesProcessingOption#DROP_UNSTABLE_ATTRIBUTES
          */
         UNSTABLE,
 
         /**
-         * The attribute is completely unknown and so we consult the {@link ClassFile.AttributesProcessingOption} option
-         * to determine whether to preserve or drop it during transformation.
+         * The attribute is completely unknown.  As a result, expanding and
+         * rewriting is not possible, and any difference between the destination
+         * {@code class} file and its enclosing {@code class} file may make the
+         * attribute incorrect.
+         * <p>
+         * {@link ClassFile.AttributesProcessingOption} determines whether to
+         * preserve or drop the attribute during transformation.
+         *
+         * @see UnknownAttribute
+         * @see ClassFile.AttributesProcessingOption#DROP_UNSTABLE_ATTRIBUTES
+         * @see ClassFile.AttributesProcessingOption#DROP_UNKNOWN_ATTRIBUTES
          */
         UNKNOWN
     }
@@ -82,35 +146,104 @@ enum AttributeStability {
     String name();
 
     /**
-     * Create an {@link Attribute} instance from a classfile.
+     * Creates an {@link Attribute} instance from a {@code class} file for the
+     * Class-File API.
+     * <p>
+     * This method is called by the Class-File API to support reading of
+     * attributes.  Users should never call this method.
+     * <p>
+     * The Class-File API makes these promises about the call to this method:
+     * <ul>
+     * <li>The {@link Utf8Entry} for the name of the attribute is accessible
+     * with {@code cf.readEntry(pos - 6, Utf8Entry.class)}, and is validated;
+     * <li>The length of the attribute is accessible with {@code cf.readInt(pos
+     * - 4)}, and is validated to be positive and not beyond the length of the
+     * {@code class} file;
+     * <li>The {@link AttributedElement} attribute access functionalities on the
+     * {@code enclosing} model may not be accessed when this method is called,
+     * but can be accessed later by the returned attribute when it is accessible
+     * to users.
+     * </ul>
+     * <p>
+     * The returned {@code Attribute} must fulfill these requirements:
+     * <ul>
+     * <li>{@link Attribute#attributeMapper()} returns this mapper;
+     * <li>{@link Attribute#attributeName()} returns the attribute name in the
+     * {@code class} file.
+     * </ul>
+     *
+     * @apiNote
+     * Implementations of this method should perform minimal work to return an
+     * attribute, as this method is called even if the resulting attribute is
+     * never used.  In particular, the implementation should avoid checking the
+     * validity of the attribute {@code class} file data or performing actions
+     * that may throw exceptions.
      *
-     * @param enclosing The class, method, field, or code attribute in which
-     *                  this attribute appears
-     * @param cf The {@link ClassReader} describing the classfile to read from
-     * @param pos The offset into the classfile at which the attribute starts
-     * @return the new attribute
+     * @param enclosing the structure in which this attribute appears
+     * @param cf provides access to the {@code class} file to read from
+     * @param pos the offset into the {@code class} file at which the contents
+     *            of the attribute starts
+     * @return the read attribute
      */
     A readAttribute(AttributedElement enclosing, ClassReader cf, int pos);
 
     /**
-     * Write an {@link Attribute} instance to a classfile.
+     * Writes an {@link Attribute} instance to a {@code class} file for the
+     * Class-File API.
+     * <p>
+     * This method is called by the Class-File API to support writing of
+     * attributes.  Users should never call this method.
+     * <p>
+     * The Class-File API makes these promises about the call to this method:
+     * <ul>
+     * <li>{@link Attribute#attributeMapper() attr.attributeMapper()} returns
+     * this mapper;
+     * <li>The {@code buf} may already have data written, that its {@link
+     * BufWriter#size() size} may not be {@code 0}.
+     * </ul>
+     * <p>
+     * The {@code class} file writing must fulfill these requirements:
+     * <ul>
+     * <li>The attribute name {@code u2} and attribute length {@code u4} must
+     * be written to the {@code buf};
+     * <li>{@link Attribute#attributeName() attr.attributeName()} is written as
+     * if with {@code buf.writeIndex(attr.attributeName())};
+     * <li>The attribute length is the length, in bytes, of attribute contents
+     * written to the {@code buf}, not including the 6 bytes used by the name
+     * and the length;
+     * <li>If any information in the API model of the attribute, {@code attr},
+     * cannot be represented in the {@code class} file format of the attribute,
+     * an {@link IllegalArgumentException} is thrown.
+     * </ul>
+     *
+     * @apiNote
+     * {@link BufWriter#patchInt} can be used to update the attribute length
+     * after the attribute contents are written to the {@code buf}.
      *
-     * @param buf The {@link BufWriter} to which the attribute should be written
-     * @param attr The attribute to write
+     * @param buf the {@link BufWriter} to which the attribute should be written
+     * @param attr the attribute to write
+     * @throws IllegalArgumentException if some data in the API model of the
+     *         attribute is invalid for the {@code class} file format
      */
     void writeAttribute(BufWriter buf, A attr);
 
     /**
-     * {@return whether this attribute may appear more than once in a given location}
+     * {@return whether this attribute may appear more than once in one
+     * structure}
+     * <p>
+     * If an attribute does not allow multiple instances in one structure,
+     * can be supplied to a {@link ClassFileBuilder}, and multiple instances of
+     * the attribute are supplied to the builder, the last supplied attribute
+     * appears on the built structure.
      *
-     * @implSpec The default implementation returns {@code false}
+     * @implSpec The default implementation returns {@code false}.
      */
     default boolean allowMultiple() {
         return false;
     }
 
     /**
-     * {@return attribute stability indicator}
+     * {@return the data dependency of this attribute on the {@code class} file}
      */
     AttributeStability stability();
 }
diff --git a/src/java.base/share/classes/java/lang/classfile/AttributedElement.java b/src/java.base/share/classes/java/lang/classfile/AttributedElement.java
index 478ad1e3f0a..0edb79a863d 100644
--- a/src/java.base/share/classes/java/lang/classfile/AttributedElement.java
+++ b/src/java.base/share/classes/java/lang/classfile/AttributedElement.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2022, 2024, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2022, 2025, 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
@@ -24,6 +24,7 @@
  */
 package java.lang.classfile;
 
+import java.lang.classfile.attribute.CodeAttribute;
 import java.lang.classfile.attribute.RecordComponentInfo;
 import java.util.ArrayList;
 import java.util.Collections;
@@ -35,9 +36,11 @@
 import static java.util.Objects.requireNonNull;
 
 /**
- * A {@link ClassFileElement} describing an entity that has attributes, such
- * as a class, field, method, code attribute, or record component.
+ * A {@link ClassFileElement} describing a {@code class} file structure that has
+ * attributes, such as a {@code class} file, a field, a method, a {@link
+ * CodeAttribute Code} attribute, or a record component.
  *
+ * @jvms 4.7 Attributes
  * @sealedGraph
  * @since 24
  */
@@ -46,15 +49,28 @@ public sealed interface AttributedElement extends ClassFileElement
                 RecordComponentInfo, AbstractUnboundModel {
 
     /**
-     * {@return the attributes of this element}
+     * {@return the attributes of this structure}
      */
     List<Attribute<?>> attributes();
 
     /**
-     * Finds an attribute by name.
+     * Finds an attribute by name.  This is suitable to find attributes that
+     * {@linkplain AttributeMapper#allowMultiple() allow at most one instance}
+     * in one structure.  If this is used to find attributes that allow multiple
+     * instances in one structure, the first matching instance is returned.
+     *
+     * @apiNote
+     * This can easily find an attribute and send it to another {@link
+     * ClassFileBuilder}, which is a {@code Consumer}:
+     * {@snippet lang=java :
+     * MethodModel method = null; // @replace substring=null; replacement=...
+     * MethodBuilder mb = null; // @replace substring=null; replacement=...
+     * method.findAttribute(Attributes.code()).ifPresent(mb);
+     * }
+     *
      * @param attr the attribute mapper
      * @param <T> the type of the attribute
-     * @return the attribute, or an empty {@linkplain Optional} if the attribute
+     * @return the attribute, or {@code Optional.empty()} if the attribute
      * is not present
      */
     default <T extends Attribute<T>> Optional<T> findAttribute(AttributeMapper<T> attr) {
@@ -70,10 +86,13 @@ default <T extends Attribute<T>> Optional<T> findAttribute(AttributeMapper<T> at
     }
 
     /**
-     * Finds one or more attributes by name.
+     * Finds attributes by name.  This is suitable to find attributes that
+     * {@linkplain AttributeMapper#allowMultiple() allow multiple instances}
+     * in one structure.
+     *
      * @param attr the attribute mapper
      * @param <T> the type of the attribute
-     * @return the attributes, or an empty {@linkplain List} if the attribute
+     * @return the attributes, or an empty {@code List} if the attribute
      * is not present
      */
     default <T extends Attribute<T>> List<T> findAttributes(AttributeMapper<T> attr) {
diff --git a/src/java.base/share/classes/java/lang/classfile/Attributes.java b/src/java.base/share/classes/java/lang/classfile/Attributes.java
index 24684a36b02..eaa0fec5a4e 100644
--- a/src/java.base/share/classes/java/lang/classfile/Attributes.java
+++ b/src/java.base/share/classes/java/lang/classfile/Attributes.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2022, 2024, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2022, 2025, 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
@@ -30,64 +30,20 @@
 import jdk.internal.classfile.impl.AbstractAttributeMapper.*;
 
 /**
- * Attribute mappers for standard classfile attributes.
+ * Attribute mappers for predefined (JVMS {@jvms 4.7}) and JDK-specific
+ * nonstandard attributes.
  * <p>
- * Unless otherwise specified, mappers returned by each method
- * do not permit multiple attribute instances in a given location.
- * <p>
- * The most stable {@link AttributeStability#STATELESS STATELESS} mappers are:
- * <ul>
- * <li>{@link #deprecated()}
- * <li>{@link #moduleResolution()}
- * <li>{@link #sourceDebugExtension()}
- * <li>{@link #synthetic()}
- * </ul>
- *
- * The mappers with {@link AttributeStability#CP_REFS CP_REFS} stability are:
- * <ul>
- * <li>{@link #annotationDefault()}
- * <li>{@link #bootstrapMethods()}
- * <li>{@link #code()}
- * <li>{@link #compilationId()}
- * <li>{@link #constantValue()}
- * <li>{@link #enclosingMethod()}
- * <li>{@link #exceptions()}
- * <li>{@link #innerClasses()}
- * <li>{@link #methodParameters()}
- * <li>{@link #module()}
- * <li>{@link #moduleHashes()}
- * <li>{@link #moduleMainClass()}
- * <li>{@link #modulePackages()}
- * <li>{@link #moduleTarget()}
- * <li>{@link #nestHost()}
- * <li>{@link #nestMembers()}
- * <li>{@link #permittedSubclasses()}
- * <li>{@link #record()}
- * <li>{@link #runtimeInvisibleAnnotations()}
- * <li>{@link #runtimeInvisibleParameterAnnotations()}
- * <li>{@link #runtimeVisibleAnnotations()}
- * <li>{@link #runtimeVisibleParameterAnnotations()}
- * <li>{@link #signature()}
- * <li>{@link #sourceFile()}
- * <li>{@link #sourceId()}
- * </ul>
- *
- * The mappers with {@link AttributeStability#LABELS LABELS} stability are:
+ * Unless otherwise specified, each mapper returned by methods in this class:
  * <ul>
- * <li>{@link #characterRangeTable()}
- * <li>{@link #lineNumberTable()}
- * <li>{@link #localVariableTable()}
- * <li>{@link #localVariableTypeTable()}
- * </ul>
- *
- * The {@link AttributeStability#UNSTABLE UNSTABLE} mappers are:
- * <ul>
- * <li>{@link #runtimeInvisibleTypeAnnotations()}
- * <li>{@link #runtimeVisibleTypeAnnotations()}
+ * <li>is predefined in the JVMS instead of JDK-specific;
+ * <li>does not permit {@linkplain AttributeMapper#allowMultiple() multiple
+ * attribute instances} in the same structure;
+ * <li>the attribute has a {@linkplain AttributeMapper#stability() data
+ * dependency} on the {@linkplain AttributeStability#CP_REFS constant pool}.
  * </ul>
  *
  * @see AttributeMapper
- *
+ * @see java.lang.classfile.attribute
  * @since 24
  */
 public final class Attributes {
@@ -204,258 +160,278 @@ private Attributes() {
     }
 
     /**
-     * {@return Attribute mapper for the {@code AnnotationDefault} attribute}
+     * {@return the mapper for the {@code AnnotationDefault} attribute}
      */
     public static AttributeMapper<AnnotationDefaultAttribute> annotationDefault() {
         return AnnotationDefaultMapper.INSTANCE;
     }
 
     /**
-     * {@return Attribute mapper for the {@code BootstrapMethods} attribute}
+     * {@return the mapper for the {@code BootstrapMethods} attribute}
      */
     public static AttributeMapper<BootstrapMethodsAttribute> bootstrapMethods() {
         return BootstrapMethodsMapper.INSTANCE;
     }
 
     /**
-     * {@return Attribute mapper for the {@code CharacterRangeTable} attribute}
-     * The mapper permits multiple instances in a given location.
+     * {@return the mapper for the {@code CharacterRangeTable} attribute}
+     * This is a JDK-specific attribute.
+     * The mapper permits multiple instances in a {@code Code} attribute, but this
+     * attribute should be only emitted once.
+     * This has a data dependency on {@linkplain AttributeStability#LABELS labels}.
      */
     public static AttributeMapper<CharacterRangeTableAttribute> characterRangeTable() {
         return CharacterRangeTableMapper.INSTANCE;
     }
 
     /**
-     * {@return Attribute mapper for the {@code Code} attribute}
+     * {@return the mapper for the {@code Code} attribute}
      */
     public static AttributeMapper<CodeAttribute> code() {
         return CodeMapper.INSTANCE;
     }
 
     /**
-     * {@return Attribute mapper for the {@code CompilationID} attribute}
+     * {@return the mapper for the {@code CompilationID} attribute}
+     * This is a JDK-specific attribute.
      */
     public static AttributeMapper<CompilationIDAttribute> compilationId() {
         return CompilationIDMapper.INSTANCE;
     }
 
     /**
-     * {@return Attribute mapper for the {@code ConstantValue} attribute}
+     * {@return the mapper for the {@code ConstantValue} attribute}
      */
     public static AttributeMapper<ConstantValueAttribute> constantValue() {
         return ConstantValueMapper.INSTANCE;
     }
 
     /**
-     * {@return Attribute mapper for the {@code Deprecated} attribute}
+     * {@return the mapper for the {@code Deprecated} attribute}
      * The mapper permits multiple instances in a given location.
+     * This has {@linkplain AttributeStability#STATELESS no data dependency}.
      */
     public static AttributeMapper<DeprecatedAttribute> deprecated() {
         return DeprecatedMapper.INSTANCE;
     }
 
     /**
-     * {@return Attribute mapper for the {@code EnclosingMethod} attribute}
+     * {@return the mapper for the {@code EnclosingMethod} attribute}
      */
     public static AttributeMapper<EnclosingMethodAttribute> enclosingMethod() {
         return EnclosingMethodMapper.INSTANCE;
     }
 
     /**
-     * {@return Attribute mapper for the {@code Exceptions} attribute}
+     * {@return the mapper for the {@code Exceptions} attribute}
      */
     public static AttributeMapper<ExceptionsAttribute> exceptions() {
         return ExceptionsMapper.INSTANCE;
     }
 
     /**
-     * {@return Attribute mapper for the {@code InnerClasses} attribute}
+     * {@return the mapper for the {@code InnerClasses} attribute}
      */
     public static AttributeMapper<InnerClassesAttribute> innerClasses() {
         return InnerClassesMapper.INSTANCE;
     }
 
     /**
-     * {@return Attribute mapper for the {@code LineNumberTable} attribute}
-     * The mapper permits multiple instances in a given location.
+     * {@return the mapper for the {@code LineNumberTable} attribute}
+     * The mapper permits multiple instances in a {@code Code} attribute.
+     * This has a data dependency on {@linkplain AttributeStability#LABELS labels}.
      */
     public static AttributeMapper<LineNumberTableAttribute> lineNumberTable() {
         return LineNumberTableMapper.INSTANCE;
     }
 
     /**
-     * {@return Attribute mapper for the {@code LocalVariableTable} attribute}
-     * The mapper permits multiple instances in a given location.
+     * {@return the mapper for the {@code LocalVariableTable} attribute}
+     * The mapper permits multiple instances in a {@code Code} attribute.
+     * This has a data dependency on {@linkplain AttributeStability#LABELS labels}.
      */
     public static AttributeMapper<LocalVariableTableAttribute> localVariableTable() {
         return LocalVariableTableMapper.INSTANCE;
     }
 
     /**
-     * {@return Attribute mapper for the {@code LocalVariableTypeTable} attribute}
+     * {@return the mapper for the {@code LocalVariableTypeTable} attribute}
      * The mapper permits multiple instances in a given location.
+     * This has a data dependency on {@linkplain AttributeStability#LABELS labels}.
      */
     public static AttributeMapper<LocalVariableTypeTableAttribute> localVariableTypeTable() {
         return LocalVariableTypeTableMapper.INSTANCE;
     }
 
     /**
-     * {@return Attribute mapper for the {@code MethodParameters} attribute}
+     * {@return the mapper for the {@code MethodParameters} attribute}
      */
     public static AttributeMapper<MethodParametersAttribute> methodParameters() {
         return MethodParametersMapper.INSTANCE;
     }
 
     /**
-     * {@return Attribute mapper for the {@code Module} attribute}
+     * {@return the mapper for the {@code Module} attribute}
      */
     public static AttributeMapper<ModuleAttribute> module() {
         return ModuleMapper.INSTANCE;
     }
 
     /**
-     * {@return Attribute mapper for the {@code ModuleHashes} attribute}
+     * {@return the mapper for the {@code ModuleHashes} attribute}
+     * This is a JDK-specific attribute.
      */
     public static AttributeMapper<ModuleHashesAttribute> moduleHashes() {
         return ModuleHashesMapper.INSTANCE;
     }
 
     /**
-     * {@return Attribute mapper for the {@code ModuleMainClass} attribute}
+     * {@return the mapper for the {@code ModuleMainClass} attribute}
      */
     public static AttributeMapper<ModuleMainClassAttribute> moduleMainClass() {
         return ModuleMainClassMapper.INSTANCE;
     }
 
     /**
-     * {@return Attribute mapper for the {@code ModulePackages} attribute}
+     * {@return the mapper for the {@code ModulePackages} attribute}
      */
     public static AttributeMapper<ModulePackagesAttribute> modulePackages() {
         return ModulePackagesMapper.INSTANCE;
     }
 
     /**
-     * {@return Attribute mapper for the {@code ModuleResolution} attribute}
+     * {@return the mapper for the {@code ModuleResolution} attribute}
+     * This is a JDK-specific attribute.
+     * This has {@linkplain AttributeStability#STATELESS no data dependency}.
      */
     public static AttributeMapper<ModuleResolutionAttribute> moduleResolution() {
         return ModuleResolutionMapper.INSTANCE;
     }
 
     /**
-     * {@return Attribute mapper for the {@code ModuleTarget} attribute}
+     * {@return the mapper for the {@code ModuleTarget} attribute}
+     * This is a JDK-specific attribute.
      */
     public static AttributeMapper<ModuleTargetAttribute> moduleTarget() {
         return ModuleTargetMapper.INSTANCE;
     }
 
     /**
-     * {@return Attribute mapper for the {@code NestHost} attribute}
+     * {@return the mapper for the {@code NestHost} attribute}
      */
     public static AttributeMapper<NestHostAttribute> nestHost() {
         return NestHostMapper.INSTANCE;
     }
 
     /**
-     * {@return Attribute mapper for the {@code NestMembers} attribute}
+     * {@return the mapper for the {@code NestMembers} attribute}
      */
     public static AttributeMapper<NestMembersAttribute> nestMembers() {
         return NestMembersMapper.INSTANCE;
     }
 
     /**
-     * {@return Attribute mapper for the {@code PermittedSubclasses} attribute}
+     * {@return the mapper for the {@code PermittedSubclasses} attribute}
      */
     public static AttributeMapper<PermittedSubclassesAttribute> permittedSubclasses() {
         return PermittedSubclassesMapper.INSTANCE;
     }
 
     /**
-     * {@return Attribute mapper for the {@code Record} attribute}
+     * {@return the mapper for the {@code Record} attribute}
      */
     public static AttributeMapper<RecordAttribute> record() {
         return RecordMapper.INSTANCE;
     }
 
     /**
-     * {@return Attribute mapper for the {@code RuntimeInvisibleAnnotations} attribute}
+     * {@return the mapper for the {@code RuntimeInvisibleAnnotations} attribute}
      */
     public static AttributeMapper<RuntimeInvisibleAnnotationsAttribute> runtimeInvisibleAnnotations() {
         return RuntimeInvisibleAnnotationsMapper.INSTANCE;
     }
 
     /**
-     * {@return Attribute mapper for the {@code RuntimeInvisibleParameterAnnotations} attribute}
+     * {@return the mapper for the {@code RuntimeInvisibleParameterAnnotations} attribute}
      */
     public static AttributeMapper<RuntimeInvisibleParameterAnnotationsAttribute> runtimeInvisibleParameterAnnotations() {
         return RuntimeInvisibleParameterAnnotationsMapper.INSTANCE;
     }
 
     /**
-     * {@return Attribute mapper for the {@code RuntimeInvisibleTypeAnnotations} attribute}
+     * {@return the mapper for the {@code RuntimeInvisibleTypeAnnotations} attribute}
+     * This has a data dependency on {@linkplain AttributeStability#UNSTABLE
+     * arbitrary indices} in the {@code class} file format.
      */
     public static AttributeMapper<RuntimeInvisibleTypeAnnotationsAttribute> runtimeInvisibleTypeAnnotations() {
         return RuntimeInvisibleTypeAnnotationsMapper.INSTANCE;
     }
 
     /**
-     * {@return Attribute mapper for the {@code RuntimeVisibleAnnotations} attribute}
+     * {@return the mapper for the {@code RuntimeVisibleAnnotations} attribute}
      */
     public static AttributeMapper<RuntimeVisibleAnnotationsAttribute> runtimeVisibleAnnotations() {
         return RuntimeVisibleAnnotationsMapper.INSTANCE;
     }
 
     /**
-     * {@return Attribute mapper for the {@code RuntimeVisibleParameterAnnotations} attribute}
+     * {@return the mapper for the {@code RuntimeVisibleParameterAnnotations} attribute}
      */
     public static AttributeMapper<RuntimeVisibleParameterAnnotationsAttribute> runtimeVisibleParameterAnnotations() {
         return RuntimeVisibleParameterAnnotationsMapper.INSTANCE;
     }
 
     /**
-     * {@return Attribute mapper for the {@code RuntimeVisibleTypeAnnotations} attribute}
+     * {@return the mapper for the {@code RuntimeVisibleTypeAnnotations} attribute}
+     * This has a data dependency on {@linkplain AttributeStability#UNSTABLE
+     * arbitrary indices} in the {@code class} file format.
      */
     public static AttributeMapper<RuntimeVisibleTypeAnnotationsAttribute> runtimeVisibleTypeAnnotations() {
         return RuntimeVisibleTypeAnnotationsMapper.INSTANCE;
     }
 
     /**
-     * {@return Attribute mapper for the {@code Signature} attribute}
+     * {@return the mapper for the {@code Signature} attribute}
      */
     public static AttributeMapper<SignatureAttribute> signature() {
         return SignatureMapper.INSTANCE;
     }
 
     /**
-     * {@return Attribute mapper for the {@code SourceDebugExtension} attribute}
+     * {@return the mapper for the {@code SourceDebugExtension} attribute}
+     * This has {@linkplain AttributeStability#STATELESS no data dependency}.
      */
     public static AttributeMapper<SourceDebugExtensionAttribute> sourceDebugExtension() {
         return SourceDebugExtensionMapper.INSTANCE;
     }
 
     /**
-     * {@return Attribute mapper for the {@code SourceFile} attribute}
+     * {@return the mapper for the {@code SourceFile} attribute}
      */
     public static AttributeMapper<SourceFileAttribute> sourceFile() {
         return SourceFileMapper.INSTANCE;
     }
 
     /**
-     * {@return Attribute mapper for the {@code SourceID} attribute}
+     * {@return the mapper for the {@code SourceID} attribute}
+     * This is a JDK-specific attribute.
      */
     public static AttributeMapper<SourceIDAttribute> sourceId() {
         return SourceIDMapper.INSTANCE;
     }
 
     /**
-     * {@return Attribute mapper for the {@code StackMapTable} attribute}
+     * {@return the mapper for the {@code StackMapTable} attribute}
+     * This has a data dependency on {@linkplain AttributeStability#LABELS labels}.
      */
     public static AttributeMapper<StackMapTableAttribute> stackMapTable() {
         return StackMapTableMapper.INSTANCE;
     }
 
     /**
-     * {@return Attribute mapper for the {@code Synthetic} attribute}
+     * {@return the mapper for the {@code Synthetic} attribute}
      * The mapper permits multiple instances in a given location.
+     * This has {@linkplain AttributeStability#STATELESS no data dependency}.
      */
     public static AttributeMapper<SyntheticAttribute> synthetic() {
         return SyntheticMapper.INSTANCE;
diff --git a/src/java.base/share/classes/java/lang/classfile/BufWriter.java b/src/java.base/share/classes/java/lang/classfile/BufWriter.java
index c6779583eb1..81528401d77 100644
--- a/src/java.base/share/classes/java/lang/classfile/BufWriter.java
+++ b/src/java.base/share/classes/java/lang/classfile/BufWriter.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2022, 2024, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2022, 2025, 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
@@ -27,120 +27,163 @@
 import java.lang.classfile.constantpool.ConstantPool;
 import java.lang.classfile.constantpool.ConstantPoolBuilder;
 import java.lang.classfile.constantpool.PoolEntry;
+import java.nio.ByteOrder;
 
 import jdk.internal.classfile.impl.BufWriterImpl;
 
 /**
- * Supports writing portions of a classfile to a growable buffer.   Methods
- * are provided to write various standard entities (e.g., {@code u2}, {@code u4})
- * to the end of the buffer, as well as to create constant pool entries.
+ * Advanced {@code class} file writing support for {@link AttributeMapper}s.
+ * Supports writing portions of a {@code class} file to a growable buffer, such
+ * as writing various numerical types (e.g., {@code u2}, {@code u4}), to the end
+ * of the buffer, as well as to create constant pool entries.
+ * <p>
+ * All numeric values in the {@code class} file format are {@linkplain
+ * ByteOrder#BIG_ENDIAN big endian}.  Writing larger numeric values to smaller
+ * numeric values are always done with truncation, that the least significant
+ * bytes are kept and the other bytes are silently dropped.  As a result,
+ * numeric value writing methods can write both signed and unsigned values, and
+ * users should validate their values before writing if silent dropping of most
+ * significant bytes is not the intended behavior.
  *
+ * @see AttributeMapper#writeAttribute(BufWriter, Attribute)
  * @since 24
  */
 public sealed interface BufWriter
         permits BufWriterImpl {
 
-    /** {@return the constant pool builder associated with this buffer} */
+    /**
+     * {@return the constant pool builder associated with this buffer}
+     *
+     * @see ClassFileBuilder#constantPool()
+     */
     ConstantPoolBuilder constantPool();
 
     /**
-     * {@return whether the provided constant pool is index-compatible with this
-     * one}  This may be because they are the same constant pool, or because this
-     * constant pool was copied from the other.
+     * {@return whether the provided constant pool is index-compatible with the
+     * constant pool of this buffer}
+     * <p>
+     * This is a shortcut for {@code constantPool().canWriteDirect(other)}.
      *
      * @param other the other constant pool
+     * @see ConstantPoolBuilder#canWriteDirect(ConstantPool)
      */
     boolean canWriteDirect(ConstantPool other);
 
     /**
-     * Ensure that the buffer has at least {@code freeBytes} bytes of unused space
+     * Ensures that the buffer has at least {@code freeBytes} bytes of free space
+     * in the end of the buffer.
+     * <p>
+     * The writing result is the same without calls to this method, but the
+     * writing process may be slower.
+     *
+     * @apiNote
+     * This is a hint that changes no visible state of the buffer; it helps to
+     * reduce reallocation of the underlying storage by allocating sufficient
+     * space at once.
+     *
      * @param freeBytes the number of bytes to reserve
      */
     void reserveSpace(int freeBytes);
 
     /**
-     * Write an unsigned byte to the buffer
+     * Writes a byte to the buffer.  {@code x} is truncated to a byte and
+     * written.
      *
-     * @param x the byte value
+     * @param x the value to truncate to a byte
      */
     void writeU1(int x);
 
     /**
-     * Write an unsigned short to the buffer
+     * Writes 2 bytes, or a short, to the buffer.  {@code x} is truncated to two
+     * bytes and written.
      *
-     * @param x the short value
+     * @param x the value to truncate to a short
      */
     void writeU2(int x);
 
     /**
-     * Write a signed int to the buffer
+     * Writes 4 bytes, or an int, to the buffer.
      *
      * @param x the int value
      */
     void writeInt(int x);
 
     /**
-     * Write a float value to the buffer
+     * Writes a float value, of 4 bytes, to the buffer.
+     * <p>
+     * In the conversions, all NaN values of the {@code float} may or may not be
+     * collapsed into a single {@linkplain Float#NaN "canonical" NaN value}.
      *
      * @param x the float value
      */
     void writeFloat(float x);
 
     /**
-     * Write a long value to the buffer
+     * Writes 8 bytes, or a long, to the buffer.
      *
      * @param x the long value
      */
     void writeLong(long x);
 
     /**
-     * Write a double value to the buffer
+     * Writes a double value, of 8 bytes, to the buffer.
+     * <p>
+     * In the conversions, all NaN values of the {@code double} may or may not
+     * be collapsed into a single {@linkplain Double#NaN "canonical" NaN value}.
      *
-     * @param x the int value
+     * @param x the double value
      */
     void writeDouble(double x);
 
     /**
-     * Write the contents of a byte array to the buffer
+     * Writes the contents of a byte array to the buffer.
      *
      * @param arr the byte array
      */
     void writeBytes(byte[] arr);
 
     /**
-     * Write a range of a byte array to the buffer
+     * Writes a range of a byte array to the buffer.
      *
      * @param arr the byte array
-     * @param start the offset within the byte array of the range
+     * @param start the start offset of the range within the byte array
      * @param length the length of the range
-     * @throws IndexOutOfBoundsException if range is outside of the array bounds
+     * @throws IndexOutOfBoundsException if range is outside the array bounds
      */
     void writeBytes(byte[] arr, int start, int length);
 
     /**
-     * Patch a previously written integer value.  Depending on the specified
-     * size, the entire value, or the low 1 or 2 bytes, may be written.
+     * Patches a previously written integer value.  {@code value} is truncated
+     * to the given {@code size} number of bytes and written at the given {@code
+     * offset}.  The end of this buffer stays unchanged.
+     *
+     * @apiNote
+     * The {@code offset} can be obtained by calling {@link #size()} before
+     * writing the previous integer value.
      *
-     * @param offset the offset at which to patch
+     * @param offset the offset in this buffer at which to patch
      * @param size the size of the integer value being written, in bytes
-     * @param value the integer value
+     * @param value the integer value to be truncated
      * @throws IndexOutOfBoundsException if patched int is outside of bounds
+     * @see #size()
      */
     void patchInt(int offset, int size, int value);
 
     /**
-     * Write a 1, 2, 4, or 8 byte integer value to the buffer.  Depending on
-     * the specified size, the entire value, or the low 1, 2, or 4 bytes, may
-     * be written.
+     * Writes a multibyte value to the buffer.  {@code intValue} is truncated
+     * to the given {@code intSize} number of bytes and written.
      *
      * @param intSize the size of the integer value being written, in bytes
-     * @param intValue the integer value
+     * @param intValue the value to be truncated
      */
     void writeIntBytes(int intSize, long intValue);
 
     /**
-     * Write the index of the specified constant pool entry, as a {@code u2},
-     * to the buffer
+     * Writes the index of the specified constant pool entry as a {@link
+     * #writeU2 u2}.  If the {@code entry} does not belong to the {@linkplain
+     * #constantPool() constant pool} of this buffer, it will be {@linkplain
+     * ConstantPoolBuilder##alien converted}, and the index of the converted
+     * pool entry is written instead.
      *
      * @param entry the constant pool entry
      * @throws IllegalArgumentException if the entry has invalid index
@@ -148,16 +191,23 @@ public sealed interface BufWriter
     void writeIndex(PoolEntry entry);
 
     /**
-     * Write the index of the specified constant pool entry, as a {@code u2},
-     * to the buffer, or zero if the entry is null
+     * Writes the index of the specified constant pool entry, or the value
+     * {@code 0} if the specified entry is {@code null}, as a {@link #writeU2
+     * u2}.  If the {@code entry} does not belong to the {@linkplain
+     * #constantPool() constant pool} of this buffer, it will be {@linkplain
+     * ConstantPoolBuilder##alien converted}, and the index of the converted
+     * pool entry is written instead.
      *
-     * @param entry the constant pool entry
-     * @throws IllegalArgumentException if the entry has invalid index
+     * @param entry the constant pool entry, may be {@code null}
+     * @throws IllegalArgumentException if the entry is not {@code null} and has
+     *         invalid index
      */
     void writeIndexOrZero(PoolEntry entry);
 
     /**
      * {@return the number of bytes that have been written to the buffer}
+     *
+     * @see #patchInt(int, int, int)
      */
     int size();
 }
diff --git a/src/java.base/share/classes/java/lang/classfile/ClassReader.java b/src/java.base/share/classes/java/lang/classfile/ClassReader.java
index 93f2ac5c810..3de188af8b3 100644
--- a/src/java.base/share/classes/java/lang/classfile/ClassReader.java
+++ b/src/java.base/share/classes/java/lang/classfile/ClassReader.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2022, 2024, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2022, 2025, 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
@@ -35,12 +35,21 @@
 import jdk.internal.classfile.impl.ClassReaderImpl;
 
 /**
- * Supports reading from a classfile.  Methods are provided to read data of
- * various numeric types (e.g., {@code u2}, {@code u4}) at a given offset within
- * the classfile, copying raw bytes, and reading constant pool entries.
- * Encapsulates additional reading context such as mappers for custom attributes
- * and processing options.
+ * Advanced {@code class} file reading support for {@link AttributeMapper}s.
+ * Supports reading arbitrary offsets within a {@code class} file and reading
+ * data of various numeric types (e.g., {@code u2}, {@code u4}) in addition to
+ * constant pool access.
+ * <p>
+ * All numeric values in the {@code class} file format are {@linkplain
+ * java.nio.ByteOrder#BIG_ENDIAN big endian}.
+ * <p>
+ * Unless otherwise specified, all out-of-bounds access result in an {@link
+ * IllegalArgumentException} to indicate the {@code class} file data is
+ * malformed.  Since the {@code class} file data is arbitrary, users should
+ * sanity-check the structural integrity of the data before attempting to
+ * interpret the potentially malformed data.
  *
+ * @see AttributeMapper#readAttribute(AttributedElement, ClassReader, int)
  * @since 24
  */
 public sealed interface ClassReader extends ConstantPool
@@ -56,29 +65,41 @@ public sealed interface ClassReader extends ConstantPool
 
     // Class context
 
-    /** {@return the access flags for the class, as a bit mask } */
+    /**
+     * {@return the access flags for the class, as a bit mask}
+     *
+     * @see ClassModel#flags()
+     */
     int flags();
 
-    /** {@return the constant pool entry describing the name of class} */
+    /**
+     * {@return the constant pool entry describing the name of class}
+     *
+     * @see ClassModel#thisClass()
+     */
     ClassEntry thisClassEntry();
 
-    /** {@return the constant pool entry describing the name of the superclass, if any} */
+    /**
+     * {@return the constant pool entry describing the name of the superclass, if any}
+     *
+     * @see ClassModel#superclass()
+     */
     Optional<ClassEntry> superclassEntry();
 
-    /** {@return the length of the classfile, in bytes} */
+    /** {@return the length of the {@code class} file, in number of bytes} */
     int classfileLength();
 
     // Constant pool
 
     /**
      * {@return the constant pool entry whose index is given at the specified
-     * offset within the classfile}
+     * offset within the {@code class} file}
      *
      * @apiNote
      * If only a particular type of entry is expected, use {@link #readEntry(
      * int, Class) readEntry(int, Class)}.
      *
-     * @param offset the offset of the index within the classfile
+     * @param offset the offset of the index within the {@code class} file
      * @throws ConstantPoolException if the index is out of range of the
      *         constant pool size, or zero
      */
@@ -86,9 +107,9 @@ public sealed interface ClassReader extends ConstantPool
 
     /**
      * {@return the constant pool entry of a given type whose index is given
-     * at the specified offset within the classfile}
+     * at the specified offset within the {@code class} file}
      * @param <T> the entry type
-     * @param offset the offset of the index within the classfile
+     * @param offset the offset of the index within the {@code class} file
      * @param cls the entry type
      * @throws ConstantPoolException if the index is out of range of the
      *         constant pool size, or zero, or the entry is not of the given type
@@ -97,14 +118,14 @@ public sealed interface ClassReader extends ConstantPool
 
     /**
      * {@return the constant pool entry whose index is given at the specified
-     * offset within the classfile, or null if the index at the specified
-     * offset is zero}
+     * offset within the {@code class} file, or {@code null} if the index at the
+     * specified offset is zero}
      *
      * @apiNote
      * If only a particular type of entry is expected, use {@link #readEntryOrNull(
      * int, Class) readEntryOrNull(int, Class)}.
      *
-     * @param offset the offset of the index within the classfile
+     * @param offset the offset of the index within the {@code class} file
      * @throws ConstantPoolException if the index is out of range of the
      *         constant pool size
      */
@@ -112,11 +133,11 @@ public sealed interface ClassReader extends ConstantPool
 
     /**
      * {@return the constant pool entry of a given type whose index is given
-     * at the specified offset within the classfile, or null if the index at
-     * the specified offset is zero}
+     * at the specified offset within the {@code class} file, or {@code null} if
+     * the index at the specified offset is zero}
      *
      * @param <T> the entry type
-     * @param offset the offset of the index within the classfile
+     * @param offset the offset of the index within the {@code class} file
      * @param cls the entry type
      * @throws ConstantPoolException if the index is out of range of the
      *         constant pool size, or zero, or the entry is not of the given type
@@ -124,65 +145,89 @@ public sealed interface ClassReader extends ConstantPool
     <T extends PoolEntry> T readEntryOrNull(int offset, Class<T> cls);
 
     /**
-     * {@return the unsigned byte at the specified offset within the classfile}
-     * @param offset the offset within the classfile
+     * {@return the unsigned byte at the specified offset within the {@code
+     * class} file}  Reads a byte and zero-extends it to an {@code int}.
+     *
+     * @param offset the offset within the {@code class} file
      */
     int readU1(int offset);
 
     /**
-     * {@return the unsigned short at the specified offset within the classfile}
-     * @param offset the offset within the classfile
+     * {@return the unsigned short at the specified offset within the {@code
+     * class} file}  Reads a 2-byte value and zero-extends it to an {@code int}.
+     *
+     * @param offset the offset within the {@code class} file
      */
     int readU2(int offset);
 
     /**
-     * {@return the signed byte at the specified offset within the classfile}
-     * @param offset the offset within the classfile
+     * {@return the signed byte at the specified offset within the {@code class}
+     * file}  Reads a byte and sign-extends it to an {@code int}.
+     *
+     * @param offset the offset within the {@code class} file
      */
     int readS1(int offset);
 
     /**
-     * {@return the signed byte at the specified offset within the classfile}
-     * @param offset the offset within the classfile
+     * {@return the signed byte at the specified offset within the {@code class}
+     * file}  Reads a 2-byte value and sign-extends it to an {@code int}.
+     *
+     * @param offset the offset within the {@code class} file
      */
     int readS2(int offset);
 
     /**
-     * {@return the signed int at the specified offset within the classfile}
-     * @param offset the offset within the classfile
+     * {@return the signed int at the specified offset within the {@code class}
+     * file}  Reads 4 bytes of value.
+     *
+     * @param offset the offset within the {@code class} file
      */
     int readInt(int offset);
 
     /**
-     * {@return the signed long at the specified offset within the classfile}
-     * @param offset the offset within the classfile
+     * {@return the signed long at the specified offset within the {@code class}
+     * file}  Reads 8 bytes of value.
+     *
+     * @param offset the offset within the {@code class} file
      */
     long readLong(int offset);
 
     /**
-     * {@return the float value at the specified offset within the classfile}
-     * @param offset the offset within the classfile
+     * {@return the float value at the specified offset within the {@code class}
+     * file}  Reads 4 bytes of value.
+     * <p>
+     * In the conversions, all NaN values of the {@code float} may or may not be
+     * collapsed into a single {@linkplain Float#NaN "canonical" NaN value}.
+     *
+     * @param offset the offset within the {@code class} file
      */
     float readFloat(int offset);
 
     /**
-     * {@return the double value at the specified offset within the classfile}
-     * @param offset the offset within the classfile
+     * {@return the double value at the specified offset within the {@code
+     * class} file}  Reads 8 bytes of value.
+     * <p>
+     * In the conversions, all NaN values of the {@code double} may or may not
+     * be collapsed into a single {@linkplain Double#NaN "canonical" NaN value}.
+     *
+     * @param offset the offset within the {@code class} file
      */
     double readDouble(int offset);
 
     /**
-     * {@return a copy of the bytes at the specified range in the classfile}
-     * @param offset the offset within the classfile
+     * {@return a copy of the bytes at the specified range in the {@code class}
+     * file}
+     *
+     * @param offset the offset within the {@code class} file
      * @param len the length of the range
      */
     byte[] readBytes(int offset, int len);
 
     /**
-     * Copy a range of bytes from the classfile to a {@link BufWriter}
+     * Copy a range of bytes from the {@code class} file to a {@link BufWriter}.
      *
      * @param buf the {@linkplain BufWriter}
-     * @param offset the offset within the classfile
+     * @param offset the offset within the {@code class} file
      * @param len the length of the range
      */
     void copyBytesTo(BufWriter buf, int offset, int len);
diff --git a/src/java.base/share/classes/java/lang/classfile/ClassSignature.java b/src/java.base/share/classes/java/lang/classfile/ClassSignature.java
index 0e1329fd167..415332f0059 100644
--- a/src/java.base/share/classes/java/lang/classfile/ClassSignature.java
+++ b/src/java.base/share/classes/java/lang/classfile/ClassSignature.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2022, 2024, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2022, 2025, 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
@@ -24,6 +24,7 @@
  */
 package java.lang.classfile;
 
+import java.lang.classfile.attribute.SignatureAttribute;
 import java.util.List;
 
 import jdk.internal.classfile.impl.SignaturesImpl;
@@ -31,27 +32,53 @@
 import static java.util.Objects.requireNonNull;
 
 /**
- * Models the generic signature of a class file, as defined by JVMS {@jvms 4.7.9}.
+ * Models the generic signature of a class or interface, as defined by JVMS
+ * {@jvms 4.7.9.1}.
  *
+ * @see Class
+ * @see SignatureAttribute
+ * @jls 8.1 Class Declarations
+ * @jls 9.1 Interface Declarations
+ * @jvms 4.7.9.1 Signatures
  * @since 24
  */
 public sealed interface ClassSignature
         permits SignaturesImpl.ClassSignatureImpl {
 
-    /** {@return the type parameters of this class} */
+    /**
+     * {@return the type parameters of this class or interface, may be empty}
+     *
+     * @see Class#getTypeParameters()
+     * @jls 8.1.2 Generic Classes and Type Parameters
+     * @jls 9.1.2 Generic Interfaces and Type Parameters
+     */
     List<Signature.TypeParam> typeParameters();
 
-    /** {@return the instantiation of the superclass in this signature} */
+    /**
+     * {@return the instantiation of the superclass in this signature}
+     * Interfaces return a signature representing the {@link Object} class.
+     *
+     * @see Class#getGenericSuperclass()
+     * @jls 8.1.4 Superclasses and Subclasses
+     */
     Signature.ClassTypeSig superclassSignature();
 
-    /** {@return the instantiation of the interfaces in this signature} */
+    /**
+     * {@return the instantiation of the interfaces in this signature, may be
+     * empty}
+     *
+     * @see Class#getGenericInterfaces()
+     * @jls 8.1.5 Superinterfaces
+     * @jls 9.1.3 Superinterfaces and Subinterfaces
+     */
     List<Signature.ClassTypeSig> superinterfaceSignatures();
 
     /** {@return the raw signature string} */
     String signatureString();
 
     /**
-     * {@return a class signature}
+     * {@return a class signature with no type parameter declaration}
+     *
      * @param superclassSignature the superclass
      * @param superinterfaceSignatures the interfaces
      */
@@ -62,7 +89,7 @@ public static ClassSignature of(Signature.ClassTypeSig superclassSignature,
 
     /**
      * {@return a class signature}
-     * @param typeParameters the type parameters
+     * @param typeParameters the type parameters, may be empty
      * @param superclassSignature the superclass
      * @param superinterfaceSignatures the interfaces
      */
@@ -76,9 +103,11 @@ public static ClassSignature of(List<Signature.TypeParam> typeParameters,
     }
 
     /**
-     * Parses a raw class signature string into a {@linkplain Signature}
+     * Parses a raw class signature string into a {@linkplain Signature}.
+     *
      * @param classSignature the raw class signature string
      * @return class signature
+     * @throws IllegalArgumentException if the string is not a valid class signature string
      */
     public static ClassSignature parseFrom(String classSignature) {
         return new SignaturesImpl(classSignature).parseClassSignature();
diff --git a/src/java.base/share/classes/java/lang/classfile/CustomAttribute.java b/src/java.base/share/classes/java/lang/classfile/CustomAttribute.java
index f47ce9f055b..9f924588770 100644
--- a/src/java.base/share/classes/java/lang/classfile/CustomAttribute.java
+++ b/src/java.base/share/classes/java/lang/classfile/CustomAttribute.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2022, 2024, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2022, 2025, 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
@@ -24,16 +24,28 @@
  */
 package java.lang.classfile;
 
+import java.lang.classfile.constantpool.PoolEntry;
 import java.lang.classfile.constantpool.Utf8Entry;
+
 import jdk.internal.classfile.impl.TemporaryConstantPool;
 
 /**
- * Models a non-standard attribute of a classfile.  Clients should extend
- * this class to provide an implementation class for non-standard attributes,
- * and provide an {@link AttributeMapper} to mediate between the classfile
- * format and the {@linkplain CustomAttribute} representation.
- * @param <T> the custom attribute type
+ * Models a user-defined attribute in a {@code class} file.  API models for
+ * user-defined attributes should extend this class.  A user-defined attribute
+ * should also have an {@link AttributeMapper} defined, which will be returned
+ * by {@link #attributeMapper}, and registered to the {@link
+ * ClassFile.AttributeMapperOption} so the user-defined attributes can be read.
+ * <p>
+ * User-defined attributes are currently not delivered in the traversal of a
+ * {@link CodeModel}.
+ * <p>
+ * Accessor methods on user-defined attributes read from {@code class} files
+ * may throw {@link IllegalArgumentException} if the attribute model is lazily
+ * evaluated, and the evaluation encounters malformed {@code class} file format
+ * for the attribute.
  *
+ * @param <T> the custom attribute type
+ * @see java.lang.classfile.attribute
  * @since 24
  */
 public abstract non-sealed class CustomAttribute<T extends CustomAttribute<T>>
@@ -42,7 +54,8 @@ public abstract non-sealed class CustomAttribute<T extends CustomAttribute<T>>
     private final AttributeMapper<T> mapper;
 
     /**
-     * Construct a {@linkplain CustomAttribute}.
+     * Constructor for subclasses to call.
+     *
      * @param mapper the attribute mapper
      */
     protected CustomAttribute(AttributeMapper<T> mapper) {
@@ -54,6 +67,17 @@ public final AttributeMapper<T> attributeMapper() {
         return mapper;
     }
 
+    /**
+     * {@inheritDoc}
+     *
+     * @implSpec
+     * The default implementation returns a {@code Utf8Entry} suitable for
+     * writing only, which may be {@linkplain PoolEntry##unbound unbound}.
+     * Subclasses representing attributes read from {@code class} files must
+     * override this method.
+     *
+     * @see AttributeMapper#readAttribute
+     */
     @Override
     public Utf8Entry attributeName() {
         return TemporaryConstantPool.INSTANCE.utf8Entry(mapper.name());
diff --git a/src/java.base/share/classes/java/lang/classfile/MethodSignature.java b/src/java.base/share/classes/java/lang/classfile/MethodSignature.java
index e3889395e32..f81820a7f77 100644
--- a/src/java.base/share/classes/java/lang/classfile/MethodSignature.java
+++ b/src/java.base/share/classes/java/lang/classfile/MethodSignature.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2022, 2024, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2022, 2025, 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
@@ -24,7 +24,10 @@
  */
 package java.lang.classfile;
 
+import java.lang.classfile.attribute.SignatureAttribute;
 import java.lang.constant.MethodTypeDesc;
+import java.lang.reflect.Executable;
+import java.lang.reflect.Method;
 import java.util.List;
 
 import jdk.internal.classfile.impl.SignaturesImpl;
@@ -33,34 +36,68 @@
 import static java.util.Objects.requireNonNull;
 
 /**
- * Models the generic signature of a method, as defined by JVMS {@jvms 4.7.9}.
+ * Models the generic signature of a method or constructor, as defined by JVMS
+ * {@jvms 4.7.9.1}.
  *
+ * @see Executable
+ * @see SignatureAttribute
+ * @jls 8.4 Method Declarations
+ * @jls 8.8 Constructor Declarations
+ * @jvms 4.7.9.1 Signatures
  * @since 24
  */
 public sealed interface MethodSignature
         permits SignaturesImpl.MethodSignatureImpl {
 
-    /** {@return the type parameters of this method} */
+    /**
+     * {@return the type parameters of this method or constructor, may be empty}
+     *
+     * @see Executable#getTypeParameters()
+     * @jls 8.4.4 Generic Methods
+     * @jls 8.8.4 Generic Constructors
+     */
     List<Signature.TypeParam> typeParameters();
 
-    /** {@return the signatures of the parameters of this method} */
+    /**
+     * {@return the signatures of the parameters of this method or constructor,
+     * may be empty}  The parameters may differ from those in the method
+     * descriptor because some synthetic or implicit parameters are omitted.
+     *
+     * @see Executable#getGenericParameterTypes()
+     * @jls 8.4.1 Formal Parameters
+     * @jls 8.8.1 Formal Parameters
+     */
     List<Signature> arguments();
 
-    /** {@return the signatures of the return value of this method} */
+    /**
+     * {@return the signatures of the return value of this method}  For
+     * constructors, this returns a signature representing {@code void}.
+     *
+     * @see Method#getGenericReturnType()
+     * @jls 8.4.5 Method Result
+     */
     Signature result();
 
-    /** {@return the signatures of the exceptions thrown by this method} */
+    /**
+     * {@return the signatures of the exceptions thrown by this method or
+     * constructor}
+     *
+     * @see Executable#getGenericExceptionTypes()
+     * @jls 8.4.6 Method Throws
+     * @jls 8.8.5 Constructor Throws
+     */
     List<Signature.ThrowableSig> throwableSignatures();
 
     /** {@return the raw signature string} */
     String signatureString();
 
     /**
-     * {@return a method signature for a raw (no generic information) method descriptor}
+     * {@return a method signature for a raw method descriptor}  The resulting
+     * signature has no type parameter or exception type declared.
+     *
      * @param methodDescriptor the method descriptor
      */
     public static MethodSignature of(MethodTypeDesc methodDescriptor) {
-
         requireNonNull(methodDescriptor);
         return new SignaturesImpl.MethodSignatureImpl(
                 List.of(),
@@ -70,13 +107,15 @@ public static MethodSignature of(MethodTypeDesc methodDescriptor) {
     }
 
     /**
-     * {@return a method signature}
+     * {@return a method signature with no type parameter or exception type}
+     * The parameters may differ from those in the method descriptor because
+     * some synthetic or implicit parameters are omitted.
+     *
      * @param result signature for the return type
-     * @param arguments signatures for the method arguments
+     * @param arguments signatures for the method parameters
      */
     public static MethodSignature of(Signature result,
                                      Signature... arguments) {
-
         return new SignaturesImpl.MethodSignatureImpl(List.of(),
                                                       List.of(),
                                                       requireNonNull(result),
@@ -84,17 +123,19 @@ public static MethodSignature of(Signature result,
     }
 
     /**
-     * {@return a method signature}
+     * {@return a method signature}  The parameters may differ from those in
+     * the method descriptor because some synthetic or implicit parameters are
+     * omitted.
+     *
      * @param typeParameters signatures for the type parameters
      * @param exceptions signatures for the exceptions
      * @param result signature for the return type
-     * @param arguments signatures for the method arguments
+     * @param arguments signatures for the method parameters
      */
     public static MethodSignature of(List<Signature.TypeParam> typeParameters,
                                      List<Signature.ThrowableSig> exceptions,
                                      Signature result,
                                      Signature... arguments) {
-
         return new SignaturesImpl.MethodSignatureImpl(
                 List.copyOf(requireNonNull(typeParameters)),
                 List.copyOf(requireNonNull(exceptions)),
@@ -103,12 +144,14 @@ public static MethodSignature of(List<Signature.TypeParam> typeParameters,
     }
 
     /**
-     * Parses a raw method signature string into a {@linkplain MethodSignature}
+     * Parses a raw method signature string into a {@code MethodSignature}.
+     *
      * @param methodSignature the raw method signature string
-     * @return method signature
+     * @return the parsed method signature
+     * @throws IllegalArgumentException if the string is not a valid method
+     *         signature string
      */
     public static MethodSignature parseFrom(String methodSignature) {
-
         return new SignaturesImpl(methodSignature).parseMethodSignature();
     }
 }
diff --git a/src/java.base/share/classes/java/lang/classfile/Signature.java b/src/java.base/share/classes/java/lang/classfile/Signature.java
index ad2dca0ad46..eef86d5a7a1 100644
--- a/src/java.base/share/classes/java/lang/classfile/Signature.java
+++ b/src/java.base/share/classes/java/lang/classfile/Signature.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2022, 2024, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2022, 2025, 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
@@ -24,7 +24,15 @@
  */
 package java.lang.classfile;
 
+import java.lang.classfile.attribute.SignatureAttribute;
+import java.lang.classfile.constantpool.ClassEntry;
 import java.lang.constant.ClassDesc;
+import java.lang.reflect.GenericArrayType;
+import java.lang.reflect.GenericDeclaration;
+import java.lang.reflect.ParameterizedType;
+import java.lang.reflect.Type;
+import java.lang.reflect.TypeVariable;
+import java.lang.reflect.WildcardType;
 import java.util.List;
 import java.util.Optional;
 
@@ -36,6 +44,10 @@
 /**
  * Models generic Java type signatures, as defined in JVMS {@jvms 4.7.9.1}.
  *
+ * @see Type
+ * @see SignatureAttribute
+ * @jls 4.1 The Kinds of Types and Values
+ * @jvms 4.7.9.1 Signatures
  * @sealedGraph
  * @since 24
  */
@@ -45,16 +57,21 @@ public sealed interface Signature {
     String signatureString();
 
     /**
-     * Parses generic Java type signature from raw string
+     * Parses a Java type signature from a raw string.
+     *
      * @param javaTypeSignature raw Java type signature string
-     * @return Java type signature
+     * @return a Java type signature
+     * @throws IllegalArgumentException if the string is not a valid Java type
+     *         signature string
      */
     public static Signature parseFrom(String javaTypeSignature) {
         return new SignaturesImpl(javaTypeSignature).parseSignature();
     }
 
     /**
-     * {@return a Java type signature}
+     * {@return a Java type signature from a field descriptor}  The returned
+     * signature represents a reifiable type (JLS {@jls 4.7}).
+     *
      * @param classDesc the symbolic description of the Java type
      */
     public static Signature of(ClassDesc classDesc) {
@@ -67,8 +84,10 @@ public static Signature of(ClassDesc classDesc) {
     }
 
     /**
-     * Models the signature of a primitive type or void
+     * Models the signature of a primitive type (JLS {@jls 4.2}) or void.
      *
+     * @jls 4.2 Primitive Types and Values
+     * @jvms 4.7.9.1 Signatures
      * @since 24
      */
     public sealed interface BaseTypeSig extends Signature
@@ -81,6 +100,8 @@ public sealed interface BaseTypeSig extends Signature
          * {@return the signature of a primitive type or void}
          * @param classDesc a symbolic descriptor for the base type, must correspond
          *                  to a primitive type
+         * @throws IllegalArgumentException if the {@code classDesc} is not
+         *         primitive
          */
         public static BaseTypeSig of(ClassDesc classDesc) {
             requireNonNull(classDesc);
@@ -92,6 +113,8 @@ public static BaseTypeSig of(ClassDesc classDesc) {
         /**
          * {@return the signature of a primitive type or void}
          * @param baseType the single-letter descriptor for the base type
+         * @throws IllegalArgumentException if the {@code baseType} is not a
+         *         valid descriptor character for a primitive type or void
          */
         public static BaseTypeSig of(char baseType) {
             if ("VIJCSBFDZ".indexOf(baseType) < 0)
@@ -104,6 +127,8 @@ public static BaseTypeSig of(char baseType) {
      * Models the signature of a reference type, which may be a class, interface,
      * type variable, or array type.
      *
+     * @jls 4.3 Reference Types and Values
+     * @jvms 4.7.9.1 Signatures
      * @sealedGraph
      * @since 24
      */
@@ -115,42 +140,68 @@ public sealed interface RefTypeSig
     /**
      * Models the signature of a possibly-parameterized class or interface type.
      *
+     * @see Type
+     * @see ParameterizedType
+     * @jvms 4.7.9.1 Signatures
      * @since 24
      */
     public sealed interface ClassTypeSig
             extends RefTypeSig, ThrowableSig
             permits SignaturesImpl.ClassTypeSigImpl {
 
-        /** {@return the signature of the outer type, if any} */
+        /**
+         * {@return the signature of the class that this class is a member of,
+         * only if this is a member class}  Note that the outer class may be
+         * absent if it is not a parameterized type.
+         *
+         * @jls 4.5 Parameterized Types
+         */
         Optional<ClassTypeSig> outerType();
 
-        /** {@return the class name} */
+        /**
+         * {@return the class or interface name; includes the {@linkplain
+         * ClassEntry##internalname slash-separated} package name if there is no
+         * outer type}
+         */
         String className();
 
-        /** {@return the class name, as a symbolic descriptor} */
+        /**
+         * {@return this class or interface, as a symbolic descriptor}
+         */
         default ClassDesc classDesc() {
             var outer = outerType();
             return outer.isEmpty() ? ClassDesc.ofInternalName(className())
                     : outer.get().classDesc().nested(className());
         }
 
-        /** {@return the type arguments of the class} */
+        /**
+         * {@return the type arguments of this class or interface}
+         * Note that the outer type may have more type arguments.
+         *
+         * @jls 4.5 Parameterized Types
+         */
         List<TypeArg> typeArgs();
 
         /**
-         * {@return a class type signature}
-         * @param className the name of the class
-         * @param typeArgs signatures of the type arguments
+         * {@return a class or interface signature without an outer type}
+         *
+         * @param className the name of the class or interface
+         * @param typeArgs the type arguments
+         * @throws IllegalArgumentException if {@code className} does not
+         *         represent a class or interface
          */
         public static ClassTypeSig of(ClassDesc className, TypeArg... typeArgs) {
             return of(null, className, typeArgs);
         }
 
         /**
-         * {@return a class type signature for an inner class}
-         * @param outerType signature of the outer type
-         * @param className the name of the class
-         * @param typeArgs signatures of the type arguments
+         * {@return a class or interface signature}
+         *
+         * @param outerType signature of the outer type, may be {@code null}
+         * @param className the name of this class or interface
+         * @param typeArgs the type arguments
+         * @throws IllegalArgumentException if {@code className} does not
+         *         represent a class or interface
          */
         public static ClassTypeSig of(ClassTypeSig outerType, ClassDesc className, TypeArg... typeArgs) {
             requireNonNull(className);
@@ -158,19 +209,21 @@ public static ClassTypeSig of(ClassTypeSig outerType, ClassDesc className, TypeA
         }
 
         /**
-         * {@return a class type signature}
-         * @param className the name of the class
-         * @param typeArgs signatures of the type arguments
+         * {@return a class or interface signature without an outer type}
+         *
+         * @param className the name of the class or interface
+         * @param typeArgs the type arguments
          */
         public static ClassTypeSig of(String className, TypeArg... typeArgs) {
             return of(null, className, typeArgs);
         }
 
         /**
-         * {@return a class type signature for an inner class}
-         * @param outerType signature of the outer type
-         * @param className the name of the class
-         * @param typeArgs signatures of the type arguments
+         * {@return a class type signature}
+         *
+         * @param outerType signature of the outer type, may be {@code null}
+         * @param className the name of this class or interface
+         * @param typeArgs the type arguments
          */
         public static ClassTypeSig of(ClassTypeSig outerType, String className, TypeArg... typeArgs) {
             requireNonNull(className);
@@ -179,15 +232,25 @@ public static ClassTypeSig of(ClassTypeSig outerType, String className, TypeArg.
     }
 
     /**
-     * Models the type argument.
+     * Models a type argument, an argument to a type parameter.
      *
+     * @see Type
+     * @see WildcardType
+     * @jls 4.5.1 Type Arguments of Parameterized Types
+     * @jvms 4.7.9.1 Signatures
      * @sealedGraph
      * @since 24
      */
     public sealed interface TypeArg {
 
         /**
-         * Models an unbounded type argument {@code *}.
+         * Models an unbounded wildcard type argument {@code *}, or {@code
+         * ?} in Java programs.  This type argument has an implicit upper
+         * bound of {@link Object}.
+         *
+         * @see WildcardType#getUpperBounds()
+         * @jls 4.5.1 Type Arguments of Parameterized Types
+         * @jvms 4.7.9.1 Signatures
          * @since 24
          */
         public sealed interface Unbounded extends TypeArg permits SignaturesImpl.UnboundedTypeArgImpl {
@@ -195,31 +258,46 @@ public sealed interface Unbounded extends TypeArg permits SignaturesImpl.Unbound
 
         /**
          * Models a type argument with an explicit bound type.
+         *
+         * @jls 4.5.1 Type Arguments of Parameterized Types
+         * @jvms 4.7.9.1 Signatures
          * @since 24
          */
         public sealed interface Bounded extends TypeArg permits SignaturesImpl.TypeArgImpl {
 
             /**
              * Models a type argument's wildcard indicator.
+             *
+             * @jls 4.5.1 Type Arguments of Parameterized Types
+             * @jvms 4.7.9.1 Signatures
              * @since 24
              */
             public enum WildcardIndicator {
 
                 /**
-                 * No wildcard (empty), an exact type. Also known as
-                 * {@index invariant}.
+                 * No wildcard (empty), an exact type.  Also known as
+                 * {@index invariant}.  This is the direct use of a
+                 * reference type in Java programs.
+                 *
+                 * @see Type
                  */
                 NONE,
 
                 /**
-                 * Upper-bound indicator {@code +}. Also known as
-                 * {@index covariant}.
+                 * Upper-bound indicator {@code +}.  Also known as
+                 * {@index covariant}.  This is the {@code ? extends}
+                 * prefix in Java programs.
+                 *
+                 * @see WildcardType#getUpperBounds()
                  */
                 EXTENDS,
 
                 /**
-                 * Lower-bound indicator {@code -}. Also known as
-                 * {@index contravariant}.
+                 * Lower-bound indicator {@code -}.  Also known as
+                 * {@index contravariant}.  This is the {@code ? super}
+                 * prefix in Java programs.
+                 *
+                 * @see WildcardType#getLowerBounds()
                  */
                 SUPER;
             }
@@ -232,8 +310,10 @@ public enum WildcardIndicator {
         }
 
         /**
-         * {@return a bounded type arg}
-         * @param boundType the bound
+         * {@return a type argument of a reference type}
+         *
+         * @param boundType the reference type
+         * @see Bounded.WildcardIndicator#NONE
          */
         public static TypeArg.Bounded of(RefTypeSig boundType) {
             requireNonNull(boundType);
@@ -241,15 +321,17 @@ public static TypeArg.Bounded of(RefTypeSig boundType) {
         }
 
         /**
-         * {@return an unbounded type arg}
+         * {@return an unbounded wildcard type argument {@code *}}
          */
         public static TypeArg.Unbounded unbounded() {
             return SignaturesImpl.UnboundedTypeArgImpl.INSTANCE;
         }
 
         /**
-         * {@return an upper-bounded type arg}
+         * {@return an upper-bounded wildcard type argument}
+         *
          * @param boundType the upper bound
+         * @see Bounded.WildcardIndicator#EXTENDS
          */
         public static TypeArg.Bounded extendsOf(RefTypeSig boundType) {
             requireNonNull(boundType);
@@ -257,8 +339,10 @@ public static TypeArg.Bounded extendsOf(RefTypeSig boundType) {
         }
 
         /**
-         * {@return a lower-bounded type arg}
+         * {@return a lower-bounded wildcard type argument}
+         *
          * @param boundType the lower bound
+         * @see Bounded.WildcardIndicator#SUPER
          */
         public static TypeArg.Bounded superOf(RefTypeSig boundType) {
             requireNonNull(boundType);
@@ -266,9 +350,10 @@ public static TypeArg.Bounded superOf(RefTypeSig boundType) {
         }
 
         /**
-         * {@return a bounded type arg}
-         * @param wildcard the wild card
-         * @param boundType optional bound type
+         * {@return a bounded type argument}
+         *
+         * @param wildcard the wildcard indicator
+         * @param boundType the bound type
          */
         public static TypeArg.Bounded bounded(Bounded.WildcardIndicator wildcard, RefTypeSig boundType) {
             requireNonNull(wildcard);
@@ -278,8 +363,13 @@ public static TypeArg.Bounded bounded(Bounded.WildcardIndicator wildcard, RefTyp
     }
 
     /**
-     * Models the signature of a type variable.
+     * Models the signature of a type variable.  A type variable is introduced
+     * by a {@linkplain TypeParam type parameter} declaration.
      *
+     * @see TypeVariable
+     * @see TypeParam
+     * @jls 4.4 Type Variables
+     * @jvms 4.7.9.1 Signatures
      * @since 24
      */
     public sealed interface TypeVarSig
@@ -291,6 +381,7 @@ public sealed interface TypeVarSig
 
         /**
          * {@return a signature for a type variable}
+         *
          * @param identifier the name of the type variable
          */
         public static TypeVarSig of(String identifier) {
@@ -301,6 +392,10 @@ public static TypeVarSig of(String identifier) {
     /**
      * Models the signature of an array type.
      *
+     * @see Type
+     * @see GenericArrayType
+     * @jls 10.1 Array Types
+     * @jvms 4.7.9.1 Signatures
      * @since 24
      */
     public sealed interface ArrayTypeSig
@@ -311,7 +406,7 @@ public sealed interface ArrayTypeSig
         Signature componentSignature();
 
         /**
-         * {@return a signature for an array type}
+         * {@return an array type with the given component type}
          * @param componentSignature the component type
          */
         public static ArrayTypeSig of(Signature componentSignature) {
@@ -322,6 +417,8 @@ public static ArrayTypeSig of(Signature componentSignature) {
          * {@return a signature for an array type}
          * @param dims the dimension of the array
          * @param componentSignature the component type
+         * @throws IllegalArgumentException if the resulting array type exceeds
+         *         255 dimensions
          */
         public static ArrayTypeSig of(int dims, Signature componentSignature) {
             requireNonNull(componentSignature);
@@ -334,8 +431,15 @@ public static ArrayTypeSig of(int dims, Signature componentSignature) {
     }
 
     /**
-     * Models a signature for a type parameter of a generic class or method.
+     * Models a signature for a type parameter of a generic class, interface,
+     * method, or constructor, which introduces a {@linkplain TypeVarSig type
+     * variable}.
      *
+     * @see GenericDeclaration#getTypeParameters()
+     * @see TypeVariable
+     * @see TypeVarSig
+     * @jls 4.4 Type Variables
+     * @jvms 4.7.9.1 Signatures
      * @since 24
      */
     public sealed interface TypeParam
@@ -344,16 +448,23 @@ public sealed interface TypeParam
         /** {@return the name of the type parameter} */
         String identifier();
 
-        /** {@return the class bound of the type parameter} */
+        /**
+         * {@return the class bound of the type parameter}  This may be empty
+         * if this type parameter only has interface bounds.
+         */
         Optional<RefTypeSig> classBound();
 
-        /** {@return the interface bounds of the type parameter} */
+        /**
+         * {@return the interface bounds of the type parameter}  This may be
+         * empty.
+         */
         List<RefTypeSig> interfaceBounds();
 
         /**
          * {@return a signature for a type parameter}
+         *
          * @param identifier the name of the type parameter
-         * @param classBound the class bound of the type parameter
+         * @param classBound the class bound of the type parameter, may be {@code null}
          * @param interfaceBounds the interface bounds of the type parameter
          */
         public static TypeParam of(String identifier, RefTypeSig classBound, RefTypeSig... interfaceBounds) {
@@ -365,8 +476,9 @@ public static TypeParam of(String identifier, RefTypeSig classBound, RefTypeSig.
 
         /**
          * {@return a signature for a type parameter}
+         *
          * @param identifier the name of the type parameter
-         * @param classBound the class bound of the type parameter
+         * @param classBound the optional class bound of the type parameter
          * @param interfaceBounds the interface bounds of the type parameter
          */
         public static TypeParam of(String identifier, Optional<RefTypeSig> classBound, RefTypeSig... interfaceBounds) {
@@ -378,8 +490,10 @@ public static TypeParam of(String identifier, Optional<RefTypeSig> classBound, R
     }
 
     /**
-     * Models a signature for a throwable type.
+     * Marker interface for a signature for a throwable type.
      *
+     * @jls 8.4.6 Method Throws
+     * @jvms 4.7.9.1 Signatures
      * @sealedGraph
      * @since 24
      */
diff --git a/src/java.base/share/classes/java/lang/classfile/TypeAnnotation.java b/src/java.base/share/classes/java/lang/classfile/TypeAnnotation.java
index 9353b30a643..68514a2436c 100644
--- a/src/java.base/share/classes/java/lang/classfile/TypeAnnotation.java
+++ b/src/java.base/share/classes/java/lang/classfile/TypeAnnotation.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2022, 2024, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2022, 2025, 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
@@ -59,6 +59,7 @@ public sealed interface TypeAnnotation
     /**
      * The kind of target on which the annotation appears, as defined in JVMS {@jvms 4.7.20.1}.
      *
+     * @see TargetInfo#targetType()
      * @since 24
      */
     public enum TargetType {
@@ -189,6 +190,7 @@ static TypeAnnotation of(TargetInfo targetInfo, List<TypePathComponent> targetPa
     /**
      * Specifies which type in a declaration or expression is being annotated.
      *
+     * @see #targetInfo()
      * @sealedGraph
      * @since 24
      */
@@ -440,8 +442,11 @@ static EmptyTarget ofMethodReceiver() {
         }
 
         /**
-         * {@return a target for annotations on the type in a formal parameter declaration of a method,
-         * constructor, or lambda expression}
+         * {@return a target for annotations on the type in a formal parameter
+         * declaration of a method, constructor, or lambda expression}  The
+         * index may differ from the index in the method descriptor because some
+         * synthetic or implicit parameters are omitted.
+         *
          * @param formalParameterIndex specifies which formal parameter declaration has an annotated type
          */
         static FormalParameterTarget ofMethodFormalParameter(int formalParameterIndex) {
@@ -498,7 +503,7 @@ static CatchTarget ofExceptionParameter(int exceptionTableIndex) {
          * @param targetType {@link TargetType#INSTANCEOF}, {@link TargetType#NEW},
          *                   {@link TargetType#CONSTRUCTOR_REFERENCE},
          *                   or {@link TargetType#METHOD_REFERENCE}
-         * @param target the code label corresponding to the instruction
+         * @param target the label right before the instruction
          */
         static OffsetTarget ofOffset(TargetType targetType, Label target) {
             return new TargetInfoImpl.OffsetTargetImpl(targetType, target);
@@ -506,7 +511,7 @@ static OffsetTarget ofOffset(TargetType targetType, Label target) {
 
         /**
          * {@return a target for annotations on the type in an instanceof expression}
-         * @param target the code label corresponding to the instruction
+         * @param target the label right before the instruction
          */
         static OffsetTarget ofInstanceofExpr(Label target) {
             return ofOffset(TargetType.INSTANCEOF, target);
@@ -514,7 +519,7 @@ static OffsetTarget ofInstanceofExpr(Label target) {
 
         /**
          * {@return a target for annotations on the type in a new expression}
-         * @param target the code label corresponding to the instruction
+         * @param target the label right before the instruction
          */
         static OffsetTarget ofNewExpr(Label target) {
             return ofOffset(TargetType.NEW, target);
@@ -522,7 +527,7 @@ static OffsetTarget ofNewExpr(Label target) {
 
         /**
          * {@return a target for annotations on the type before the :: in a constructor reference expression}
-         * @param target the code label corresponding to the instruction
+         * @param target the label right before the instruction
          */
         static OffsetTarget ofConstructorReference(Label target) {
             return ofOffset(TargetType.CONSTRUCTOR_REFERENCE, target);
@@ -530,7 +535,7 @@ static OffsetTarget ofConstructorReference(Label target) {
 
         /**
          * {@return a target for annotations on the type before the :: in a method reference expression}
-         * @param target the code label corresponding to the instruction
+         * @param target the label right before the instruction
          */
         static OffsetTarget ofMethodReference(Label target) {
             return ofOffset(TargetType.METHOD_REFERENCE, target);
@@ -545,7 +550,7 @@ static OffsetTarget ofMethodReference(Label target) {
          *                   {@link TargetType#METHOD_INVOCATION_TYPE_ARGUMENT},
          *                   {@link TargetType#CONSTRUCTOR_REFERENCE_TYPE_ARGUMENT},
          *                   or {@link TargetType#METHOD_REFERENCE_TYPE_ARGUMENT}
-         * @param target the code label corresponding to the instruction
+         * @param target the label right before the instruction
          * @param typeArgumentIndex specifies which type in the cast operator or argument is annotated
          */
         static TypeArgumentTarget ofTypeArgument(TargetType targetType, Label target, int typeArgumentIndex) {
@@ -554,7 +559,7 @@ static TypeArgumentTarget ofTypeArgument(TargetType targetType, Label target, in
 
         /**
          * {@return a target for annotations on the i'th type in a cast expression}
-         * @param target the code label corresponding to the instruction
+         * @param target the label right before the instruction
          * @param typeArgumentIndex specifies which type in the cast operator is annotated
          */
         static TypeArgumentTarget ofCastExpr(Label target, int typeArgumentIndex) {
@@ -564,7 +569,7 @@ static TypeArgumentTarget ofCastExpr(Label target, int typeArgumentIndex) {
         /**
          * {@return a target for annotations on the i'th type argument in the explicit type argument list for
          * an explicit constructor invocation statement}
-         * @param target the code label corresponding to the instruction
+         * @param target the label right before the instruction
          * @param typeArgumentIndex specifies which type in the argument is annotated
          */
         static TypeArgumentTarget ofConstructorInvocationTypeArgument(Label target, int typeArgumentIndex) {
@@ -574,7 +579,7 @@ static TypeArgumentTarget ofConstructorInvocationTypeArgument(Label target, int
         /**
          * {@return a target for annotations on the i'th type argument in the explicit type argument list for
          * a method invocation expression}
-         * @param target the code label corresponding to the instruction
+         * @param target the label right before the instruction
          * @param typeArgumentIndex specifies which type in the argument is annotated
          */
         static TypeArgumentTarget ofMethodInvocationTypeArgument(Label target, int typeArgumentIndex) {
@@ -584,7 +589,7 @@ static TypeArgumentTarget ofMethodInvocationTypeArgument(Label target, int typeA
         /**
          * {@return a target for annotations on the i'th type argument in the explicit type argument list for
          * a new expression}
-         * @param target the code label corresponding to the instruction
+         * @param target the label right before the instruction
          * @param typeArgumentIndex specifies which type in the argument is annotated
          */
         static TypeArgumentTarget ofConstructorReferenceTypeArgument(Label target, int typeArgumentIndex) {
@@ -594,7 +599,7 @@ static TypeArgumentTarget ofConstructorReferenceTypeArgument(Label target, int t
         /**
          * {@return a target for annotations on the i'th type argument in the explicit type argument list for
          * a method reference expression}
-         * @param target the code label corresponding to the instruction
+         * @param target the label right before the instruction
          * @param typeArgumentIndex specifies which type in the argument is annotated
          */
         static TypeArgumentTarget ofMethodReferenceTypeArgument(Label target, int typeArgumentIndex) {
@@ -607,6 +612,9 @@ static TypeArgumentTarget ofMethodReferenceTypeArgument(Label target, int typeAr
      * parameter of a generic class, generic interface, generic method, or
      * generic constructor.
      *
+     * @see #ofTypeParameter(TargetType, int)
+     * @see #ofClassTypeParameter(int)
+     * @see #ofMethodTypeParameter(int)
      * @since 24
      */
     sealed interface TypeParameterTarget extends TargetInfo
@@ -625,6 +633,7 @@ sealed interface TypeParameterTarget extends TargetInfo
      * Indicates that an annotation appears on a type in the extends or implements
      * clause of a class or interface declaration.
      *
+     * @see #ofClassExtends(int)
      * @since 24
      */
     sealed interface SupertypeTarget extends TargetInfo
@@ -648,6 +657,9 @@ sealed interface SupertypeTarget extends TargetInfo
      * type parameter declaration of a generic class, interface, method, or
      * constructor.
      *
+     * @see #ofTypeParameterBound(TargetType, int, int)
+     * @see #ofClassTypeParameterBound(int, int)
+     * @see #ofMethodTypeParameterBound(int, int)
      * @since 24
      */
     sealed interface TypeParameterBoundTarget extends TargetInfo
@@ -673,6 +685,10 @@ sealed interface TypeParameterBoundTarget extends TargetInfo
      * declaration, the return type of a method, the type of a newly constructed
      * object, or the receiver type of a method or constructor.
      *
+     * @see #of(TargetType)
+     * @see #ofField()
+     * @see #ofMethodReturn()
+     * @see #ofMethodReceiver()
      * @since 24
      */
     sealed interface EmptyTarget extends TargetInfo
@@ -683,16 +699,17 @@ sealed interface EmptyTarget extends TargetInfo
      * Indicates that an annotation appears on the type in a formal parameter
      * declaration of a method, constructor, or lambda expression.
      *
+     * @see #ofMethodFormalParameter(int)
      * @since 24
      */
     sealed interface FormalParameterTarget extends TargetInfo
             permits TargetInfoImpl.FormalParameterTargetImpl {
 
         /**
-         * Which formal parameter declaration has an annotated type.
-         *
-         * @return the index into the formal parameter declarations, in the order
-         * declared in the source code
+         * {@return the index into the formal parameter declarations, in the
+         * order declared in the source code}  The index may differ from the
+         * index in the method descriptor because some synthetic or implicit
+         * parameters are omitted.
          */
         int formalParameterIndex();
     }
@@ -701,6 +718,7 @@ sealed interface FormalParameterTarget extends TargetInfo
      * Indicates that an annotation appears on the i'th type in the throws
      * clause of a method or constructor declaration.
      *
+     * @see #ofThrows(int)
      * @since 24
      */
     sealed interface ThrowsTarget extends TargetInfo
@@ -720,13 +738,14 @@ sealed interface ThrowsTarget extends TargetInfo
      * Indicates that an annotation appears on the type in a local variable declaration,
      * including a variable declared as a resource in a try-with-resources statement.
      *
+     * @see #ofLocalVariable(List)
      * @since 24
      */
     sealed interface LocalVarTarget extends TargetInfo
             permits TargetInfoImpl.LocalVarTargetImpl {
 
         /**
-         * {@return the table of local variable location/indices.}
+         * {@return the table of local variable location/indices}
          */
         List<LocalVarTargetInfo> table();
     }
@@ -736,6 +755,7 @@ sealed interface LocalVarTarget extends TargetInfo
      * has a value, and the index into the local variable array of the current
      * frame at which that local variable can be found.
      *
+     * @see LocalVarTarget
      * @since 24
      */
     sealed interface LocalVarTargetInfo
@@ -782,6 +802,7 @@ static LocalVarTargetInfo of(Label startLabel, Label endLabel, int index) {
      * Indicates that an annotation appears on the i'th type in an exception parameter
      * declaration.
      *
+     * @see #ofExceptionParameter(int)
      * @since 24
      */
     sealed interface CatchTarget extends TargetInfo
@@ -800,17 +821,22 @@ sealed interface CatchTarget extends TargetInfo
      * Indicates that an annotation appears on either the type in an instanceof expression
      * or a new expression, or the type before the :: in a method reference expression.
      *
+     * @see #ofOffset(TargetType, Label)
+     * @see #ofNewExpr(Label)
+     * @see #ofInstanceofExpr(Label)
+     * @see #ofConstructorReference(Label)
+     * @see #ofMethodReference(Label)
      * @since 24
      */
     sealed interface OffsetTarget extends TargetInfo
             permits TargetInfoImpl.OffsetTargetImpl {
 
         /**
-         * The code array offset of either the bytecode instruction
-         * corresponding to the instanceof expression, the new bytecode instruction corresponding to the new
-         * expression, or the bytecode instruction corresponding to the method reference expression.
+         * The label right before the {@link Instruction} corresponding to the
+         * instanceof expression, the new expression, or the method reference
+         * expression.
          *
-         * @return the code label corresponding to the instruction
+         * @return the label right before the instruction
          */
         Label target();
     }
@@ -821,19 +847,24 @@ sealed interface OffsetTarget extends TargetInfo
      * expression, an explicit constructor invocation statement, a method invocation expression, or a method reference
      * expression.
      *
+     * @see #ofTypeArgument(TargetType, Label, int)
+     * @see #ofCastExpr(Label, int)
+     * @see #ofConstructorInvocationTypeArgument(Label, int)
+     * @see #ofConstructorReferenceTypeArgument(Label, int)
+     * @see #ofMethodInvocationTypeArgument(Label, int)
+     * @see #ofMethodReferenceTypeArgument(Label, int)
      * @since 24
      */
     sealed interface TypeArgumentTarget extends TargetInfo
             permits TargetInfoImpl.TypeArgumentTargetImpl {
 
         /**
-         * The code array offset of either the bytecode instruction
-         * corresponding to the cast expression, the new bytecode instruction corresponding to the new expression, the
-         * bytecode instruction corresponding to the explicit constructor invocation statement, the bytecode
-         * instruction corresponding to the method invocation expression, or the bytecode instruction corresponding to
-         * the method reference expression.
+         * The label right before the {@link Instruction} corresponding to the
+         * cast expression, the new expression, the explicit constructor
+         * invocation statement, the method invocation expression, or the method
+         * reference expression.
          *
-         * @return the code label corresponding to the instruction
+         * @return the label right before the instruction
          */
         Label target();
 
@@ -856,6 +887,7 @@ sealed interface TypeArgumentTarget extends TargetInfo
      * JVMS: Type_path structure identifies which part of the type is annotated,
      * as defined in JVMS {@jvms 4.7.20.2}
      *
+     * @see #targetPath()
      * @since 24
      */
     sealed interface TypePathComponent
diff --git a/src/java.base/share/classes/java/lang/classfile/attribute/AnnotationDefaultAttribute.java b/src/java.base/share/classes/java/lang/classfile/attribute/AnnotationDefaultAttribute.java
index 206c0a84087..f92f4261324 100644
--- a/src/java.base/share/classes/java/lang/classfile/attribute/AnnotationDefaultAttribute.java
+++ b/src/java.base/share/classes/java/lang/classfile/attribute/AnnotationDefaultAttribute.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2022, 2024, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2022, 2025, 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
@@ -27,24 +27,31 @@
 
 import java.lang.classfile.AnnotationValue;
 import java.lang.classfile.Attribute;
+import java.lang.classfile.AttributeMapper;
+import java.lang.classfile.AttributeMapper.AttributeStability;
+import java.lang.classfile.Attributes;
+import java.lang.classfile.ClassFile;
 import java.lang.classfile.MethodElement;
-import java.lang.classfile.MethodModel;
+import java.lang.reflect.Method;
 
 import jdk.internal.classfile.impl.BoundAttribute;
 import jdk.internal.classfile.impl.UnboundAttribute;
 
 /**
- * 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}.
+ * Models the {@link Attributes#annotationDefault() AnnotationDefault} attribute
+ * (JVMS {@jvms 4.7.22}), which records the default value (JLS {@jls 9.6.2}) for
+ * the annotation interface element defined by this method.
  * <p>
- * The attribute does not permit multiple instances in a given location.
- * Subsequent occurrence of the attribute takes precedence during the attributed
- * element build or transformation.
+ * This attribute only appears on methods, and does not permit {@linkplain
+ * AttributeMapper#allowMultiple multiple instances} in a method.  It has a
+ * data dependency on the {@linkplain AttributeStability#CP_REFS constant pool}.
  * <p>
- * The attribute was introduced in the Java SE Platform version 5.0.
+ * This attribute was introduced in the Java SE Platform version 5.0, major
+ * version {@value ClassFile#JAVA_5_VERSION}.
  *
+ * @see Attributes#annotationDefault()
+ * @jls 9.6.2 Defaults for Annotation Interface Elements
+ * @jvms 4.7.22 The {@code AnnotationDefault} Attribute
  * @since 24
  */
 public sealed interface AnnotationDefaultAttribute
@@ -53,14 +60,16 @@ public sealed interface AnnotationDefaultAttribute
                 UnboundAttribute.UnboundAnnotationDefaultAttribute {
 
     /**
-     * {@return the default value of the annotation type element represented by
-     * this method}
+     * {@return the default value of the annotation interface element defined by
+     * the enclosing method}
+     *
+     * @see Method#getDefaultValue()
      */
     AnnotationValue defaultValue();
 
     /**
      * {@return an {@code AnnotationDefault} attribute}
-     * @param annotationDefault the default value of the annotation type element
+     * @param annotationDefault the default value of the annotation interface element
      */
     static AnnotationDefaultAttribute of(AnnotationValue annotationDefault) {
         return new UnboundAttribute.UnboundAnnotationDefaultAttribute(annotationDefault);
diff --git a/src/java.base/share/classes/java/lang/classfile/attribute/BootstrapMethodsAttribute.java b/src/java.base/share/classes/java/lang/classfile/attribute/BootstrapMethodsAttribute.java
index bbea96dc162..0ed08f63512 100644
--- a/src/java.base/share/classes/java/lang/classfile/attribute/BootstrapMethodsAttribute.java
+++ b/src/java.base/share/classes/java/lang/classfile/attribute/BootstrapMethodsAttribute.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2022, 2024, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2022, 2025, 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
@@ -26,24 +26,41 @@
 package java.lang.classfile.attribute;
 
 import java.lang.classfile.Attribute;
+import java.lang.classfile.AttributeMapper;
+import java.lang.classfile.AttributeMapper.AttributeStability;
+import java.lang.classfile.Attributes;
 import java.lang.classfile.BootstrapMethodEntry;
+import java.lang.classfile.ClassFile;
+import java.lang.classfile.ClassModel;
 import java.lang.classfile.constantpool.ConstantPool;
+import java.lang.classfile.constantpool.ConstantPoolBuilder;
 import java.util.List;
 
 import jdk.internal.classfile.impl.BoundAttribute;
 import jdk.internal.classfile.impl.UnboundAttribute;
 
 /**
- * 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}.
+ * Models the {@link Attributes#bootstrapMethods() BootstrapMethods} attribute
+ * (JVMS {@jvms 4.7.23}), which stores symbolic information for the execution of
+ * bootstrap methods, used by dynamically-computed call sites and constants.
+ * It is logically a part of the constant pool of a {@code class} file and thus
+ * not delivered in {@link ClassModel} traversal; its elements are accessible
+ * through {@link ConstantPool}.
  * <p>
- * The attribute does not permit multiple instances in a given location.
- * Subsequent occurrence of the attribute takes precedence during the attributed
- * element build or transformation.
+ * This attribute only appears on classes, and does not permit {@linkplain
+ * AttributeMapper#allowMultiple multiple instances} in a class.  It has a
+ * data dependency on the {@linkplain AttributeStability#CP_REFS constant pool}.
  * <p>
- * The attribute was introduced in the Java SE Platform version 7.
+ * This attribute cannot be constructed directly; its entries can be constructed
+ * through {@link ConstantPoolBuilder#bsmEntry}, resulting in at most one
+ * attribute instance in the built {@code class} file.
+ * <p>
+ * The attribute was introduced in the Java SE Platform version 7, major version
+ * {@value ClassFile#JAVA_7_VERSION}.
  *
+ * @see Attributes#bootstrapMethods()
+ * @see java.lang.invoke##bsm Execution of bootstrap methods
+ * @jvms 4.7.23 The {@code BootstrapMethods} Attribute
  * @since 24
  */
 public sealed interface BootstrapMethodsAttribute
@@ -57,8 +74,7 @@ public sealed interface BootstrapMethodsAttribute
     List<BootstrapMethodEntry> bootstrapMethods();
 
     /**
-     * {@return the size of the bootstrap methods table}.  Calling this method
-     * does not necessarily inflate the entire table.
+     * {@return the size of the bootstrap methods table}
      */
     int bootstrapMethodsSize();
 
diff --git a/src/java.base/share/classes/java/lang/classfile/attribute/CharacterRangeInfo.java b/src/java.base/share/classes/java/lang/classfile/attribute/CharacterRangeInfo.java
index ab37c372c29..7bb0a0d124d 100644
--- a/src/java.base/share/classes/java/lang/classfile/attribute/CharacterRangeInfo.java
+++ b/src/java.base/share/classes/java/lang/classfile/attribute/CharacterRangeInfo.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2022, 2024, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2022, 2025, 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
@@ -24,64 +24,77 @@
  */
 package java.lang.classfile.attribute;
 
+import java.lang.classfile.CodeBuilder;
 import java.lang.classfile.instruction.CharacterRange;
 
 import jdk.internal.classfile.impl.UnboundAttribute;
 
 /**
- * Models a single character range in the {@link CharacterRangeTableAttribute}.
+ * Models a single character range entry in the {@link
+ * CharacterRangeTableAttribute}.
+ * <p>
+ * Each character range entry associates a range of indices in the code array
+ * with a range of character positions in the source file.  A character position
+ * in the source file is represented by a line number and a column number, and
+ * its value is encoded as {@code lineNumber << 10 + columnNumber}.  Note that
+ * column numbers are not the same as byte indices in a column as multibyte
+ * characters may be present in the source file.
  *
+ * Each character range entry includes a
+ * flag which indicates what kind of range is described: statement, assignment,
+ * method call, etc.
+ *
+ * @see CharacterRangeTableAttribute#characterRangeTable()
+ * @see CharacterRange
  * @since 24
  */
 public sealed interface CharacterRangeInfo
         permits UnboundAttribute.UnboundCharacterRangeInfo {
 
     /**
-     * {@return the start of the character range region (inclusive)}  This is
-     * the index into the code array at which the code for this character range
-     * begins.
+     * {@return the start of indices in the code array, inclusive}
+     *
+     * @see CharacterRange#startScope()
      */
     int startPc();
 
     /**
-     * {@return the end of the character range region (exclusive)}  This is the
-     * index into the code array after which the code for this character range
-     * ends.
+     * {@return the end of indices in the code array, exclusive}
+     *
+     * @see CharacterRange#endScope()
      */
     int endPc();
 
     /**
-     * {@return the encoded start of the character range region (inclusive)}
-     * The value is constructed from the line_number/column_number pair as given
-     * by {@code line_number << 10 + column_number}, where the source file is
-     * viewed as an array of (possibly multi-byte) characters.
+     * {@return the encoded start of character positions in the source file,
+     * inclusive}
      */
     int characterRangeStart();
 
     /**
-     * {@return the encoded end of the character range region (exclusive)}.
-     * The value is constructed from the line_number/column_number pair as given
-     * by {@code line_number << 10 + column_number}, where the source file is
-     * viewed as an array of (possibly multi-byte) characters.
+     * {@return the encoded end of character positions in the source file,
+     * exclusive}
      */
     int characterRangeEnd();
 
     /**
+     * {@return the flags of this character range entry}
+     * <p>
      * The value of the flags item describes the kind of range. Multiple flags
      * may be set within flags.
      * <ul>
      * <li>{@link CharacterRange#FLAG_STATEMENT} Range is a Statement
-     * (except ExpressionStatement), StatementExpression {@jls 14.8}, as well as each
-     * VariableDeclaratorId = VariableInitializer of
-     * LocalVariableDeclarationStatement {@jls 14.4} or FieldDeclaration {@jls 8.3} in the
-     * grammar.
-     * <li>{@link CharacterRange#FLAG_BLOCK} Range is a Block in the
-     * grammar.
+     * (except ExpressionStatement), StatementExpression (JLS {@jls 14.8}), as
+     * well as each {@code VariableDeclaratorId = VariableInitializer} of
+     * LocalVariableDeclarationStatement (JLS {@jls 14.4}) or FieldDeclaration
+     * (JLS {@jls 8.3}) in the grammar.
+     * <li>{@link CharacterRange#FLAG_BLOCK} Range is a Block in the grammar.
      * <li>{@link CharacterRange#FLAG_ASSIGNMENT} Range is an assignment
-     * expression - Expression1 AssignmentOperator Expression1 in the grammar as
-     * well as increment and decrement expressions (both prefix and postfix).
+     * expression - {@code Expression1 AssignmentOperator Expression1} in the
+     * grammar as well as increment and decrement expressions (both prefix and
+     * postfix).
      * <li>{@link CharacterRange#FLAG_FLOW_CONTROLLER} An expression
-     * whose value will effect control flow. {@code Flowcon} in the following:
+     * whose value will affect control flow. {@code Flowcon} in the following:
      * <pre>
      * if ( Flowcon ) Statement [else Statement]
      * for ( ForInitOpt ; [Flowcon] ; ForUpdateOpt ) Statement
@@ -131,22 +144,28 @@ public sealed interface CharacterRangeInfo
      * if&lt;cond&gt;, ifnonull, ifnull or goto.
      * </ul>
      * <p>
-     * All bits of the flags item not assigned above are reserved for future use. They should be set to zero in generated class files and should be ignored by Java virtual machine implementations.
+     * All bits of the flags item not assigned above are reserved for future use.
+     * They should be set to zero in generated class files and should be ignored
+     * by Java virtual machine implementations.
      *
-     * @return the flags
      * @see CharacterRange#flags()
      */
     int flags();
 
     /**
-     * {@return a character range description}
-     * @param startPc the start of the bytecode range, inclusive
-     * @param endPc the end of the bytecode range, exclusive
-     * @param characterRangeStart the start of the character range, inclusive,
-     *                            encoded as {@code line_number << 10 + column_number}
-     * @param characterRangeEnd the end of the character range, exclusive,
-     *                          encoded as {@code line_number << 10 + column_number}
-     * @param flags the range flags
+     * {@return a character range entry}
+     *
+     * @apiNote
+     * The created entry cannot be written to a {@link CodeBuilder}.  Use
+     * {@link CodeBuilder#characterRange CodeBuilder::characterRange} instead.
+     *
+     * @param startPc the start of indices in the code array, inclusive
+     * @param endPc the end of indices in the code array, exclusive
+     * @param characterRangeStart the encoded start of character positions in
+     *        the source file, inclusive
+     * @param characterRangeEnd the encoded end of character positions in the
+     *        source file, exclusive
+     * @param flags the flags of this entry
      */
     static CharacterRangeInfo of(int startPc,
                                  int endPc,
diff --git a/src/java.base/share/classes/java/lang/classfile/attribute/CharacterRangeTableAttribute.java b/src/java.base/share/classes/java/lang/classfile/attribute/CharacterRangeTableAttribute.java
index 42a8443f2f6..49168ed99f8 100644
--- a/src/java.base/share/classes/java/lang/classfile/attribute/CharacterRangeTableAttribute.java
+++ b/src/java.base/share/classes/java/lang/classfile/attribute/CharacterRangeTableAttribute.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2022, 2024, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2022, 2025, 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
@@ -26,37 +26,48 @@
 package java.lang.classfile.attribute;
 
 import java.lang.classfile.Attribute;
+import java.lang.classfile.AttributeMapper;
+import java.lang.classfile.AttributeMapper.AttributeStability;
+import java.lang.classfile.Attributes;
+import java.lang.classfile.ClassFile;
+import java.lang.classfile.CodeBuilder;
+import java.lang.classfile.CodeModel;
+import java.lang.classfile.instruction.CharacterRange;
 import java.util.List;
 
 import jdk.internal.classfile.impl.BoundAttribute;
 import jdk.internal.classfile.impl.UnboundAttribute;
 
 /**
- * The CharacterRangeTable attribute is an optional variable-length attribute in
- * the attributes table of a {@code Code} attribute. It may be used by debuggers
- * to determine which part of the Java virtual machine code array corresponds to
- * a given position in the source file or to determine what section of source
- * code corresponds to a given index into the code array. The
- * CharacterRangeTable attribute consists of an array of character range entries.
- * Each character range entry within the table associates a range of indices in
- * the code array with a range of character indices in the source file. If the
- * source file is viewed as an array of characters, a character index is the
- * corresponding index into this array. Note that character indices are not the
- * same as byte indices as multi-byte characters may be present in the source
- * file. Each character range entry includes a flag which indicates what kind of
- * range is described: statement, assignment, method call, etc. Both code index
- * ranges and character ranges may nest within other ranges, but they may not
- * partially overlap. Thus, a given code index may correspond to several
- * character range entries and in turn several character ranges, but there will
- * be a smallest character range, and for each kind of range in which it is
- * enclosed there will be a smallest character range. Similarly, a given
- * character index may correspond to several character range entries and in turn
- * several code index ranges, but there will be a smallest code index range, and
- * for each kind of range in which it is enclosed there will be a smallest code
- * index range. The character range entries may appear in any order.
+ * Models the {@link Attributes#characterRangeTable() CharacterRangeTable}
+ * attribute, which is a bidirectional mapping from ranges of positions in the
+ * source file to ranges of indices into the {@code code} array.  Its entries
+ * are delivered as {@link CharacterRange}s when traversing the elements of a
+ * {@link CodeModel}, toggled by {@link ClassFile.DebugElementsOption}.
  * <p>
- * The attribute permits multiple instances in a given location.
+ * The {@code CharacterRangeTable} attribute consists of an array of {@linkplain
+ * CharacterRangeInfo character range entries}.  The character range entries
+ * form a forest data structure: any two range entries are either disjoint, or
+ * if they overlap, then one entry must be enclosed within the other, both in
+ * {@code code} array indices and source file character positions.  The
+ * character range entries may appear in any order.
+ * <p>
+ * This attribute only appears on {@code Code} attributes, permits multiple
+ * appearances but should only {@linkplain AttributeMapper#allowMultiple()
+ * appear once} in a {@code Code} attribute.  It has a data dependency on
+ * {@linkplain AttributeStability#LABELS labels}.
+ * <p>
+ * This attribute cannot be sent to a {@link CodeBuilder}; its entries can be
+ * constructed with {@link CharacterRange}, resulting in at most one
+ * attribute instance in the built {@code Code} attribute.
+ * <p>
+ * This attribute is not predefined in the Java SE Platform.  This is a
+ * JDK-specific nonstandard attribute produced by the reference implementation
+ * of the system Java compiler, defined by the {@code jdk.compiler} module.
  *
+ * @see Attributes#characterRangeTable()
+ * @see CompilationIDAttribute
+ * @see SourceIDAttribute
  * @since 24
  */
 public sealed interface CharacterRangeTableAttribute
@@ -71,6 +82,11 @@ public sealed interface CharacterRangeTableAttribute
 
     /**
      * {@return a {@code CharacterRangeTable} attribute}
+     *
+     * @apiNote
+     * The created attribute cannot be written to a {@link CodeBuilder}.  Use
+     * {@link CodeBuilder#characterRange CodeBuilder::characterRange} instead.
+     *
      * @param ranges the descriptions of the character ranges
      */
     static CharacterRangeTableAttribute of(List<CharacterRangeInfo> ranges) {
diff --git a/src/java.base/share/classes/java/lang/classfile/attribute/CodeAttribute.java b/src/java.base/share/classes/java/lang/classfile/attribute/CodeAttribute.java
index 9bc9e975d12..4a06fe2d610 100644
--- a/src/java.base/share/classes/java/lang/classfile/attribute/CodeAttribute.java
+++ b/src/java.base/share/classes/java/lang/classfile/attribute/CodeAttribute.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2022, 2024, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2022, 2025, 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
@@ -25,22 +25,31 @@
 
 package java.lang.classfile.attribute;
 
-import java.lang.classfile.Attribute;
-import java.lang.classfile.CodeModel;
-import java.lang.classfile.Label;
+import java.lang.classfile.*;
+import java.lang.classfile.AttributeMapper.AttributeStability;
 
 import jdk.internal.classfile.impl.BoundAttribute;
 
 /**
- * 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}.
+ * Models the {@link Attributes#code() Code} attribute (JVMS {@jvms 4.7.3}),
+ * which contains the bytecode of this method.
  * <p>
- * The attribute does not permit multiple instances in a given location.
- * Subsequent occurrence of the attribute takes precedence during the attributed
- * element build or transformation.
+ * This attribute only appears on methods, and does not permit {@linkplain
+ * AttributeMapper#allowMultiple multiple instances} in a method.  It has a
+ * data dependency on the {@linkplain AttributeStability#CP_REFS constant pool}.
+ * <p>
+ * This attribute was introduced in the Java Platform version 1.0.2, major
+ * version {@value ClassFile#JAVA_1_VERSION}.
+ *
+ * @apiNote
+ * {@code CodeAttribute} models properties of a {@code Code} attribute read
+ * from {@code class} files.  General {@code class} file transformation should
+ * process and traverse a {@link CodeModel} in the traversal of a {@link
+ * MethodModel}, to support transformation of {@code Code} attributes currently
+ * being built.
  *
+ * @see Attributes#code()
+ * @jvms 4.7.3 The {@code Code} Attribute
  * @since 24
  */
 public sealed interface CodeAttribute extends Attribute<CodeAttribute>, CodeModel
@@ -68,6 +77,9 @@ public sealed interface CodeAttribute extends Attribute<CodeAttribute>, CodeMode
 
     /**
      * {@return the position of the {@code label} in the {@link #codeArray codeArray}}
+     * The label represents a cursor pointing at immediately before the returned
+     * index into the {@code code} array.
+     *
      * @param label a marker for a position within this {@code CodeAttribute}
      * @throws IllegalArgumentException if the {@code label} is not from this attribute
      */
diff --git a/src/java.base/share/classes/java/lang/classfile/attribute/CompilationIDAttribute.java b/src/java.base/share/classes/java/lang/classfile/attribute/CompilationIDAttribute.java
index 8311a8e045c..f3cbce227c3 100644
--- a/src/java.base/share/classes/java/lang/classfile/attribute/CompilationIDAttribute.java
+++ b/src/java.base/share/classes/java/lang/classfile/attribute/CompilationIDAttribute.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2022, 2024, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2022, 2025, 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
@@ -26,6 +26,9 @@
 package java.lang.classfile.attribute;
 
 import java.lang.classfile.Attribute;
+import java.lang.classfile.AttributeMapper;
+import java.lang.classfile.AttributeMapper.AttributeStability;
+import java.lang.classfile.Attributes;
 import java.lang.classfile.ClassElement;
 import java.lang.classfile.constantpool.Utf8Entry;
 
@@ -34,15 +37,20 @@
 import jdk.internal.classfile.impl.UnboundAttribute;
 
 /**
- * Models the {@code CompilationID} attribute (@@@ need reference), which can
- * appear on classes and records the compilation time of the class.  Delivered
- * as a {@link java.lang.classfile.ClassElement} when traversing the elements of
- * a {@link java.lang.classfile.ClassModel}.
+ * Models the {@link Attributes#compilationId() CompilationID} attribute, which
+ * records the compilation time of the {@code class} file.
  * <p>
- * The attribute does not permit multiple instances in a given location.
- * Subsequent occurrence of the attribute takes precedence during the attributed
- * element build or transformation.
+ * This attribute only appears on classes, and does not permit {@linkplain
+ * AttributeMapper#allowMultiple multiple instances} in a class.  It has a
+ * data dependency on the {@linkplain AttributeStability#CP_REFS constant pool}.
+ * <p>
+ * This attribute is not predefined in the Java SE Platform.  This is a
+ * JDK-specific nonstandard attribute produced by the reference implementation
+ * of the system Java compiler, defined by the {@code jdk.compiler} module.
  *
+ * @see Attributes#compilationId()
+ * @see CharacterRangeTableAttribute
+ * @see SourceIDAttribute
  * @since 24
  */
 public sealed interface CompilationIDAttribute
@@ -51,8 +59,8 @@ public sealed interface CompilationIDAttribute
                 UnboundAttribute.UnboundCompilationIDAttribute {
 
     /**
-     * {@return the compilation ID}  The compilation ID is the value of
-     * {@link System#currentTimeMillis()} when the classfile is generated.
+     * {@return the compilation ID}  The compilation ID is the string value of
+     * {@link System#currentTimeMillis()} when the {@code class} file is generated.
      */
     Utf8Entry compilationId();
 
diff --git a/src/java.base/share/classes/java/lang/classfile/attribute/ConstantValueAttribute.java b/src/java.base/share/classes/java/lang/classfile/attribute/ConstantValueAttribute.java
index 54f4742ab0c..7aa6540aa86 100644
--- a/src/java.base/share/classes/java/lang/classfile/attribute/ConstantValueAttribute.java
+++ b/src/java.base/share/classes/java/lang/classfile/attribute/ConstantValueAttribute.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2022, 2024, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2022, 2025, 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
@@ -25,6 +25,10 @@
 package java.lang.classfile.attribute;
 
 import java.lang.classfile.Attribute;
+import java.lang.classfile.AttributeMapper;
+import java.lang.classfile.AttributeMapper.AttributeStability;
+import java.lang.classfile.Attributes;
+import java.lang.classfile.ClassFile;
 import java.lang.classfile.FieldElement;
 import java.lang.classfile.constantpool.ConstantValueEntry;
 import java.lang.constant.ConstantDesc;
@@ -34,15 +38,19 @@
 import jdk.internal.classfile.impl.UnboundAttribute;
 
 /**
- * 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}.
+ * Models the {@link Attributes#constantValue() ConstantValue} attribute (JVMS
+ * {@jvms 4.7.2}), which indicates this field's value is a constant and that
+ * constant value.
  * <p>
- * The attribute does not permit multiple instances in a given location.
- * Subsequent occurrence of the attribute takes precedence during the attributed
- * element build or transformation.
+ * This attribute only appears on fields, and does not permit {@linkplain
+ * AttributeMapper#allowMultiple multiple instances} in a field.  It has a
+ * data dependency on the {@linkplain AttributeStability#CP_REFS constant pool}.
+ * <p>
+ * This attribute was introduced in the Java Platform version 1.0.2, major
+ * version {@value ClassFile#JAVA_1_VERSION}.
  *
+ * @see Attributes#constantValue()
+ * @jvms 4.7.2 The {@code ConstantValue} Attribute
  * @since 24
  */
 public sealed interface ConstantValueAttribute
diff --git a/src/java.base/share/classes/java/lang/classfile/attribute/DeprecatedAttribute.java b/src/java.base/share/classes/java/lang/classfile/attribute/DeprecatedAttribute.java
index 9e470711e1f..89a0394388c 100644
--- a/src/java.base/share/classes/java/lang/classfile/attribute/DeprecatedAttribute.java
+++ b/src/java.base/share/classes/java/lang/classfile/attribute/DeprecatedAttribute.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2022, 2024, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2022, 2025, 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
@@ -24,22 +24,34 @@
  */
 package java.lang.classfile.attribute;
 
-import java.lang.classfile.Attribute;
-import java.lang.classfile.ClassElement;
-import java.lang.classfile.FieldElement;
-import java.lang.classfile.MethodElement;
+import java.lang.classfile.*;
+import java.lang.classfile.AttributeMapper.AttributeStability;
 
 import jdk.internal.classfile.impl.BoundAttribute;
 import jdk.internal.classfile.impl.UnboundAttribute;
 
 /**
- * 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.
+ * Models the {@link Attributes#deprecated() Deprecated} attribute (JVMS {@jvms
+ * 4.7.15}), which indicates this structure has been superseded.
  * <p>
- * The attribute permits multiple instances in a given location.
+ * This attribute can appear on classes, methods, and fields, and permits
+ * {@linkplain AttributeMapper#allowMultiple multiple instances} in a structure.
+ * It has {@linkplain AttributeStability#STATELESS no data dependency}.
+ * <p>
+ * This attribute was introduced in the Java SE Platform version 1.1, major
+ * version {@value ClassFile#JAVA_1_VERSION}.
+ *
+ * @apiNote
+ * When this attribute is present, the {@link Deprecated} annotation should
+ * also be present in the {@link RuntimeVisibleAnnotationsAttribute
+ * RuntimeVisibleAnnotations} attribute to provide more obvious alerts.
+ * The reference implementation of the system Java compiler emits this attribute
+ * without the annotation when a {@code @deprecated} tag is present in the
+ * documentation comments without the annotation.
  *
+ * @see Attributes#deprecated()
+ * @see Deprecated
+ * @jvms 4.7.15 The {@code Deprecated} Attribute
  * @since 24
  */
 public sealed interface DeprecatedAttribute
diff --git a/src/java.base/share/classes/java/lang/classfile/attribute/EnclosingMethodAttribute.java b/src/java.base/share/classes/java/lang/classfile/attribute/EnclosingMethodAttribute.java
index 06ded8c82a5..c89bed9fde9 100644
--- a/src/java.base/share/classes/java/lang/classfile/attribute/EnclosingMethodAttribute.java
+++ b/src/java.base/share/classes/java/lang/classfile/attribute/EnclosingMethodAttribute.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2022, 2024, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2022, 2025, 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
@@ -25,11 +25,16 @@
 package java.lang.classfile.attribute;
 
 import java.lang.classfile.Attribute;
+import java.lang.classfile.AttributeMapper;
+import java.lang.classfile.AttributeMapper.AttributeStability;
+import java.lang.classfile.Attributes;
 import java.lang.classfile.ClassElement;
+import java.lang.classfile.ClassFile;
 import java.lang.classfile.constantpool.ClassEntry;
 import java.lang.classfile.constantpool.NameAndTypeEntry;
 import java.lang.classfile.constantpool.Utf8Entry;
 import java.lang.constant.ClassDesc;
+import java.lang.constant.ConstantDescs;
 import java.lang.constant.MethodTypeDesc;
 import java.util.Optional;
 
@@ -39,17 +44,20 @@
 import jdk.internal.classfile.impl.Util;
 
 /**
- * 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}.
+ * Models the {@link Attributes#enclosingMethod() EnclosingMethod} attribute
+ * (JVMS {@jvms 4.7.7}), which indicates that this class is a local or
+ * anonymous class, and indicates the enclosing method or constructor of this
+ * class if this class is enclosed in exactly one method or constructor.
  * <p>
- * The attribute does not permit multiple instances in a given location.
- * Subsequent occurrence of the attribute takes precedence during the attributed
- * element build or transformation.
+ * This attribute only appears on classes, and does not permit {@linkplain
+ * AttributeMapper#allowMultiple multiple instances} in a class.  It has a
+ * data dependency on the {@linkplain AttributeStability#CP_REFS constant pool}.
  * <p>
- * The attribute was introduced in the Java SE Platform version 5.0.
+ * The attribute was introduced in the Java SE Platform version 5.0, major
+ * version {@value ClassFile#JAVA_5_VERSION}.
  *
+ * @see Attributes#enclosingMethod()
+ * @jvms 4.7.7 The {@code EnclosingMethod} Attribute
  * @since 24
  */
 public sealed interface EnclosingMethodAttribute
@@ -58,36 +66,52 @@ public sealed interface EnclosingMethodAttribute
                 UnboundAttribute.UnboundEnclosingMethodAttribute {
 
     /**
-     * {@return the innermost class that encloses the declaration of the current
-     * class}
+     * {@return the class that encloses the declaration of the current
+     * class}  If the {@link #enclosingMethod()} is present, this is the
+     * declaring class of that enclosing method or constructor.
+     *
+     * @see Class#getEnclosingClass()
      */
     ClassEntry enclosingClass();
 
     /**
      * {@return the name and type of the enclosing method, if the class is
-     * immediately enclosed by a method or constructor}
+     * immediately enclosed by exactly one method or constructor}  This may
+     * be empty if the anonymous or local class appears in a field initializer
+     * (JLS {@jls 8.3.2}), an instance initializer (JLS {@jls 8.6}), or a static
+     * initializer (JLS {@jls 8.7}).  As a result, this never describes a class
+     * initialization method {@value ConstantDescs#CLASS_INIT_NAME}.
+     *
+     * @see Class#getEnclosingMethod()
+     * @see Class#getEnclosingConstructor()
      */
     Optional<NameAndTypeEntry> enclosingMethod();
 
     /**
-     * {@return the name of the enclosing method, if the class is
-     * immediately enclosed by a method or constructor}
+     * {@return the name of the enclosing method, if the class is immediately
+     * enclosed by exactly one method or constructor}
+     *
+     * @see #enclosingMethod()
      */
     default Optional<Utf8Entry> enclosingMethodName() {
         return enclosingMethod().map(NameAndTypeEntry::name);
     }
 
     /**
-     * {@return the type of the enclosing method, if the class is
-     * immediately enclosed by a method or constructor}
+     * {@return the name of the enclosing method, if the class is immediately
+     * enclosed by exactly one method or constructor}
+     *
+     * @see #enclosingMethod()
      */
     default Optional<Utf8Entry> enclosingMethodType() {
         return enclosingMethod().map(NameAndTypeEntry::type);
     }
 
     /**
-     * {@return the type of the enclosing method, if the class is
-     * immediately enclosed by a method or constructor}
+     * {@return the name of the enclosing method, if the class is immediately
+     * enclosed by exactly one method or constructor}
+     *
+     * @see #enclosingMethod()
      */
     default Optional<MethodTypeDesc> enclosingMethodTypeSymbol() {
         return enclosingMethodType().map(Util::methodTypeSymbol);
@@ -96,8 +120,8 @@ default Optional<MethodTypeDesc> enclosingMethodTypeSymbol() {
     /**
      * {@return an {@code EnclosingMethod} attribute}
      * @param className the class name
-     * @param method the name and type of the enclosing method or {@code empty} if
-     *               the class is not immediately enclosed by a method or constructor
+     * @param method the name and type of the enclosing method or {@code Optional.empty()} if
+     *               the class is not immediately enclosed by exactly one method or constructor
      */
     static EnclosingMethodAttribute of(ClassEntry className,
                                        Optional<NameAndTypeEntry> method) {
@@ -107,10 +131,10 @@ static EnclosingMethodAttribute of(ClassEntry className,
     /**
      * {@return an {@code EnclosingMethod} attribute}
      * @param className the class name
-     * @param methodName the name of the enclosing method or {@code empty} if
-     *                   the class is not immediately enclosed by a method or constructor
-     * @param methodType the type of the enclosing method or {@code empty} if
-     *                   the class is not immediately enclosed by a method or constructor
+     * @param methodName the name of the enclosing method or {@code Optional.empty()} if
+     *                   the class is not immediately enclosed by exactly one method or constructor
+     * @param methodType the type of the enclosing method or {@code Optional.empty()} if
+     *                   the class is not immediately enclosed by exactly one method or constructor
      * @throws IllegalArgumentException if {@code className} represents a primitive type
      */
     static EnclosingMethodAttribute of(ClassDesc className,
diff --git a/src/java.base/share/classes/java/lang/classfile/attribute/ExceptionsAttribute.java b/src/java.base/share/classes/java/lang/classfile/attribute/ExceptionsAttribute.java
index 67732e10e81..acfd8bcca94 100644
--- a/src/java.base/share/classes/java/lang/classfile/attribute/ExceptionsAttribute.java
+++ b/src/java.base/share/classes/java/lang/classfile/attribute/ExceptionsAttribute.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2022, 2024, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2022, 2025, 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
@@ -25,9 +25,14 @@
 package java.lang.classfile.attribute;
 
 import java.lang.classfile.Attribute;
+import java.lang.classfile.AttributeMapper;
+import java.lang.classfile.AttributeMapper.AttributeStability;
+import java.lang.classfile.Attributes;
+import java.lang.classfile.ClassFile;
 import java.lang.classfile.MethodElement;
 import java.lang.classfile.constantpool.ClassEntry;
 import java.lang.constant.ClassDesc;
+import java.lang.reflect.Executable;
 import java.util.Arrays;
 import java.util.List;
 
@@ -36,15 +41,25 @@
 import jdk.internal.classfile.impl.Util;
 
 /**
- * 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}.
+ * Models the {@link Attributes#exceptions() Exceptions} attribute (JVMS {@jvms
+ * 4.7.5}), which records the exceptions declared to be thrown by this
+ * method.
  * <p>
- * The attribute does not permit multiple instances in a given location.
- * Subsequent occurrence of the attribute takes precedence during the attributed
- * element build or transformation.
+ * This attribute only appears on methods, and does not permit {@linkplain
+ * AttributeMapper#allowMultiple multiple instances} in a method.  It has a
+ * data dependency on the {@linkplain AttributeStability#CP_REFS constant pool}.
+ * <p>
+ * The attribute was introduced in the Java Platform version 1.0.2, major
+ * version {@value ClassFile#JAVA_1_VERSION}.
+ *
+ * @apiNote
+ * Generic exceptions types thrown by a method and potentially annotated use of
+ * those types are defined by {@link SignatureAttribute} and {@link
+ * RuntimeVisibleTypeAnnotationsAttribute} respectively, which requires this
+ * attribute to be present.
  *
+ * @see Attributes#exceptions()
+ * @jvms 4.7.5 The {@code Exceptions} Attribute
  * @since 24
  */
 public sealed interface ExceptionsAttribute
@@ -54,12 +69,14 @@ public sealed interface ExceptionsAttribute
 
     /**
      * {@return the exceptions declared to be thrown by this method}
+     *
+     * @see Executable#getExceptionTypes()
      */
     List<ClassEntry> exceptions();
 
     /**
      * {@return an {@code Exceptions} attribute}
-     * @param exceptions the checked exceptions that may be thrown from this method
+     * @param exceptions the exceptions that may be thrown from this method
      */
     static ExceptionsAttribute of(List<ClassEntry> exceptions) {
         return new UnboundAttribute.UnboundExceptionsAttribute(exceptions);
@@ -67,7 +84,7 @@ static ExceptionsAttribute of(List<ClassEntry> exceptions) {
 
     /**
      * {@return an {@code Exceptions} attribute}
-     * @param exceptions the checked exceptions that may be thrown from this method
+     * @param exceptions the exceptions that may be thrown from this method
      */
     static ExceptionsAttribute of(ClassEntry... exceptions) {
         return of(List.of(exceptions));
@@ -75,7 +92,7 @@ static ExceptionsAttribute of(ClassEntry... exceptions) {
 
     /**
      * {@return an {@code Exceptions} attribute}
-     * @param exceptions the checked exceptions that may be thrown from this method
+     * @param exceptions the exceptions that may be thrown from this method
      */
     static ExceptionsAttribute ofSymbols(List<ClassDesc> exceptions) {
         return of(Util.entryList(exceptions));
@@ -83,7 +100,7 @@ static ExceptionsAttribute ofSymbols(List<ClassDesc> exceptions) {
 
     /**
      * {@return an {@code Exceptions} attribute}
-     * @param exceptions the checked exceptions that may be thrown from this method
+     * @param exceptions the exceptions that may be thrown from this method
      */
     static ExceptionsAttribute ofSymbols(ClassDesc... exceptions) {
         return ofSymbols(Arrays.asList(exceptions));
diff --git a/src/java.base/share/classes/java/lang/classfile/attribute/InnerClassInfo.java b/src/java.base/share/classes/java/lang/classfile/attribute/InnerClassInfo.java
index 6965d5fdfd2..1394ee592ed 100644
--- a/src/java.base/share/classes/java/lang/classfile/attribute/InnerClassInfo.java
+++ b/src/java.base/share/classes/java/lang/classfile/attribute/InnerClassInfo.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2022, 2024, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2022, 2025, 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
@@ -36,38 +36,52 @@
 import jdk.internal.classfile.impl.Util;
 
 /**
- * Models a single inner class in the {@link InnerClassesAttribute}.
+ * Models a single entry in the {@link InnerClassesAttribute}.
  *
+ * @see InnerClassesAttribute#classes()
+ * @jvms 4.7.6 The {@code InnerClasses} Attribute
  * @since 24
  */
 public sealed interface InnerClassInfo
         permits UnboundAttribute.UnboundInnerClassInfo {
 
     /**
-     * {@return the class described by this inner class description}
+     * {@return the nested class described by this entry}
      */
     ClassEntry innerClass();
 
     /**
-     * {@return the class or interface of which this class is a member, if it is a
-     * member of a class or interface}
+     * {@return the class or interface of which this class is a member, if it is
+     * a member of a class or interface}  This may be empty if this class is
+     * local or anonymous.
+     *
+     * @see Class#getDeclaringClass()
      */
     Optional<ClassEntry> outerClass();
 
     /**
      * {@return the simple name of this class, or empty if this class is anonymous}
+     *
+     * @see Class#getSimpleName()
      */
     Optional<Utf8Entry> innerName();
 
     /**
      * {@return a bit mask of flags denoting access permissions and properties
      * of the inner class}
+     *
+     * @see Class#getModifiers()
+     * @see AccessFlag.Location#INNER_CLASS
      */
     int flagsMask();
 
     /**
      * {@return a set of flag enums denoting access permissions and properties
-     * of the inner class}
+     * of the nested class}
+     *
+     * @throws IllegalArgumentException if the flags mask has any undefined bit set
+     * @see Class#accessFlags()
+     * @see AccessFlag.Location#INNER_CLASS
      */
     default Set<AccessFlag> flags() {
         return AccessFlag.maskToAccessFlags(flagsMask(), AccessFlag.Location.INNER_CLASS);
@@ -75,17 +89,19 @@ default Set<AccessFlag> flags() {
 
     /**
      * {@return whether a specific access flag is set}
+     *
      * @param flag the access flag
+     * @see AccessFlag.Location#INNER_CLASS
      */
     default boolean has(AccessFlag flag) {
         return Util.has(AccessFlag.Location.INNER_CLASS, flagsMask(), flag);
     }
 
     /**
-     * {@return an inner class description}
-     * @param innerClass the inner class being described
-     * @param outerClass the class containing the inner class, if any
-     * @param innerName the name of the inner class, if it is not anonymous
+     * {@return a nested class description}
+     * @param innerClass the nested class being described
+     * @param outerClass the class that has the nested class as a member, if it exists
+     * @param innerName the simple name of the nested class, if it is not anonymous
      * @param flags the inner class access flags
      */
     static InnerClassInfo of(ClassEntry innerClass, Optional<ClassEntry> outerClass,
@@ -94,10 +110,10 @@ static InnerClassInfo of(ClassEntry innerClass, Optional<ClassEntry> outerClass,
     }
 
     /**
-     * {@return an inner class description}
-     * @param innerClass the inner class being described
-     * @param outerClass the class containing the inner class, if any
-     * @param innerName the name of the inner class, if it is not anonymous
+     * {@return a nested class description}
+     * @param innerClass the nested class being described
+     * @param outerClass the class that has the nested class as a member, if it exists
+     * @param innerName the simple name of the nested class, if it is not anonymous
      * @param flags the inner class access flags
      * @throws IllegalArgumentException if {@code innerClass} or {@code outerClass} represents a primitive type
      */
@@ -109,12 +125,14 @@ static InnerClassInfo of(ClassDesc innerClass, Optional<ClassDesc> outerClass, O
     }
 
     /**
-     * {@return an inner class description}
-     * @param innerClass the inner class being described
-     * @param outerClass the class containing the inner class, if any
-     * @param innerName the name of the inner class, if it is not anonymous
+     * {@return a nested class description}
+     * @param innerClass the nested class being described
+     * @param outerClass the class that has the nested class as a member, if it exists
+     * @param innerName the name of the nested class, if it is not anonymous
      * @param flags the inner class access flags
-     * @throws IllegalArgumentException if {@code innerClass} or {@code outerClass} represents a primitive type
+     * @throws IllegalArgumentException if {@code innerClass} or {@code outerClass}
+     *         represents a primitive type, or if any flag cannot be applied to
+     *         the {@link AccessFlag.Location#INNER_CLASS} location
      */
     static InnerClassInfo of(ClassDesc innerClass, Optional<ClassDesc> outerClass, Optional<String> innerName, AccessFlag... flags) {
         return of(innerClass, outerClass, innerName, Util.flagsToBits(AccessFlag.Location.INNER_CLASS, flags));
diff --git a/src/java.base/share/classes/java/lang/classfile/attribute/InnerClassesAttribute.java b/src/java.base/share/classes/java/lang/classfile/attribute/InnerClassesAttribute.java
index 463a29f9398..b50b38d0a00 100644
--- a/src/java.base/share/classes/java/lang/classfile/attribute/InnerClassesAttribute.java
+++ b/src/java.base/share/classes/java/lang/classfile/attribute/InnerClassesAttribute.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2022, 2024, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2022, 2025, 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
@@ -26,22 +26,30 @@
 package java.lang.classfile.attribute;
 
 import java.lang.classfile.Attribute;
+import java.lang.classfile.AttributeMapper;
+import java.lang.classfile.AttributeMapper.AttributeStability;
+import java.lang.classfile.Attributes;
 import java.lang.classfile.ClassElement;
+import java.lang.classfile.ClassFile;
 import java.util.List;
 
 import jdk.internal.classfile.impl.BoundAttribute;
 import jdk.internal.classfile.impl.UnboundAttribute;
 
 /**
- * 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}.
+ * Models the {@link Attributes#innerClasses() InnerClasses} attribute (JVMS
+ * {@jvms 4.7.6}), which records which classes referenced by this {@code class}
+ * file are nested classes.
  * <p>
- * The attribute does not permit multiple instances in a given location.
- * Subsequent occurrence of the attribute takes precedence during the attributed
- * element build or transformation.
+ * This attribute only appears on classes, and does not permit {@linkplain
+ * AttributeMapper#allowMultiple multiple instances} in a class.  It has a
+ * data dependency on the {@linkplain AttributeStability#CP_REFS constant pool}.
+ * <p>
+ * The attribute was introduced in the Java SE Platform version 1.1, major
+ * version {@value ClassFile#JAVA_1_VERSION}.
  *
+ * @see Attributes#innerClasses()
+ * @jvms 4.7.6 The {@code InnerClasses} Attribute
  * @since 24
  */
 public sealed interface InnerClassesAttribute
@@ -50,13 +58,13 @@ public sealed interface InnerClassesAttribute
                 UnboundAttribute.UnboundInnerClassesAttribute {
 
     /**
-     * {@return the inner classes used by this class}
+     * {@return the nested classes used by this {@code class} file}
      */
     List<InnerClassInfo> classes();
 
     /**
      * {@return an {@code InnerClasses} attribute}
-     * @param innerClasses descriptions of the inner classes
+     * @param innerClasses descriptions of the nested classes
      */
     static InnerClassesAttribute of(List<InnerClassInfo> innerClasses) {
         return new UnboundAttribute.UnboundInnerClassesAttribute(innerClasses);
@@ -64,7 +72,7 @@ static InnerClassesAttribute of(List<InnerClassInfo> innerClasses) {
 
     /**
      * {@return an {@code InnerClasses} attribute}
-     * @param innerClasses descriptions of the inner classes
+     * @param innerClasses descriptions of the nested classes
      */
     static InnerClassesAttribute of(InnerClassInfo... innerClasses) {
         return new UnboundAttribute.UnboundInnerClassesAttribute(List.of(innerClasses));
diff --git a/src/java.base/share/classes/java/lang/classfile/attribute/LineNumberInfo.java b/src/java.base/share/classes/java/lang/classfile/attribute/LineNumberInfo.java
index 7e148cec9c1..2f4f6d00deb 100644
--- a/src/java.base/share/classes/java/lang/classfile/attribute/LineNumberInfo.java
+++ b/src/java.base/share/classes/java/lang/classfile/attribute/LineNumberInfo.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2022, 2024, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2022, 2025, 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
@@ -24,11 +24,16 @@
  */
 package java.lang.classfile.attribute;
 
+import java.lang.classfile.CodeBuilder;
+import java.lang.classfile.instruction.LineNumber;
+
 import jdk.internal.classfile.impl.UnboundAttribute;
 
 /**
- * Models a single line number in the {@link LineNumberTableAttribute}.
+ * Models a single line number entry in the {@link LineNumberTableAttribute}.
  *
+ * @see LineNumberTableAttribute#lineNumbers()
+ * @see LineNumber
  * @since 24
  */
 public sealed interface LineNumberInfo
@@ -47,6 +52,12 @@ public sealed interface LineNumberInfo
 
     /**
      * {@return a line number description}
+     *
+     * @apiNote
+     * The created entry cannot be written to a {@link CodeBuilder}.  Call
+     * {@link CodeBuilder#lineNumber CodeBuilder::lineNumber} in the correct
+     * order instead.
+     *
      * @param startPc the starting index of the code array for this line
      * @param lineNumber the line number within the original source file
      */
diff --git a/src/java.base/share/classes/java/lang/classfile/attribute/LineNumberTableAttribute.java b/src/java.base/share/classes/java/lang/classfile/attribute/LineNumberTableAttribute.java
index 1c00745218a..bb08beacaa2 100644
--- a/src/java.base/share/classes/java/lang/classfile/attribute/LineNumberTableAttribute.java
+++ b/src/java.base/share/classes/java/lang/classfile/attribute/LineNumberTableAttribute.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2022, 2024, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2022, 2025, 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
@@ -25,21 +25,39 @@
 package java.lang.classfile.attribute;
 
 import java.lang.classfile.Attribute;
+import java.lang.classfile.AttributeMapper;
+import java.lang.classfile.AttributeMapper.AttributeStability;
+import java.lang.classfile.Attributes;
+import java.lang.classfile.ClassFile;
+import java.lang.classfile.CodeBuilder;
+import java.lang.classfile.CodeModel;
+import java.lang.classfile.instruction.LineNumber;
 import java.util.List;
 
 import jdk.internal.classfile.impl.BoundAttribute;
 import jdk.internal.classfile.impl.UnboundAttribute;
 
 /**
- * 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
- * elements of a {@link java.lang.classfile.CodeModel}, according to the setting of the
- * {@link java.lang.classfile.ClassFile.LineNumbersOption} option.
+ * Models the {@link Attributes#lineNumberTable() LineNumberTable} attribute
+ * (JVMS {@jvms 4.7.12}), which records the mapping between indexes into
+ * the {@code code} array and line numbers in the source file.  Its entries are
+ * delivered as {@link LineNumber} when traversing the elements of a {@link
+ * CodeModel}, which is toggled by {@link ClassFile.LineNumbersOption}.
  * <p>
- * The attribute permits multiple instances in a given location.
+ * This attribute only appears on {@code Code} attributes, and permits {@linkplain
+ * AttributeMapper#allowMultiple() multiple instances} in a {@code Code}
+ * attribute.  It has a data dependency on {@linkplain AttributeStability#LABELS
+ * labels}.
+ * <p>
+ * This attribute cannot be sent to a {@link CodeBuilder}; its entries can be
+ * constructed with {@link LineNumber}, resulting in at most one attribute
+ * instance in the built {@code Code} attribute.
+ * <p>
+ * The attribute was introduced in the Java Platform version 1.0.2, major
+ * version {@value ClassFile#JAVA_1_VERSION}.
  *
+ * @see Attributes#lineNumberTable()
+ * @jvms 4.7.12 The {@code LineNumberTable} Attribute
  * @since 24
  */
 public sealed interface LineNumberTableAttribute
@@ -54,6 +72,12 @@ public sealed interface LineNumberTableAttribute
 
     /**
      * {@return a {@code LineNumberTable} attribute}
+     *
+     * @apiNote
+     * The created attribute cannot be written to a {@link CodeBuilder}.  Call
+     * {@link CodeBuilder#lineNumber CodeBuilder::lineNumber} in the correct
+     * order instead.
+     *
      * @param lines the line number descriptions
      */
     static LineNumberTableAttribute of(List<LineNumberInfo> lines) {
diff --git a/src/java.base/share/classes/java/lang/classfile/attribute/LocalVariableInfo.java b/src/java.base/share/classes/java/lang/classfile/attribute/LocalVariableInfo.java
index 2b4030b46a6..b6b1c03f133 100644
--- a/src/java.base/share/classes/java/lang/classfile/attribute/LocalVariableInfo.java
+++ b/src/java.base/share/classes/java/lang/classfile/attribute/LocalVariableInfo.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2022, 2024, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2022, 2025, 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
@@ -25,6 +25,7 @@
 package java.lang.classfile.attribute;
 
 import java.lang.classfile.constantpool.Utf8Entry;
+import java.lang.classfile.instruction.LocalVariable;
 import java.lang.constant.ClassDesc;
 
 import jdk.internal.classfile.impl.BoundLocalVariable;
@@ -34,20 +35,23 @@
 /**
  * Models a single local variable in the {@link LocalVariableTableAttribute}.
  *
+ * @see LocalVariableTableAttribute#localVariables()
+ * @see LocalVariable
+ * @jvms 4.7.13 The {@code LocalVaribleTable} Attribute
  * @since 24
  */
 public sealed interface LocalVariableInfo
         permits UnboundAttribute.UnboundLocalVariableInfo, BoundLocalVariable {
 
     /**
-     * {@return the index into the code array (inclusive) at which the scope of
+     * {@return the index into the code array, inclusive, at which the scope of
      * this variable begins}
      */
     int startPc();
 
     /**
      * {@return the length of the region of the code array in which this
-     * variable is in scope.}
+     * variable is in scope}
      */
     int length();
 
@@ -57,7 +61,7 @@ public sealed interface LocalVariableInfo
     Utf8Entry name();
 
     /**
-     * {@return the field descriptor of the local variable}
+     * {@return the field descriptor string of the local variable}
      */
     Utf8Entry type();
 
diff --git a/src/java.base/share/classes/java/lang/classfile/attribute/LocalVariableTableAttribute.java b/src/java.base/share/classes/java/lang/classfile/attribute/LocalVariableTableAttribute.java
index 8f44ab2905f..6c1795e17bf 100644
--- a/src/java.base/share/classes/java/lang/classfile/attribute/LocalVariableTableAttribute.java
+++ b/src/java.base/share/classes/java/lang/classfile/attribute/LocalVariableTableAttribute.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2022, 2024, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2022, 2025, 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
@@ -25,21 +25,45 @@
 package java.lang.classfile.attribute;
 
 import java.lang.classfile.Attribute;
+import java.lang.classfile.AttributeMapper;
+import java.lang.classfile.AttributeMapper.AttributeStability;
+import java.lang.classfile.Attributes;
+import java.lang.classfile.ClassFile;
+import java.lang.classfile.CodeBuilder;
+import java.lang.classfile.CodeModel;
+import java.lang.classfile.instruction.LocalVariable;
 import java.util.List;
 
 import jdk.internal.classfile.impl.BoundAttribute;
 import jdk.internal.classfile.impl.UnboundAttribute;
 
 /**
- * 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
- * elements of a {@link java.lang.classfile.CodeModel}, according to the setting of the
- * {@link java.lang.classfile.ClassFile.DebugElementsOption} option.
+ * Models the {@link Attributes#localVariableTable() LocalVariableTable}
+ * attribute (JVMS {@jvms 4.7.13}), which records debug information about local
+ * variables.  Its entries are delivered as {@link LocalVariable}s when
+ * traversing the elements of a {@link CodeModel}, which is toggled by {@link
+ * ClassFile.DebugElementsOption}.
  * <p>
- * The attribute permits multiple instances in a given location.
+ * This attribute only appears on {@code Code} attributes, and permits {@linkplain
+ * AttributeMapper#allowMultiple() multiple instances} in a {@code Code}
+ * attribute.  It has a data dependency on {@linkplain AttributeStability#LABELS
+ * labels}.
+ * <p>
+ * This attribute cannot be sent to a {@link CodeBuilder}; its entries can be
+ * constructed with {@link LocalVariable}, resulting in at most one attribute
+ * instance in the built {@code Code} attribute.
+ * <p>
+ * The attribute was introduced in the Java Platform version 1.0.2, major
+ * version {@value ClassFile#JAVA_1_VERSION}.
+ *
+ * @apiNote
+ * Generic local variable types and potentially annotated use of those types are
+ * defined by {@link LocalVariableTypeTableAttribute} and {@link
+ * RuntimeVisibleTypeAnnotationsAttribute} respectively, which requires this
+ * attribute to be present.
  *
+ * @see Attributes#localVariableTable()
+ * @jvms 4.7.13 The {@code LocalVaribleTable} Attribute
  * @since 24
  */
 public sealed interface LocalVariableTableAttribute
@@ -53,6 +77,11 @@ public sealed interface LocalVariableTableAttribute
 
     /**
      * {@return a {@code LocalVariableTable} attribute}
+     *
+     * @apiNote
+     * The created attribute cannot be written to a {@link CodeBuilder}.  Use
+     * {@link CodeBuilder#localVariable CodeBuilder::localVariable} instead.
+     *
      * @param locals the local variable descriptions
      */
     static LocalVariableTableAttribute of(List<LocalVariableInfo> locals) {
diff --git a/src/java.base/share/classes/java/lang/classfile/attribute/LocalVariableTypeInfo.java b/src/java.base/share/classes/java/lang/classfile/attribute/LocalVariableTypeInfo.java
index e7a137102ae..a45dd76d520 100644
--- a/src/java.base/share/classes/java/lang/classfile/attribute/LocalVariableTypeInfo.java
+++ b/src/java.base/share/classes/java/lang/classfile/attribute/LocalVariableTypeInfo.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2022, 2024, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2022, 2025, 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
@@ -25,6 +25,7 @@
 package java.lang.classfile.attribute;
 
 import java.lang.classfile.constantpool.Utf8Entry;
+import java.lang.classfile.instruction.LocalVariableType;
 
 import jdk.internal.classfile.impl.BoundLocalVariableType;
 import jdk.internal.classfile.impl.UnboundAttribute;
@@ -32,20 +33,23 @@
 /**
  * Models a single local variable in the {@link LocalVariableTypeTableAttribute}.
  *
+ * @see LocalVariableTypeTableAttribute#localVariableTypes()
+ * @see LocalVariableType
+ * @jvms 4.7.14 The {@code LocalVariableTypeTable} Attribute
  * @since 24
  */
 public sealed interface LocalVariableTypeInfo
         permits UnboundAttribute.UnboundLocalVariableTypeInfo, BoundLocalVariableType {
 
     /**
-     * {@return the index into the code array (inclusive) at which the scope of
+     * {@return the index into the code array, inclusive at which the scope of
      * this variable begins}
      */
     int startPc();
 
     /**
      * {@return the length of the region of the code array in which this
-     * variable is in scope.}
+     * variable is in scope}
      */
     int length();
 
@@ -56,7 +60,7 @@ public sealed interface LocalVariableTypeInfo
 
 
     /**
-     * {@return the field signature of the local variable}
+     * {@return the field signature string of the local variable}
      */
     Utf8Entry signature();
 
diff --git a/src/java.base/share/classes/java/lang/classfile/attribute/LocalVariableTypeTableAttribute.java b/src/java.base/share/classes/java/lang/classfile/attribute/LocalVariableTypeTableAttribute.java
index 2bf7b7a87b3..b4bc80cdca1 100644
--- a/src/java.base/share/classes/java/lang/classfile/attribute/LocalVariableTypeTableAttribute.java
+++ b/src/java.base/share/classes/java/lang/classfile/attribute/LocalVariableTypeTableAttribute.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2022, 2024, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2022, 2025, 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
@@ -26,23 +26,45 @@
 package java.lang.classfile.attribute;
 
 import java.lang.classfile.Attribute;
+import java.lang.classfile.AttributeMapper;
+import java.lang.classfile.AttributeMapper.AttributeStability;
+import java.lang.classfile.Attributes;
+import java.lang.classfile.ClassFile;
+import java.lang.classfile.CodeBuilder;
+import java.lang.classfile.CodeModel;
+import java.lang.classfile.instruction.LocalVariableType;
 import java.util.List;
 
 import jdk.internal.classfile.impl.BoundAttribute;
 import jdk.internal.classfile.impl.UnboundAttribute;
 
 /**
- * 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
- * elements of a {@link java.lang.classfile.CodeModel}, according to the setting of the
- * {@link java.lang.classfile.ClassFile.LineNumbersOption} option.
+ * Models the {@link Attributes#localVariableTypeTable() LocalVariableTypeTable}
+ * attribute (JVMS {@jvms 4.7.14}), which records debug information about local
+ * variables with generic types.  Its entries are delivered as {@link
+ * LocalVariableType}s when traversing the elements of a {@link CodeModel},
+ * which can be toggled by {@link ClassFile.DebugElementsOption}.
  * <p>
- * The attribute permits multiple instances in a given location.
+ * This attribute only appears on {@code Code} attributes, and permits {@linkplain
+ * AttributeMapper#allowMultiple() multiple instances} in a {@code Code}
+ * attribute.  It has a data dependency on {@linkplain AttributeStability#LABELS
+ * labels}.
  * <p>
- * The attribute was introduced in the Java SE Platform version 5.0.
+ * This attribute cannot be sent to a {@link CodeBuilder}; its entries can be
+ * constructed with {@link LocalVariableType}, resulting in at most one attribute
+ * instance in the built {@code Code} attribute.
+ * <p>
+ * The attribute was introduced in the Java SE Platform version 5.0, major
+ * version {@value ClassFile#JAVA_5_VERSION}.
+ *
+ * @apiNote
+ * Only local variables that have generic field types need to be described by
+ * this attribute.  If a local variable is described in a {@code
+ * LocalVariableTypeTable} attribute, it must also be described in a {@link
+ * LocalVariableTableAttribute LocalVariableTable} attribute.
  *
+ * @see Attributes#localVariableTypeTable()
+ * @jvms 4.7.14 The {@code LocalVariableTypeTable} Attribute
  * @since 24
  */
 public sealed interface LocalVariableTypeTableAttribute
@@ -50,7 +72,7 @@ public sealed interface LocalVariableTypeTableAttribute
         permits BoundAttribute.BoundLocalVariableTypeTableAttribute, UnboundAttribute.UnboundLocalVariableTypeTableAttribute {
 
     /**
-     * {@return debug information for the local variables in this method}
+     * {@return debug information for the local variables with generic types in this method}
      */
     List<LocalVariableTypeInfo> localVariableTypes();
 
diff --git a/src/java.base/share/classes/java/lang/classfile/attribute/MethodParameterInfo.java b/src/java.base/share/classes/java/lang/classfile/attribute/MethodParameterInfo.java
index 35301a30284..0366ec07e25 100644
--- a/src/java.base/share/classes/java/lang/classfile/attribute/MethodParameterInfo.java
+++ b/src/java.base/share/classes/java/lang/classfile/attribute/MethodParameterInfo.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2022, 2024, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2022, 2025, 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
@@ -24,9 +24,9 @@
  */
 package java.lang.classfile.attribute;
 
-import java.lang.classfile.ClassFile;
 import java.lang.classfile.constantpool.Utf8Entry;
 import java.lang.reflect.AccessFlag;
+import java.lang.reflect.Parameter;
 import java.util.Optional;
 import java.util.Set;
 
@@ -37,30 +37,35 @@
 /**
  * Models a single method parameter in the {@link MethodParametersAttribute}.
  *
+ * @see MethodParametersAttribute#parameters()
+ * @see Parameter
+ * @jvms 4.7.24 The {@code MethodParameters} Attribute
  * @since 24
  */
 public sealed interface MethodParameterInfo
         permits UnboundAttribute.UnboundMethodParameterInfo {
     /**
-     * The name of the method parameter, if there is one.
+     * {@return the parameter name, if it has one}
      *
-     * @return the parameter name, if it has one
+     * @see Parameter#getName()
+     * @see Parameter#isNamePresent()
      */
     Optional<Utf8Entry> name();
 
     /**
-     * Parameter access flags for this parameter, as a bit mask.  Valid
-     * parameter flags include {@link ClassFile#ACC_FINAL},
-     * {@link ClassFile#ACC_SYNTHETIC}, and {@link ClassFile#ACC_MANDATED}.
+     * {@return the access flags, as a bit mask}
      *
-     * @return the access flags, as a bit mask
+     * @see Parameter#getModifiers()
+     * @see AccessFlag.Location#METHOD_PARAMETER
      */
     int flagsMask();
 
     /**
-     * Parameter access flags for this parameter.
+     * {@return the access flags, as a set of flag enums}
      *
-     * @return the access flags, as a bit mask
+     * @throws IllegalArgumentException if the flags mask has any undefined bit set
+     * @see Parameter#accessFlags()
+     * @see AccessFlag.Location#METHOD_PARAMETER
      */
     default Set<AccessFlag> flags() {
         return AccessFlag.maskToAccessFlags(flagsMask(), AccessFlag.Location.METHOD_PARAMETER);
@@ -69,6 +74,7 @@ default Set<AccessFlag> flags() {
     /**
      * {@return whether the method parameter has a specific flag set}
      * @param flag the method parameter flag
+     * @see AccessFlag.Location#METHOD_PARAMETER
      */
     default boolean has(AccessFlag flag) {
         return Util.has(AccessFlag.Location.METHOD_PARAMETER, flagsMask(), flag);
@@ -76,7 +82,7 @@ default boolean has(AccessFlag flag) {
 
     /**
      * {@return a method parameter description}
-     * @param name the method parameter name
+     * @param name the method parameter name, may be empty
      * @param flags the method parameter access flags
      */
     static MethodParameterInfo of(Optional<Utf8Entry> name, int flags) {
@@ -85,8 +91,10 @@ static MethodParameterInfo of(Optional<Utf8Entry> name, int flags) {
 
     /**
      * {@return a method parameter description}
-     * @param name the method parameter name
+     * @param name the method parameter name, may be empty
      * @param flags the method parameter access flags
+     * @throws IllegalArgumentException if any flag cannot be applied to the
+     *         {@link AccessFlag.Location#METHOD_PARAMETER} location
      */
     static MethodParameterInfo of(Optional<String> name, AccessFlag... flags) {
         return of(name.map(TemporaryConstantPool.INSTANCE::utf8Entry), Util.flagsToBits(AccessFlag.Location.METHOD_PARAMETER, flags));
@@ -94,7 +102,7 @@ static MethodParameterInfo of(Optional<String> name, AccessFlag... flags) {
 
     /**
      * {@return a method parameter description}
-     * @param name the method parameter name
+     * @param name the method parameter name, may be empty
      * @param flags the method parameter access flags
      */
     static MethodParameterInfo ofParameter(Optional<String> name, int flags) {
diff --git a/src/java.base/share/classes/java/lang/classfile/attribute/MethodParametersAttribute.java b/src/java.base/share/classes/java/lang/classfile/attribute/MethodParametersAttribute.java
index 3b3bacbbca5..8cf6d7b6319 100644
--- a/src/java.base/share/classes/java/lang/classfile/attribute/MethodParametersAttribute.java
+++ b/src/java.base/share/classes/java/lang/classfile/attribute/MethodParametersAttribute.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2022, 2024, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2022, 2025, 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
@@ -26,24 +26,32 @@
 package java.lang.classfile.attribute;
 
 import java.lang.classfile.Attribute;
+import java.lang.classfile.AttributeMapper;
+import java.lang.classfile.Attributes;
+import java.lang.classfile.ClassFile;
 import java.lang.classfile.MethodElement;
+import java.lang.reflect.Executable;
 import java.util.List;
 
 import jdk.internal.classfile.impl.BoundAttribute;
 import jdk.internal.classfile.impl.UnboundAttribute;
 
 /**
- * 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}.
+ * Models the {@link Attributes#methodParameters() MethodParameters} attribute
+ * (JVMS {@jvms 4.7.24}), which records reflective information about this
+ * method's parameters such as access modifiers.
  * <p>
- * The attribute does not permit multiple instances in a given location.
- * Subsequent occurrence of the attribute takes precedence during the attributed
- * element build or transformation.
+ * This attribute only appears on methods, and does not permit {@linkplain
+ * AttributeMapper#allowMultiple multiple instances} in a method.  It has a
+ * data dependency on the {@linkplain AttributeMapper.AttributeStability#CP_REFS
+ * constant pool}.
  * <p>
- * The attribute was introduced in the Java SE Platform version 8.
+ * The attribute was introduced in the Java SE Platform version 8, major version
+ * {@value ClassFile#JAVA_8_VERSION}.
  *
+ * @see Attributes#methodParameters()
+ * @see Executable#getParameters()
+ * @jvms 4.7.24 The {@code MethodParameters} Attribute
  * @since 24
  */
 public sealed interface MethodParametersAttribute
@@ -53,7 +61,7 @@ public sealed interface MethodParametersAttribute
 
     /**
      * {@return information about the parameters of the method}  The i'th entry
-     * in the list corresponds to the i'th parameter in the method declaration.
+     * in the list corresponds to the i'th parameter in the method descriptor.
      */
     List<MethodParameterInfo> parameters();
 
diff --git a/src/java.base/share/classes/java/lang/classfile/attribute/ModuleAttribute.java b/src/java.base/share/classes/java/lang/classfile/attribute/ModuleAttribute.java
index 07e0f2baa12..231796c1b81 100644
--- a/src/java.base/share/classes/java/lang/classfile/attribute/ModuleAttribute.java
+++ b/src/java.base/share/classes/java/lang/classfile/attribute/ModuleAttribute.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2022, 2024, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2022, 2025, 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
@@ -25,17 +25,24 @@
 package java.lang.classfile.attribute;
 
 import java.lang.classfile.Attribute;
+import java.lang.classfile.AttributeMapper;
+import java.lang.classfile.Attributes;
 import java.lang.classfile.ClassElement;
+import java.lang.classfile.ClassFile;
+import java.lang.classfile.ClassModel;
 import java.lang.classfile.constantpool.ClassEntry;
 import java.lang.classfile.constantpool.ModuleEntry;
 import java.lang.classfile.constantpool.Utf8Entry;
 import java.lang.constant.ClassDesc;
 import java.lang.constant.ModuleDesc;
 import java.lang.constant.PackageDesc;
+import java.lang.invoke.MethodHandles;
+import java.lang.module.ModuleDescriptor;
 import java.lang.reflect.AccessFlag;
 import java.util.Collection;
 import java.util.List;
 import java.util.Optional;
+import java.util.ServiceLoader;
 import java.util.Set;
 import java.util.function.Consumer;
 
@@ -45,17 +52,21 @@
 import jdk.internal.classfile.impl.Util;
 
 /**
- * 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}.
+ * Models the {@link Attributes#module() Module} attribute (JVMS {@jvms 4.7.25}),
+ * which always appears on classes that {@linkplain ClassModel#isModuleInfo()
+ * represent} module descriptors.
  * <p>
- * The attribute does not permit multiple instances in a given location.
- * Subsequent occurrence of the attribute takes precedence during the attributed
- * element build or transformation.
+ * This attribute only appears on classes, and does not permit {@linkplain
+ * AttributeMapper#allowMultiple multiple instances} in a class.  It has a
+ * data dependency on the {@linkplain AttributeMapper.AttributeStability#CP_REFS
+ * constant pool}.
  * <p>
- * The attribute was introduced in the Java SE Platform version 9.
+ * The attribute was introduced in the Java SE Platform version 9, major version
+ * {@value ClassFile#JAVA_9_VERSION}.
  *
+ * @see Attributes#module()
+ * @see ModuleDescriptor
+ * @jvms 4.7.25 The {@code Module} Attribute
  * @since 24
  */
 public sealed interface ModuleAttribute
@@ -64,25 +75,36 @@ public sealed interface ModuleAttribute
 
     /**
      * {@return the name of the module}
+     *
+     * @see ModuleDescriptor#name()
      */
     ModuleEntry moduleName();
 
     /**
-     * {@return the the module flags of the module, as a bit mask}
+     * {@return the module flags of the module, as a bit mask}
+     *
+     * @see ModuleDescriptor#modifiers()
+     * @see AccessFlag.Location#MODULE
      */
     int moduleFlagsMask();
 
     /**
-     * {@return the the module flags of the module, as a set of enum constants}
+     * {@return the module flags of the module, as a set of enum constants}
+     *
+     * @throws IllegalArgumentException if the flags mask has any undefined bit set
+     * @see ModuleDescriptor#accessFlags()
+     * @see AccessFlag.Location#MODULE
      */
     default Set<AccessFlag> moduleFlags() {
         return AccessFlag.maskToAccessFlags(moduleFlagsMask(), AccessFlag.Location.MODULE);
     }
 
     /**
-     * Tests presence of module flag
+     * Tests presence of module flag.
+     *
      * @param flag the module flag
      * @return true if the flag is set
+     * @see AccessFlag.Location#MODULE
      */
     default boolean has(AccessFlag flag) {
         return Util.has(AccessFlag.Location.MODULE, moduleFlagsMask(), flag);
@@ -90,32 +112,49 @@ default boolean has(AccessFlag flag) {
 
     /**
      * {@return the version of the module, if present}
+     *
+     * @see ModuleDescriptor#version()
      */
     Optional<Utf8Entry> moduleVersion();
 
     /**
      * {@return the modules required by this module}
+     *
+     * @see ModuleDescriptor#requires()
      */
     List<ModuleRequireInfo> requires();
 
     /**
      * {@return the packages exported by this module}
+     *
+     * @see ModuleDescriptor#packages()
      */
     List<ModuleExportInfo> exports();
 
     /**
      * {@return the packages opened by this module}
+     *
+     * @apiNote
+     * Opening a package to another module allows that other module to gain
+     * the same full privilege access as members in this module.  See {@link
+     * MethodHandles#privateLookupIn} for more details.
+     *
+     * @see ModuleDescriptor#opens()
      */
     List<ModuleOpenInfo> opens();
 
     /**
      * {@return the services used by this module}  Services may be discovered via
-     * {@link java.util.ServiceLoader}.
+     * {@link ServiceLoader}.
+     *
+     * @see ModuleDescriptor#uses()
      */
     List<ClassEntry> uses();
 
     /**
      * {@return the service implementations provided by this module}
+     *
+     * @see ModuleDescriptor#provides()
      */
     List<ModuleProvideInfo> provides();
 
@@ -124,7 +163,7 @@ default boolean has(AccessFlag flag) {
      *
      * @param moduleName the module name
      * @param moduleFlags the module flags
-     * @param moduleVersion the module version
+     * @param moduleVersion the module version, may be {@code null}
      * @param requires the required packages
      * @param exports the exported packages
      * @param opens the opened packages
@@ -168,126 +207,165 @@ static ModuleAttribute of(ModuleEntry moduleName,
     }
 
     /**
-     * A builder for module attributes.
+     * A builder for {@link ModuleAttribute Module} attributes.
      *
+     * @see ModuleDescriptor.Builder
+     * @jvms 4.7.25 The {@code Module} Attribute
      * @since 24
      */
     public sealed interface ModuleAttributeBuilder
             permits ModuleAttributeBuilderImpl {
 
         /**
-         * Sets the module name
+         * Sets the module name.
+         *
          * @param moduleName the module name
          * @return this builder
          */
         ModuleAttributeBuilder moduleName(ModuleDesc moduleName);
 
         /**
-         * Sets the module flags
+         * Sets the module flags.
+         *
          * @param flagsMask the module flags
          * @return this builder
          */
         ModuleAttributeBuilder moduleFlags(int flagsMask);
 
         /**
-         * Sets the module flags
+         * Sets the module flags.
+         *
          * @param moduleFlags the module flags
          * @return this builder
+         * @throws IllegalArgumentException if any flag cannot be applied to the
+         *         {@link AccessFlag.Location#MODULE} location
          */
         default ModuleAttributeBuilder moduleFlags(AccessFlag... moduleFlags) {
             return moduleFlags(Util.flagsToBits(AccessFlag.Location.MODULE, moduleFlags));
         }
 
         /**
-         * Sets the module version
-         * @param version the module version
+         * Sets the module version, which may be {@code null}.
+         *
+         * @param version the module version, may be {@code null}
          * @return this builder
          */
         ModuleAttributeBuilder moduleVersion(String version);
 
         /**
-         * Adds module requirement
+         * Adds a module requirement.
+         *
          * @param module the required module
          * @param requiresFlagsMask the requires flags
-         * @param version the required module version
+         * @param version the required module version, may be {@code null}
          * @return this builder
          */
         ModuleAttributeBuilder requires(ModuleDesc module, int requiresFlagsMask, String version);
 
         /**
-         * Adds module requirement
+         * Adds a module requirement.
+         *
          * @param module the required module
          * @param requiresFlags the requires flags
-         * @param version the required module version
+         * @param version the required module version, may be {@code null}
          * @return this builder
+         * @throws IllegalArgumentException if any flag cannot be applied to the
+         *         {@link AccessFlag.Location#MODULE_REQUIRES} location
          */
         default ModuleAttributeBuilder requires(ModuleDesc module, Collection<AccessFlag> requiresFlags, String version) {
             return requires(module, Util.flagsToBits(AccessFlag.Location.MODULE_REQUIRES, requiresFlags), version);
         }
 
         /**
-         * Adds module requirement
+         * Adds module requirement.
+         *
          * @param requires the module require info
          * @return this builder
          */
         ModuleAttributeBuilder requires(ModuleRequireInfo requires);
 
         /**
-         * Adds exported package
+         * Adds an exported package.
+         *
          * @param pkge the exported package
          * @param exportsFlagsMask the export flags
-         * @param exportsToModules the modules to export to
+         * @param exportsToModules the modules to export to, or empty for an unqualified export
          * @return this builder
          */
         ModuleAttributeBuilder exports(PackageDesc pkge, int exportsFlagsMask, ModuleDesc... exportsToModules);
 
         /**
-         * Adds exported package
+         * Adds an exported package.
+         *
          * @param pkge the exported package
          * @param exportsFlags the export flags
-         * @param exportsToModules the modules to export to
+         * @param exportsToModules the modules to export to, or empty for an unqualified export
          * @return this builder
+         * @throws IllegalArgumentException if any flag cannot be applied to the
+         *         {@link AccessFlag.Location#MODULE_EXPORTS} location
          */
         default ModuleAttributeBuilder exports(PackageDesc pkge, Collection<AccessFlag> exportsFlags, ModuleDesc... exportsToModules) {
             return exports(pkge, Util.flagsToBits(AccessFlag.Location.MODULE_EXPORTS, exportsFlags), exportsToModules);
         }
 
         /**
-         * Adds exported package
+         * Adds an exported package.
+         *
          * @param exports the module export info
          * @return this builder
          */
         ModuleAttributeBuilder exports(ModuleExportInfo exports);
 
         /**
-         * Opens package
+         * Opens a package.
+         *
+         * @apiNote
+         * Opening a package to another module allows that other module to gain
+         * the same full privilege access as members in this module.  See {@link
+         * MethodHandles#privateLookupIn} for more details.
+         *
          * @param pkge the opened package
          * @param opensFlagsMask the open package flags
-         * @param opensToModules the modules to open to
+         * @param opensToModules the modules to open to, or empty for an unqualified open
          * @return this builder
          */
         ModuleAttributeBuilder opens(PackageDesc pkge, int opensFlagsMask, ModuleDesc... opensToModules);
 
         /**
-         * Opens package
+         * Opens a package.
+         *
+         * @apiNote
+         * Opening a package to another module allows that other module to gain
+         * the same full privilege access as members in this module.  See {@link
+         * MethodHandles#privateLookupIn} for more details.
+         *
          * @param pkge the opened package
          * @param opensFlags the open package flags
-         * @param opensToModules the modules to open to
+         * @param opensToModules the modules to open to, or empty for an unqualified open
          * @return this builder
+         * @throws IllegalArgumentException if any flag cannot be applied to the
+         *         {@link AccessFlag.Location#MODULE_OPENS} location
          */
         default ModuleAttributeBuilder opens(PackageDesc pkge, Collection<AccessFlag> opensFlags, ModuleDesc... opensToModules) {
             return opens(pkge, Util.flagsToBits(AccessFlag.Location.MODULE_OPENS, opensFlags), opensToModules);
         }
 
         /**
-         * Opens package
+         * Opens a package.
+         *
+         * @apiNote
+         * Opening a package to another module allows that other module to gain
+         * the same full privilege access as members in this module.  See {@link
+         * MethodHandles#privateLookupIn} for more details.
+         *
          * @param opens the module open info
          * @return this builder
          */
         ModuleAttributeBuilder opens(ModuleOpenInfo opens);
 
         /**
-         * Declares use of a service
+         * Declares use of a service.
+         *
          * @param service the service class used
          * @return this builder
          * @throws IllegalArgumentException if {@code service} represents a primitive type
@@ -295,14 +373,16 @@ default ModuleAttributeBuilder opens(PackageDesc pkge, Collection<AccessFlag> op
         ModuleAttributeBuilder uses(ClassDesc service);
 
         /**
-         * Declares use of a service
+         * Declares use of a service.
+         *
          * @param uses the service class used
          * @return this builder
          */
         ModuleAttributeBuilder uses(ClassEntry uses);
 
         /**
-         * Declares provision of a service
+         * Declares provision of a service.
+         *
          * @param service the service class provided
          * @param implClasses the implementation classes
          * @return this builder
@@ -311,7 +391,8 @@ default ModuleAttributeBuilder opens(PackageDesc pkge, Collection<AccessFlag> op
         ModuleAttributeBuilder provides(ClassDesc service, ClassDesc... implClasses);
 
         /**
-         * Declares provision of a service
+         * Declares provision of a service.
+         *
          * @param provides the module provides info
          * @return this builder
          */
diff --git a/src/java.base/share/classes/java/lang/classfile/attribute/ModuleExportInfo.java b/src/java.base/share/classes/java/lang/classfile/attribute/ModuleExportInfo.java
index 69290c55994..2071561a1e5 100644
--- a/src/java.base/share/classes/java/lang/classfile/attribute/ModuleExportInfo.java
+++ b/src/java.base/share/classes/java/lang/classfile/attribute/ModuleExportInfo.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2022, 2024, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2022, 2025, 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
@@ -24,11 +24,11 @@
  */
 package java.lang.classfile.attribute;
 
-import java.lang.classfile.ClassFile;
 import java.lang.classfile.constantpool.ModuleEntry;
 import java.lang.classfile.constantpool.PackageEntry;
 import java.lang.constant.ModuleDesc;
 import java.lang.constant.PackageDesc;
+import java.lang.module.ModuleDescriptor;
 import java.lang.reflect.AccessFlag;
 import java.util.Collection;
 import java.util.List;
@@ -41,6 +41,9 @@
 /**
  * Models a single "exports" declaration in the {@link ModuleAttribute}.
  *
+ * @see ModuleAttribute#exports()
+ * @see ModuleDescriptor.Exports
+ * @jvms 4.7.25 The {@code Module} Attribute
  * @since 24
  */
 public sealed interface ModuleExportInfo
@@ -48,43 +51,57 @@ public sealed interface ModuleExportInfo
 
     /**
      * {@return the exported package}
+     *
+     * @see ModuleDescriptor.Exports#source()
      */
     PackageEntry exportedPackage();
 
     /**
      * {@return the flags associated with this export declaration, as a bit mask}
-     * Valid flags include {@link ClassFile#ACC_SYNTHETIC} and
-     * {@link ClassFile#ACC_MANDATED}.
+     *
+     * @see ModuleDescriptor.Exports#modifiers()
+     * @see AccessFlag.Location#MODULE_EXPORTS
      */
     int exportsFlagsMask();
 
     /**
      * {@return the flags associated with this export declaration, as a set of
-     * flag values}
+     * flag enums}
+     *
+     * @throws IllegalArgumentException if the flags mask has any undefined bit set
+     * @see ModuleDescriptor.Exports#accessFlags()
+     * @see AccessFlag.Location#MODULE_EXPORTS
      */
     default Set<AccessFlag> exportsFlags() {
         return AccessFlag.maskToAccessFlags(exportsFlagsMask(), AccessFlag.Location.MODULE_EXPORTS);
     }
 
     /**
-     * {@return the list of modules to which this package is exported, if it is a
-     * qualified export}
-     */
-    List<ModuleEntry> exportsTo();
-
-    /**
-     * {@return whether the module has the specified access flag set}
+     * {@return whether the export declaration has the specified access flag set}
+     *
      * @param flag the access flag
+     * @see AccessFlag.Location#MODULE_EXPORTS
      */
     default boolean has(AccessFlag flag) {
         return Util.has(AccessFlag.Location.MODULE_EXPORTS, exportsFlagsMask(), flag);
     }
 
+    /**
+     * {@return the list of modules to which this package is exported, or empty
+     * if this is an unqualified export}
+     *
+     * @see ModuleDescriptor.Exports#isQualified()
+     * @see ModuleDescriptor.Exports#targets()
+     */
+    List<ModuleEntry> exportsTo();
+
     /**
      * {@return a module export description}
+     *
      * @param exports the exported package
      * @param exportFlags the export flags, as a bitmask
-     * @param exportsTo the modules to which this package is exported
+     * @param exportsTo the modules to which this package is exported, or empty
+     *        if this is an unqualified export
      */
     static ModuleExportInfo of(PackageEntry exports, int exportFlags,
                                List<ModuleEntry> exportsTo) {
@@ -93,9 +110,13 @@ static ModuleExportInfo of(PackageEntry exports, int exportFlags,
 
     /**
      * {@return a module export description}
+     *
      * @param exports the exported package
      * @param exportFlags the export flags
-     * @param exportsTo the modules to which this package is exported
+     * @param exportsTo the modules to which this package is exported, or empty
+     *        if this is an unqualified export
+     * @throws IllegalArgumentException if any flag cannot be applied to the
+     *         {@link AccessFlag.Location#MODULE_EXPORTS} location
      */
     static ModuleExportInfo of(PackageEntry exports, Collection<AccessFlag> exportFlags,
                                List<ModuleEntry> exportsTo) {
@@ -104,9 +125,11 @@ static ModuleExportInfo of(PackageEntry exports, Collection<AccessFlag> exportFl
 
     /**
      * {@return a module export description}
+     *
      * @param exports the exported package
      * @param exportFlags the export flags, as a bitmask
-     * @param exportsTo the modules to which this package is exported
+     * @param exportsTo the modules to which this package is exported, or empty
+     *        if this is an unqualified export
      */
     static ModuleExportInfo of(PackageEntry exports,
                                int exportFlags,
@@ -116,9 +139,13 @@ static ModuleExportInfo of(PackageEntry exports,
 
     /**
      * {@return a module export description}
+     *
      * @param exports the exported package
      * @param exportFlags the export flags
-     * @param exportsTo the modules to which this package is exported
+     * @param exportsTo the modules to which this package is exported, or empty
+     *        if this is an unqualified export
+     * @throws IllegalArgumentException if any flag cannot be applied to the
+     *         {@link AccessFlag.Location#MODULE_EXPORTS} location
      */
     static ModuleExportInfo of(PackageEntry exports,
                                Collection<AccessFlag> exportFlags,
@@ -128,9 +155,11 @@ static ModuleExportInfo of(PackageEntry exports,
 
     /**
      * {@return a module export description}
+     *
      * @param exports the exported package
      * @param exportFlags the export flags, as a bitmask
-     * @param exportsTo the modules to which this package is exported
+     * @param exportsTo the modules to which this package is exported, or empty
+     *        if this is an unqualified export
      */
     static ModuleExportInfo of(PackageDesc exports, int exportFlags,
                                List<ModuleDesc> exportsTo) {
@@ -141,9 +170,13 @@ static ModuleExportInfo of(PackageDesc exports, int exportFlags,
 
     /**
      * {@return a module export description}
+     *
      * @param exports the exported package
      * @param exportFlags the export flags
-     * @param exportsTo the modules to which this package is exported
+     * @param exportsTo the modules to which this package is exported, or empty
+     *        if this is an unqualified export
+     * @throws IllegalArgumentException if any flag cannot be applied to the
+     *         {@link AccessFlag.Location#MODULE_EXPORTS} location
      */
     static ModuleExportInfo of(PackageDesc exports, Collection<AccessFlag> exportFlags,
                                List<ModuleDesc> exportsTo) {
@@ -152,9 +185,11 @@ static ModuleExportInfo of(PackageDesc exports, Collection<AccessFlag> exportFla
 
     /**
      * {@return a module export description}
+     *
      * @param exports the exported package
      * @param exportFlags the export flags, as a bitmask
-     * @param exportsTo the modules to which this package is exported
+     * @param exportsTo the modules to which this package is exported, or empty
+     *        if this is an unqualified export
      */
     static ModuleExportInfo of(PackageDesc exports,
                                int exportFlags,
@@ -164,9 +199,13 @@ static ModuleExportInfo of(PackageDesc exports,
 
     /**
      * {@return a module export description}
+     *
      * @param exports the exported package
      * @param exportFlags the export flags
-     * @param exportsTo the modules to which this package is exported
+     * @param exportsTo the modules to which this package is exported, or empty
+     *        if this is an unqualified export
+     * @throws IllegalArgumentException if any flag cannot be applied to the
+     *         {@link AccessFlag.Location#MODULE_EXPORTS} location
      */
     static ModuleExportInfo of(PackageDesc exports,
                                Collection<AccessFlag> exportFlags,
diff --git a/src/java.base/share/classes/java/lang/classfile/attribute/ModuleHashInfo.java b/src/java.base/share/classes/java/lang/classfile/attribute/ModuleHashInfo.java
index 07616757daa..e89a941296c 100644
--- a/src/java.base/share/classes/java/lang/classfile/attribute/ModuleHashInfo.java
+++ b/src/java.base/share/classes/java/lang/classfile/attribute/ModuleHashInfo.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2022, 2024, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2022, 2025, 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
@@ -33,6 +33,7 @@
 /**
  * Models hash information for a single module in the {@link ModuleHashesAttribute}.
  *
+ * @see ModuleHashesAttribute#hashes()
  * @since 24
  */
 public sealed interface ModuleHashInfo
diff --git a/src/java.base/share/classes/java/lang/classfile/attribute/ModuleHashesAttribute.java b/src/java.base/share/classes/java/lang/classfile/attribute/ModuleHashesAttribute.java
index 918d18bda1e..11c016aa9e1 100644
--- a/src/java.base/share/classes/java/lang/classfile/attribute/ModuleHashesAttribute.java
+++ b/src/java.base/share/classes/java/lang/classfile/attribute/ModuleHashesAttribute.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2022, 2024, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2022, 2025, 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
@@ -26,7 +26,11 @@
 package java.lang.classfile.attribute;
 
 import java.lang.classfile.Attribute;
+import java.lang.classfile.AttributeMapper;
+import java.lang.classfile.AttributeMapper.AttributeStability;
+import java.lang.classfile.Attributes;
 import java.lang.classfile.ClassElement;
+import java.lang.classfile.ClassModel;
 import java.lang.classfile.constantpool.Utf8Entry;
 import java.util.List;
 
@@ -35,13 +39,11 @@
 import jdk.internal.classfile.impl.UnboundAttribute;
 
 /**
- * Models the {@code ModuleHashes} attribute, which can
- * appear on classes that represent module descriptors.  This is a JDK-specific
- * attribute, which captures the hashes of a set of co-delivered modules.
- * Delivered as a {@link java.lang.classfile.ClassElement} when
- * traversing the elements of a {@link java.lang.classfile.ClassModel}.
- *
- *  <p>The specification of the {@code ModuleHashes} attribute is:
+ * Models the {@link Attributes#moduleHashes() ModuleHashes} attribute, which
+ * appears on classes that {@linkplain ClassModel#isModuleInfo() represent}
+ * module descriptors to capture the hashes of a set of co-delivered modules.
+ * <p>
+ * The specification of the {@code ModuleHashes} attribute is:
  * <pre> {@code
  *
  * ModuleHashes_attribute {
@@ -63,10 +65,17 @@
  * }
  * } </pre>
  * <p>
- * The attribute does not permit multiple instances in a given location.
- * Subsequent occurrence of the attribute takes precedence during the attributed
- * element build or transformation.
+ * This attribute only appears on classes, and does not permit {@linkplain
+ * AttributeMapper#allowMultiple multiple instances} in a class.  It has a
+ * data dependency on the {@linkplain AttributeStability#CP_REFS constant pool}.
+ * <p>
+ * This attribute is not predefined in the Java SE Platform.  This is a
+ * JDK-specific nonstandard attribute produced by the {@code jdk.jlink} module,
+ * which defines the {@code jlink} and {@code jmod} tools.
  *
+ * @see Attributes#moduleHashes()
+ * @see ModuleResolutionAttribute
+ * @see ModuleTargetAttribute
  * @since 24
  */
 public sealed interface ModuleHashesAttribute
diff --git a/src/java.base/share/classes/java/lang/classfile/attribute/ModuleMainClassAttribute.java b/src/java.base/share/classes/java/lang/classfile/attribute/ModuleMainClassAttribute.java
index 7f06eb0f95b..cc88da465fe 100644
--- a/src/java.base/share/classes/java/lang/classfile/attribute/ModuleMainClassAttribute.java
+++ b/src/java.base/share/classes/java/lang/classfile/attribute/ModuleMainClassAttribute.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2022, 2024, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2022, 2025, 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
@@ -26,26 +26,36 @@
 package java.lang.classfile.attribute;
 
 import java.lang.classfile.Attribute;
+import java.lang.classfile.AttributeMapper;
+import java.lang.classfile.AttributeMapper.AttributeStability;
+import java.lang.classfile.Attributes;
 import java.lang.classfile.ClassElement;
+import java.lang.classfile.ClassFile;
+import java.lang.classfile.ClassModel;
 import java.lang.classfile.constantpool.ClassEntry;
 import java.lang.constant.ClassDesc;
+import java.lang.module.ModuleDescriptor;
 
 import jdk.internal.classfile.impl.BoundAttribute;
 import jdk.internal.classfile.impl.TemporaryConstantPool;
 import jdk.internal.classfile.impl.UnboundAttribute;
 
 /**
- * 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}.
+ * Models the {@link Attributes#moduleMainClass() ModuleMainClass} attribute
+ * (JVMS {@jvms 4.7.27}), which appears on classes that {@linkplain
+ * ClassModel#isModuleInfo() represent} module descriptors to indicate the main
+ * class of the module.
  * <p>
- * The attribute does not permit multiple instances in a given location.
- * Subsequent occurrence of the attribute takes precedence during the attributed
- * element build or transformation.
+ * This attribute only appears on classes, and does not permit {@linkplain
+ * AttributeMapper#allowMultiple multiple instances} in a class.  It has a
+ * data dependency on the {@linkplain AttributeStability#CP_REFS constant pool}.
  * <p>
- * The attribute was introduced in the Java SE Platform version 9.
+ * The attribute was introduced in the Java SE Platform version 9, major version
+ * {@value ClassFile#JAVA_9_VERSION}.
  *
+ * @see Attributes#moduleMainClass()
+ * @see ModuleDescriptor#mainClass()
+ * @jvms 4.7.27 The {@code ModuleMainClass} Attribute
  * @since 24
  */
 public sealed interface ModuleMainClassAttribute
diff --git a/src/java.base/share/classes/java/lang/classfile/attribute/ModuleOpenInfo.java b/src/java.base/share/classes/java/lang/classfile/attribute/ModuleOpenInfo.java
index a16c9973627..16c0cf8a057 100644
--- a/src/java.base/share/classes/java/lang/classfile/attribute/ModuleOpenInfo.java
+++ b/src/java.base/share/classes/java/lang/classfile/attribute/ModuleOpenInfo.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2022, 2024, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2022, 2025, 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
@@ -28,6 +28,8 @@
 import java.lang.classfile.constantpool.PackageEntry;
 import java.lang.constant.ModuleDesc;
 import java.lang.constant.PackageDesc;
+import java.lang.invoke.MethodHandles;
+import java.lang.module.ModuleDescriptor;
 import java.lang.reflect.AccessFlag;
 import java.util.Collection;
 import java.util.List;
@@ -40,6 +42,14 @@
 /**
  * Models a single "opens" declaration in the {@link ModuleAttribute}.
  *
+ * @apiNote
+ * Opening a package to another module allows that other module to gain
+ * the same full privilege access as members in this module.  See {@link
+ * MethodHandles#privateLookupIn} for more details.
+ *
+ * @see ModuleAttribute#exports()
+ * @see ModuleDescriptor.Opens
+ * @jvms 4.7.25 The {@code Module} Attribute
  * @since 24
  */
 public sealed interface ModuleOpenInfo
@@ -47,44 +57,57 @@ public sealed interface ModuleOpenInfo
 
     /**
      * {@return the package being opened}
+     *
+     * @see ModuleDescriptor.Opens#source()
      */
     PackageEntry openedPackage();
 
     /**
      * {@return the flags associated with this open declaration, as a bit mask}
-     * Valid flags include {@link java.lang.classfile.ClassFile#ACC_SYNTHETIC} and
-     * {@link java.lang.classfile.ClassFile#ACC_MANDATED}
+     *
+     * @see ModuleDescriptor.Opens#modifiers()
+     * @see AccessFlag.Location#MODULE_OPENS
      */
     int opensFlagsMask();
 
     /**
-     * {@return the access flags}
+     * {@return the flags associated with this open declaration, as a set of
+     * flag enums}
+     *
+     * @throws IllegalArgumentException if the flags mask has any undefined bit set
+     * @see ModuleDescriptor.Opens#accessFlags()
+     * @see AccessFlag.Location#MODULE_OPENS
      */
     default Set<AccessFlag> opensFlags() {
         return AccessFlag.maskToAccessFlags(opensFlagsMask(), AccessFlag.Location.MODULE_OPENS);
     }
 
     /**
-     * {@return whether the specified access flag is set}
+     * {@return whether the open declaration has the specified access flag set}
+     *
      * @param flag the access flag
+     * @see AccessFlag.Location#MODULE_OPENS
      */
     default boolean has(AccessFlag flag) {
         return Util.has(AccessFlag.Location.MODULE_OPENS, opensFlagsMask(), flag);
     }
 
     /**
-     * The list of modules to which this package is opened, if it is a
-     * qualified open.
+     * {@return the modules to which this package is opened, or empty if this
+     * is an unqualified open}
      *
-     * @return the modules to which this package is opened
+     * @see ModuleDescriptor.Opens#isQualified()
+     * @see ModuleDescriptor.Opens#targets()
      */
     List<ModuleEntry> opensTo();
 
     /**
      * {@return a module open description}
+     *
      * @param opens the package to open
      * @param opensFlags the open flags
-     * @param opensTo the packages to which this package is opened, if it is a qualified open
+     * @param opensTo the modules to which this package is opened, or empty if
+     *               this is an unqualified open
      */
     static ModuleOpenInfo of(PackageEntry opens, int opensFlags,
                              List<ModuleEntry> opensTo) {
@@ -93,9 +116,13 @@ static ModuleOpenInfo of(PackageEntry opens, int opensFlags,
 
     /**
      * {@return a module open description}
+     *
      * @param opens the package to open
      * @param opensFlags the open flags
-     * @param opensTo the packages to which this package is opened, if it is a qualified open
+     * @param opensTo the modules to which this package is opened, or empty if
+     *               this is an unqualified open
+     * @throws IllegalArgumentException if any flag cannot be applied to the
+     *         {@link AccessFlag.Location#MODULE_OPENS} location
      */
     static ModuleOpenInfo of(PackageEntry opens, Collection<AccessFlag> opensFlags,
                              List<ModuleEntry> opensTo) {
@@ -104,9 +131,11 @@ static ModuleOpenInfo of(PackageEntry opens, Collection<AccessFlag> opensFlags,
 
     /**
      * {@return a module open description}
+     *
      * @param opens the package to open
      * @param opensFlags the open flags
-     * @param opensTo the packages to which this package is opened, if it is a qualified open
+     * @param opensTo the modules to which this package is opened, or empty if
+     *               this is an unqualified open
      */
     static ModuleOpenInfo of(PackageEntry opens,
                              int opensFlags,
@@ -116,9 +145,13 @@ static ModuleOpenInfo of(PackageEntry opens,
 
     /**
      * {@return a module open description}
+     *
      * @param opens the package to open
      * @param opensFlags the open flags
-     * @param opensTo the packages to which this package is opened, if it is a qualified open
+     * @param opensTo the modules to which this package is opened, or empty if
+     *               this is an unqualified open
+     * @throws IllegalArgumentException if any flag cannot be applied to the
+     *         {@link AccessFlag.Location#MODULE_OPENS} location
      */
     static ModuleOpenInfo of(PackageEntry opens,
                              Collection<AccessFlag> opensFlags,
@@ -130,7 +163,8 @@ static ModuleOpenInfo of(PackageEntry opens,
      * {@return a module open description}
      * @param opens the package to open
      * @param opensFlags the open flags
-     * @param opensTo the packages to which this package is opened, if it is a qualified open
+     * @param opensTo the modules to which this package is opened, if it is a
+     *                qualified open, or empty
      */
     static ModuleOpenInfo of(PackageDesc opens, int opensFlags,
                              List<ModuleDesc> opensTo) {
@@ -143,7 +177,10 @@ static ModuleOpenInfo of(PackageDesc opens, int opensFlags,
      * {@return a module open description}
      * @param opens the package to open
      * @param opensFlags the open flags
-     * @param opensTo the packages to which this package is opened, if it is a qualified open
+     * @param opensTo the modules to which this package is opened, if it is a
+     *               qualified open, or empty
+     * @throws IllegalArgumentException if any flag cannot be applied to the
+     *         {@link AccessFlag.Location#MODULE_OPENS} location
      */
     static ModuleOpenInfo of(PackageDesc opens, Collection<AccessFlag> opensFlags,
                              List<ModuleDesc> opensTo) {
@@ -154,7 +191,8 @@ static ModuleOpenInfo of(PackageDesc opens, Collection<AccessFlag> opensFlags,
      * {@return a module open description}
      * @param opens the package to open
      * @param opensFlags the open flags
-     * @param opensTo the packages to which this package is opened, if it is a qualified open
+     * @param opensTo the packages to which this package is opened, or empty if
+     *               this is an unqualified open
      */
     static ModuleOpenInfo of(PackageDesc opens,
                              int opensFlags,
@@ -166,7 +204,10 @@ static ModuleOpenInfo of(PackageDesc opens,
      * {@return a module open description}
      * @param opens the package to open
      * @param opensFlags the open flags
-     * @param opensTo the packages to which this package is opened, if it is a qualified open
+     * @param opensTo the packages to which this package is opened, or empty if
+     *               this is an unqualified open
+     * @throws IllegalArgumentException if any flag cannot be applied to the
+     *         {@link AccessFlag.Location#MODULE_OPENS} location
      */
     static ModuleOpenInfo of(PackageDesc opens,
                              Collection<AccessFlag> opensFlags,
diff --git a/src/java.base/share/classes/java/lang/classfile/attribute/ModulePackagesAttribute.java b/src/java.base/share/classes/java/lang/classfile/attribute/ModulePackagesAttribute.java
index ec0a65742b4..24a9218c9fd 100644
--- a/src/java.base/share/classes/java/lang/classfile/attribute/ModulePackagesAttribute.java
+++ b/src/java.base/share/classes/java/lang/classfile/attribute/ModulePackagesAttribute.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2022, 2024, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2022, 2025, 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
@@ -25,9 +25,15 @@
 package java.lang.classfile.attribute;
 
 import java.lang.classfile.Attribute;
+import java.lang.classfile.AttributeMapper;
+import java.lang.classfile.AttributeMapper.AttributeStability;
+import java.lang.classfile.Attributes;
 import java.lang.classfile.ClassElement;
+import java.lang.classfile.ClassFile;
+import java.lang.classfile.ClassModel;
 import java.lang.classfile.constantpool.PackageEntry;
 import java.lang.constant.PackageDesc;
+import java.lang.module.ModuleDescriptor;
 import java.util.Arrays;
 import java.util.List;
 
@@ -36,17 +42,21 @@
 import jdk.internal.classfile.impl.UnboundAttribute;
 
 /**
- * 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}.
+ * Models the {@link Attributes#modulePackages() ModulePackages} attribute (JVMS
+ * {@jvms 4.7.26}), which can appear on classes that {@linkplain
+ * ClassModel#isModuleInfo() represent} module descriptors to indicate packages
+ * in the module used by the module descriptor.
  * <p>
- * The attribute does not permit multiple instances in a given location.
- * Subsequent occurrence of the attribute takes precedence during the attributed
- * element build or transformation.
+ * This attribute only appears on classes, and does not permit {@linkplain
+ * AttributeMapper#allowMultiple multiple instances} in a class.  It has a
+ * data dependency on the {@linkplain AttributeStability#CP_REFS constant pool}.
  * <p>
- * The attribute was introduced in the Java SE Platform version 9.
+ * The attribute was introduced in the Java SE Platform version 9, major version
+ * {@value ClassFile#JAVA_9_VERSION}.
  *
+ * @see Attributes#modulePackages()
+ * @see ModuleDescriptor#packages()
+ * @jvms 4.7.26 The {@code ModulePackages} Attribute
  * @since 24
  */
 public sealed interface ModulePackagesAttribute
@@ -55,7 +65,9 @@ public sealed interface ModulePackagesAttribute
                 UnboundAttribute.UnboundModulePackagesAttribute {
 
     /**
-     * {@return the packages that are opened or exported by this module}
+     * {@return the packages used by the module descriptor}  This must include
+     * all packages opened or exported by the module, as well as the packages of
+     * any service providers, and the package for the main class.
      */
     List<PackageEntry> packages();
 
diff --git a/src/java.base/share/classes/java/lang/classfile/attribute/ModuleProvideInfo.java b/src/java.base/share/classes/java/lang/classfile/attribute/ModuleProvideInfo.java
index ce68848d4dc..76dc88c50f7 100644
--- a/src/java.base/share/classes/java/lang/classfile/attribute/ModuleProvideInfo.java
+++ b/src/java.base/share/classes/java/lang/classfile/attribute/ModuleProvideInfo.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2022, 2024, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2022, 2025, 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
@@ -26,6 +26,7 @@
 
 import java.lang.classfile.constantpool.ClassEntry;
 import java.lang.constant.ClassDesc;
+import java.lang.module.ModuleDescriptor;
 import java.util.Arrays;
 import java.util.List;
 
@@ -36,6 +37,9 @@
 /**
  * Models a single "provides" declaration in the {@link ModuleAttribute}.
  *
+ * @see ModuleAttribute#provides()
+ * @see ModuleDescriptor.Provides
+ * @jvms 4.7.25 The {@code Module} Attribute
  * @since 24
  */
 public sealed interface ModuleProvideInfo
@@ -43,18 +47,23 @@ public sealed interface ModuleProvideInfo
 
     /**
      * {@return the service interface representing the provided service}
+     *
+     * @see ModuleDescriptor.Provides#service()
      */
     ClassEntry provides();
 
     /**
-     * {@return the classes providing the service implementation}
+     * {@return the classes providing the service implementation}  The list
+     * should not be empty.
+     *
+     * @see ModuleDescriptor.Provides#providers()
      */
     List<ClassEntry> providesWith();
 
     /**
      * {@return a service provision description}
      * @param provides the service class interface
-     * @param providesWith the service class implementations
+     * @param providesWith the service class implementations, must not be empty
      */
     static ModuleProvideInfo of(ClassEntry provides,
                                 List<ClassEntry> providesWith) {
@@ -64,7 +73,7 @@ static ModuleProvideInfo of(ClassEntry provides,
     /**
      * {@return a service provision description}
      * @param provides the service class interface
-     * @param providesWith the service class implementations
+     * @param providesWith the service class implementations, must not be empty
      */
     static ModuleProvideInfo of(ClassEntry provides,
                                 ClassEntry... providesWith) {
@@ -74,22 +83,24 @@ static ModuleProvideInfo of(ClassEntry provides,
     /**
      * {@return a service provision description}
      * @param provides the service class interface
-     * @param providesWith the service class implementations
-     * @throws IllegalArgumentException if {@code provides} represents a primitive type
+     * @param providesWith the service class implementations, must not be empty
+     * @throws IllegalArgumentException if {@code provides} or any of {@code
+     *         providesWith} represents a primitive type
      */
     static ModuleProvideInfo of(ClassDesc provides,
-                                       List<ClassDesc> providesWith) {
+                                List<ClassDesc> providesWith) {
         return of(TemporaryConstantPool.INSTANCE.classEntry(provides), Util.entryList(providesWith));
     }
 
     /**
      * {@return a service provision description}
      * @param provides the service class interface
-     * @param providesWith the service class implementations
-     * @throws IllegalArgumentException if {@code provides} or any of {@code providesWith} represents a primitive type
+     * @param providesWith the service class implementations, must not be empty
+     * @throws IllegalArgumentException if {@code provides} or any of {@code
+     *         providesWith} represents a primitive type
      */
     static ModuleProvideInfo of(ClassDesc provides,
-                                       ClassDesc... providesWith) {
+                                ClassDesc... providesWith) {
         // List view, since ref to providesWith is temporary
         return of(provides, Arrays.asList(providesWith));
     }
diff --git a/src/java.base/share/classes/java/lang/classfile/attribute/ModuleRequireInfo.java b/src/java.base/share/classes/java/lang/classfile/attribute/ModuleRequireInfo.java
index 578a783f277..edffe941629 100644
--- a/src/java.base/share/classes/java/lang/classfile/attribute/ModuleRequireInfo.java
+++ b/src/java.base/share/classes/java/lang/classfile/attribute/ModuleRequireInfo.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2022, 2024, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2022, 2025, 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
@@ -27,6 +27,7 @@
 import java.lang.classfile.constantpool.ModuleEntry;
 import java.lang.classfile.constantpool.Utf8Entry;
 import java.lang.constant.ModuleDesc;
+import java.lang.module.ModuleDescriptor;
 import java.lang.reflect.AccessFlag;
 import java.util.Collection;
 import java.util.Optional;
@@ -39,6 +40,9 @@
 /**
  * Models a single "requires" declaration in the {@link ModuleAttribute}.
  *
+ * @see ModuleAttribute#requires()
+ * @see ModuleDescriptor#requires()
+ * @jvms 4.7.25 The {@code Module} Attribute
  * @since 24
  */
 public sealed interface ModuleRequireInfo
@@ -51,15 +55,19 @@ public sealed interface ModuleRequireInfo
 
     /**
      * {@return the flags associated with this require declaration, as a bit mask}
-     * Valid flags include {@link java.lang.classfile.ClassFile#ACC_TRANSITIVE},
-     * {@link java.lang.classfile.ClassFile#ACC_STATIC_PHASE},
-     * {@link java.lang.classfile.ClassFile#ACC_SYNTHETIC} and
-     * {@link java.lang.classfile.ClassFile#ACC_MANDATED}
+     *
+     * @see ModuleDescriptor.Requires#modifiers()
+     * @see AccessFlag.Location#MODULE_REQUIRES
      */
     int requiresFlagsMask();
 
     /**
-     * {@return the access flags}
+     * {@return the flags associated with this require declaration, as a set of
+     * flag enums}
+     *
+     * @throws IllegalArgumentException if the flags mask has any undefined bit set
+     * @see ModuleDescriptor.Requires#accessFlags()
+     * @see AccessFlag.Location#MODULE_REQUIRES
      */
     default Set<AccessFlag> requiresFlags() {
         return AccessFlag.maskToAccessFlags(requiresFlagsMask(), AccessFlag.Location.MODULE_REQUIRES);
@@ -67,12 +75,16 @@ default Set<AccessFlag> requiresFlags() {
 
     /**
      * {@return the required version of the required module, if present}
+     *
+     * @see ModuleDescriptor.Requires#rawCompiledVersion()
      */
     Optional<Utf8Entry> requiresVersion();
 
     /**
      * {@return whether the specific access flag is set}
+     *
      * @param flag the access flag
+     * @see AccessFlag.Location#MODULE_REQUIRES
      */
     default boolean has(AccessFlag flag) {
         return Util.has(AccessFlag.Location.MODULE_REQUIRES, requiresFlagsMask(), flag);
@@ -80,9 +92,10 @@ default boolean has(AccessFlag flag) {
 
     /**
      * {@return a module requirement description}
+     *
      * @param requires the required module
      * @param requiresFlags the require-specific flags
-     * @param requiresVersion the required version
+     * @param requiresVersion the required version, may be {@code null}
      */
     static ModuleRequireInfo of(ModuleEntry requires, int requiresFlags, Utf8Entry requiresVersion) {
         return new UnboundAttribute.UnboundModuleRequiresInfo(requires, requiresFlags, Optional.ofNullable(requiresVersion));
@@ -90,9 +103,12 @@ static ModuleRequireInfo of(ModuleEntry requires, int requiresFlags, Utf8Entry r
 
     /**
      * {@return a module requirement description}
+     *
      * @param requires the required module
      * @param requiresFlags the require-specific flags
-     * @param requiresVersion the required version
+     * @param requiresVersion the required version, may be {@code null}
+     * @throws IllegalArgumentException if any flag cannot be applied to the
+     *         {@link AccessFlag.Location#MODULE_REQUIRES} location
      */
     static ModuleRequireInfo of(ModuleEntry requires, Collection<AccessFlag> requiresFlags, Utf8Entry requiresVersion) {
         return of(requires, Util.flagsToBits(AccessFlag.Location.MODULE_REQUIRES, requiresFlags), requiresVersion);
@@ -100,9 +116,10 @@ static ModuleRequireInfo of(ModuleEntry requires, Collection<AccessFlag> require
 
     /**
      * {@return a module requirement description}
+     *
      * @param requires the required module
      * @param requiresFlags the require-specific flags
-     * @param requiresVersion the required version
+     * @param requiresVersion the required version, may be {@code null}
      */
     static ModuleRequireInfo of(ModuleDesc requires, int requiresFlags, String requiresVersion) {
         return new UnboundAttribute.UnboundModuleRequiresInfo(TemporaryConstantPool.INSTANCE.moduleEntry(TemporaryConstantPool.INSTANCE.utf8Entry(requires.name())), requiresFlags, Optional.ofNullable(requiresVersion).map(s -> TemporaryConstantPool.INSTANCE.utf8Entry(s)));
@@ -110,9 +127,12 @@ static ModuleRequireInfo of(ModuleDesc requires, int requiresFlags, String requi
 
     /**
      * {@return a module requirement description}
+     *
      * @param requires the required module
      * @param requiresFlags the require-specific flags
-     * @param requiresVersion the required version
+     * @param requiresVersion the required version, may be {@code null}
+     * @throws IllegalArgumentException if any flag cannot be applied to the
+     *         {@link AccessFlag.Location#MODULE_REQUIRES} location
      */
     static ModuleRequireInfo of(ModuleDesc requires, Collection<AccessFlag> requiresFlags, String requiresVersion) {
         return of(requires, Util.flagsToBits(AccessFlag.Location.MODULE_REQUIRES, requiresFlags), requiresVersion);
diff --git a/src/java.base/share/classes/java/lang/classfile/attribute/ModuleResolutionAttribute.java b/src/java.base/share/classes/java/lang/classfile/attribute/ModuleResolutionAttribute.java
index 3457cb8073e..75e9ca485ff 100644
--- a/src/java.base/share/classes/java/lang/classfile/attribute/ModuleResolutionAttribute.java
+++ b/src/java.base/share/classes/java/lang/classfile/attribute/ModuleResolutionAttribute.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2022, 2024, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2022, 2025, 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
@@ -26,19 +26,21 @@
 package java.lang.classfile.attribute;
 
 import java.lang.classfile.Attribute;
+import java.lang.classfile.AttributeMapper;
+import java.lang.classfile.AttributeMapper.AttributeStability;
+import java.lang.classfile.Attributes;
 import java.lang.classfile.ClassElement;
+import java.lang.classfile.ClassModel;
 
 import jdk.internal.classfile.impl.BoundAttribute;
 import jdk.internal.classfile.impl.UnboundAttribute;
 
 /**
- * Models the {@code ModuleResolution} attribute, which can
- * appear on classes that represent module descriptors.  This is a JDK-specific
- *  * attribute, which captures resolution metadata for modules.
- * Delivered as a {@link java.lang.classfile.ClassElement} when
- * traversing the elements of a {@link java.lang.classfile.ClassModel}.
- *
- *  <p>The specification of the {@code ModuleResolution} attribute is:
+ * Models the {@link Attributes#moduleResolution() ModuleResolution} attribute,
+ * which can appear on classes that {@linkplain ClassModel#isModuleInfo()
+ * represent} module descriptors, to capture resolution metadata for modules.
+ * <p>
+ * The specification of the {@code ModuleResolution} attribute is:
  * <pre> {@code
  *  ModuleResolution_attribute {
  *    u2 attribute_name_index;    // "ModuleResolution"
@@ -58,10 +60,17 @@
  *  }
  * } </pre>
  * <p>
- * The attribute does not permit multiple instances in a given location.
- * Subsequent occurrence of the attribute takes precedence during the attributed
- * element build or transformation.
+ * This attribute only appears on classes, and does not permit {@linkplain
+ * AttributeMapper#allowMultiple multiple instances} in a class.  It has
+ * {@linkplain AttributeStability#STATELESS no data dependency}.
+ * <p>
+ * This attribute is not predefined in the Java SE Platform.  This is a
+ * JDK-specific nonstandard attribute produced by the {@code jdk.jlink} module,
+ * which defines the {@code jlink} and {@code jmod} tools.
  *
+ * @see Attributes#moduleResolution()
+ * @see ModuleHashesAttribute
+ * @see ModuleTargetAttribute
  * @since 24
  */
 public sealed interface ModuleResolutionAttribute
@@ -69,8 +78,10 @@ public sealed interface ModuleResolutionAttribute
         permits BoundAttribute.BoundModuleResolutionAttribute, UnboundAttribute.UnboundModuleResolutionAttribute {
 
     /**
-     *  The value of the resolution_flags item is a mask of flags used to denote
-     *  properties of module resolution. The flags are as follows:
+     * {@return the module resolution flags}
+     * <p>
+     * The value of the resolution_flags item is a mask of flags used to denote
+     * properties of module resolution. The flags are as follows:
      * <pre> {@code
      *   // Optional
      *   0x0001 (DO_NOT_RESOLVE_BY_DEFAULT)
@@ -80,12 +91,12 @@ public sealed interface ModuleResolutionAttribute
      *   0x0004 (WARN_DEPRECATED_FOR_REMOVAL)
      *   0x0008 (WARN_INCUBATING)
      *  } </pre>
-     * @return the module resolution flags
      */
     int resolutionFlags();
 
     /**
      * {@return a {@code ModuleResolution} attribute}
+     *
      * @param resolutionFlags the resolution flags
      */
     static ModuleResolutionAttribute of(int resolutionFlags) {
diff --git a/src/java.base/share/classes/java/lang/classfile/attribute/ModuleTargetAttribute.java b/src/java.base/share/classes/java/lang/classfile/attribute/ModuleTargetAttribute.java
index ac390c3d391..6d727db6851 100644
--- a/src/java.base/share/classes/java/lang/classfile/attribute/ModuleTargetAttribute.java
+++ b/src/java.base/share/classes/java/lang/classfile/attribute/ModuleTargetAttribute.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2022, 2024, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2022, 2025, 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
@@ -26,7 +26,11 @@
 package java.lang.classfile.attribute;
 
 import java.lang.classfile.Attribute;
+import java.lang.classfile.AttributeMapper;
+import java.lang.classfile.AttributeMapper.AttributeStability;
+import java.lang.classfile.Attributes;
 import java.lang.classfile.ClassElement;
+import java.lang.classfile.ClassModel;
 import java.lang.classfile.constantpool.Utf8Entry;
 
 import jdk.internal.classfile.impl.BoundAttribute;
@@ -34,13 +38,11 @@
 import jdk.internal.classfile.impl.UnboundAttribute;
 
 /**
- * Models the {@code ModuleTarget} attribute, which can
- * appear on classes that represent module descriptors.  This is a JDK-specific
- * attribute, which captures constraints on the target platform.
- * Delivered as a {@link java.lang.classfile.ClassElement} when
- * traversing the elements of a {@link java.lang.classfile.ClassModel}.
- *
- * <p>The specification of the {@code ModuleTarget} attribute is:
+ * Models the {@link Attributes#moduleTarget() ModuleTarget} attribute, which
+ * can appear on classes that {@linkplain ClassModel#isModuleInfo() represent}
+ * module descriptors, to represent constraints on the target platform.
+ * <p>
+ * The specification of the {@code ModuleTarget} attribute is:
  * <pre> {@code
  * TargetPlatform_attribute {
  *   // index to CONSTANT_utf8_info structure in constant pool representing
@@ -53,10 +55,17 @@
  * }
  * } </pre>
  * <p>
- * The attribute does not permit multiple instances in a given location.
- * Subsequent occurrence of the attribute takes precedence during the attributed
- * element build or transformation.
+ * This attribute only appears on classes, and does not permit {@linkplain
+ * AttributeMapper#allowMultiple multiple instances} in a class.  It has a
+ * data dependency on the {@linkplain AttributeStability#CP_REFS constant pool}.
+ * <p>
+ * This attribute is not predefined in the Java SE Platform.  This is a
+ * JDK-specific nonstandard attribute produced by the {@code jdk.jlink} module,
+ * which defines the {@code jlink} and {@code jmod} tools.
  *
+ * @see Attributes#moduleTarget()
+ * @see ModuleHashesAttribute
+ * @see ModuleResolutionAttribute
  * @since 24
  */
 public sealed interface ModuleTargetAttribute
@@ -70,6 +79,7 @@ public sealed interface ModuleTargetAttribute
 
     /**
      * {@return a {@code ModuleTarget} attribute}
+     *
      * @param targetPlatform the target platform
      */
     static ModuleTargetAttribute of(String targetPlatform) {
@@ -78,6 +88,7 @@ static ModuleTargetAttribute of(String targetPlatform) {
 
     /**
      * {@return a {@code ModuleTarget} attribute}
+     *
      * @param targetPlatform the target platform
      */
     static ModuleTargetAttribute of(Utf8Entry targetPlatform) {
diff --git a/src/java.base/share/classes/java/lang/classfile/attribute/NestHostAttribute.java b/src/java.base/share/classes/java/lang/classfile/attribute/NestHostAttribute.java
index ccfb61242cd..d2c398e556b 100644
--- a/src/java.base/share/classes/java/lang/classfile/attribute/NestHostAttribute.java
+++ b/src/java.base/share/classes/java/lang/classfile/attribute/NestHostAttribute.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2022, 2024, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2022, 2025, 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
@@ -26,7 +26,11 @@
 package java.lang.classfile.attribute;
 
 import java.lang.classfile.Attribute;
+import java.lang.classfile.AttributeMapper;
+import java.lang.classfile.AttributeMapper.AttributeStability;
+import java.lang.classfile.Attributes;
 import java.lang.classfile.ClassElement;
+import java.lang.classfile.ClassFile;
 import java.lang.classfile.constantpool.ClassEntry;
 import java.lang.constant.ClassDesc;
 
@@ -35,17 +39,22 @@
 import jdk.internal.classfile.impl.UnboundAttribute;
 
 /**
- * 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}.
+ * Models the {@link Attributes#nestHost() NestHost} attribute (JVMS {@jvms
+ * 4.7.28}), which indicates this class is a member of a nest and the host
+ * class of the nest.
  * <p>
- * The attribute does not permit multiple instances in a given location.
- * Subsequent occurrence of the attribute takes precedence during the attributed
- * element build or transformation.
+ * This attribute only appears on classes, and does not permit {@linkplain
+ * AttributeMapper#allowMultiple multiple instances} in a class.  It has a
+ * data dependency on the {@linkplain AttributeStability#CP_REFS constant pool}.
  * <p>
- * The attribute was introduced in the Java SE Platform version 11.
+ * The attribute was introduced in the Java SE Platform version 11, major
+ * version {@value ClassFile#JAVA_11_VERSION}.
  *
+ * @see Attributes#nestHost()
+ * @see NestMembersAttribute
+ * @see Class#getNestHost()
+ * @see Class#isNestmateOf(Class)
+ * @jvms 4.7.28 The {@code NestHost} Attribute
  * @since 24
  */
 public sealed interface NestHostAttribute extends Attribute<NestHostAttribute>, ClassElement
@@ -54,11 +63,14 @@ public sealed interface NestHostAttribute extends Attribute<NestHostAttribute>,
 
     /**
      * {@return the host class of the nest to which this class belongs}
+     *
+     * @see Class#getNestHost()
      */
     ClassEntry nestHost();
 
     /**
      * {@return a {@code NestHost} attribute}
+     *
      * @param nestHost the host class of the nest
      */
     static NestHostAttribute of(ClassEntry nestHost) {
@@ -67,6 +79,7 @@ static NestHostAttribute of(ClassEntry nestHost) {
 
     /**
      * {@return a {@code NestHost} attribute}
+     *
      * @param nestHost the host class of the nest
      * @throws IllegalArgumentException if {@code nestHost} represents a primitive type
      */
diff --git a/src/java.base/share/classes/java/lang/classfile/attribute/NestMembersAttribute.java b/src/java.base/share/classes/java/lang/classfile/attribute/NestMembersAttribute.java
index b01c05542de..baab955221c 100644
--- a/src/java.base/share/classes/java/lang/classfile/attribute/NestMembersAttribute.java
+++ b/src/java.base/share/classes/java/lang/classfile/attribute/NestMembersAttribute.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2022, 2024, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2022, 2025, 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
@@ -25,7 +25,11 @@
 package java.lang.classfile.attribute;
 
 import java.lang.classfile.Attribute;
+import java.lang.classfile.AttributeMapper;
+import java.lang.classfile.AttributeMapper.AttributeStability;
+import java.lang.classfile.Attributes;
 import java.lang.classfile.ClassElement;
+import java.lang.classfile.ClassFile;
 import java.lang.classfile.constantpool.ClassEntry;
 import java.lang.constant.ClassDesc;
 import java.util.Arrays;
@@ -36,17 +40,22 @@
 import jdk.internal.classfile.impl.Util;
 
 /**
- * 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}.
+ * Models the {@link Attributes#nestMembers() NestMembers} attribute (JVMS
+ * {@jvms 4.7.29}), which indicates that this class is the host of a nest
+ * and the other nest members.
  * <p>
- * The attribute does not permit multiple instances in a given location.
- * Subsequent occurrence of the attribute takes precedence during the attributed
- * element build or transformation.
+ * This attribute only appears on classes, and does not permit {@linkplain
+ * AttributeMapper#allowMultiple multiple instances} in a class.  It has a
+ * data dependency on the {@linkplain AttributeStability#CP_REFS constant pool}.
  * <p>
- * The attribute was introduced in the Java SE Platform version 11.
+ * The attribute was introduced in the Java SE Platform version 11, major
+ * version {@value ClassFile#JAVA_11_VERSION}.
  *
+ * @see Attributes#nestMembers()
+ * @see NestHostAttribute
+ * @see Class#getNestMembers()
+ * @see Class#isNestmateOf(Class)
+ * @jvms 4.7.29 The {@code NestMembers} Attribute
  * @since 24
  */
 public sealed interface NestMembersAttribute extends Attribute<NestMembersAttribute>, ClassElement
@@ -54,11 +63,14 @@ public sealed interface NestMembersAttribute extends Attribute<NestMembersAttrib
 
     /**
      * {@return the classes belonging to the nest hosted by this class}
+     *
+     * @see Class#getNestMembers()
      */
     List<ClassEntry> nestMembers();
 
     /**
      * {@return a {@code NestMembers} attribute}
+     *
      * @param nestMembers the member classes of the nest
      */
     static NestMembersAttribute of(List<ClassEntry> nestMembers) {
@@ -67,6 +79,7 @@ static NestMembersAttribute of(List<ClassEntry> nestMembers) {
 
     /**
      * {@return a {@code NestMembers} attribute}
+     *
      * @param nestMembers the member classes of the nest
      */
     static NestMembersAttribute of(ClassEntry... nestMembers) {
@@ -75,7 +88,9 @@ static NestMembersAttribute of(ClassEntry... nestMembers) {
 
     /**
      * {@return a {@code NestMembers} attribute}
+     *
      * @param nestMembers the member classes of the nest
+     * @throws IllegalArgumentException if any of {@code nestMembers} is primitive
      */
     static NestMembersAttribute ofSymbols(List<ClassDesc> nestMembers) {
         return of(Util.entryList(nestMembers));
@@ -83,10 +98,12 @@ static NestMembersAttribute ofSymbols(List<ClassDesc> nestMembers) {
 
     /**
      * {@return a {@code NestMembers} attribute}
+     *
      * @param nestMembers the member classes of the nest
+     * @throws IllegalArgumentException if any of {@code nestMembers} is primitive
      */
     static NestMembersAttribute ofSymbols(ClassDesc... nestMembers) {
-        // List view, since ref to nestMembers is temporary
+        // List version does defensive copy
         return ofSymbols(Arrays.asList(nestMembers));
     }
 }
diff --git a/src/java.base/share/classes/java/lang/classfile/attribute/PermittedSubclassesAttribute.java b/src/java.base/share/classes/java/lang/classfile/attribute/PermittedSubclassesAttribute.java
index dac63c73435..026cbb96ca0 100644
--- a/src/java.base/share/classes/java/lang/classfile/attribute/PermittedSubclassesAttribute.java
+++ b/src/java.base/share/classes/java/lang/classfile/attribute/PermittedSubclassesAttribute.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2022, 2024, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2022, 2025, 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
@@ -25,7 +25,11 @@
 package java.lang.classfile.attribute;
 
 import java.lang.classfile.Attribute;
+import java.lang.classfile.AttributeMapper;
+import java.lang.classfile.AttributeMapper.AttributeStability;
+import java.lang.classfile.Attributes;
 import java.lang.classfile.ClassElement;
+import java.lang.classfile.ClassFile;
 import java.lang.classfile.constantpool.ClassEntry;
 import java.lang.constant.ClassDesc;
 import java.util.Arrays;
@@ -36,31 +40,43 @@
 import jdk.internal.classfile.impl.Util;
 
 /**
- * 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}.
+ * Models the {@link Attributes#permittedSubclasses() PermittedSubclasses}
+ * attribute (JVMS {@jvms 4.7.31}), which indicates this class or interface
+ * is {@linkplain java.compiler/javax.lang.model.element.Modifier#SEALED sealed},
+ * and which classes or interfaces may extend or implement this class or
+ * interface.
  * <p>
- * The attribute does not permit multiple instances in a given location.
- * Subsequent occurrence of the attribute takes precedence during the attributed
- * element build or transformation.
+ * This attribute only appears on classes, and does not permit {@linkplain
+ * AttributeMapper#allowMultiple multiple instances} in a class.  It has a
+ * data dependency on the {@linkplain AttributeStability#CP_REFS constant pool}.
  * <p>
- * The attribute was introduced in the Java SE Platform version 17.
+ * The attribute was introduced in the Java SE Platform version 17, major
+ * version {@value ClassFile#JAVA_17_VERSION}.
  *
+ * @see Attributes#permittedSubclasses()
+ * @see Class#isSealed()
+ * @see Class#getPermittedSubclasses()
+ * @jls 8.1.1.2 {@code sealed}, {@code non-sealed}, and {@code final} Classes
+ * @jls 9.1.1.4 {@code sealed} and {@code non-sealed} Interfaces
+ * @jvms 4.7.31 The {@code PermittedSubclasses} Attribute
  * @since 24
  */
+@SuppressWarnings("doclint:reference")
 public sealed interface PermittedSubclassesAttribute
         extends Attribute<PermittedSubclassesAttribute>, ClassElement
         permits BoundAttribute.BoundPermittedSubclassesAttribute, UnboundAttribute.UnboundPermittedSubclassesAttribute {
 
     /**
-     * {@return the list of permitted subclasses}
+     * {@return the list of permitted subclasses or subinterfaces}
+     *
+     * @see Class#getPermittedSubclasses()
      */
     List<ClassEntry> permittedSubclasses();
 
     /**
      * {@return a {@code PermittedSubclasses} attribute}
-     * @param permittedSubclasses the permitted subclasses
+     *
+     * @param permittedSubclasses the permitted subclasses or subinterfaces
      */
     static PermittedSubclassesAttribute of(List<ClassEntry> permittedSubclasses) {
         return new UnboundAttribute.UnboundPermittedSubclassesAttribute(permittedSubclasses);
@@ -68,7 +84,8 @@ static PermittedSubclassesAttribute of(List<ClassEntry> permittedSubclasses) {
 
     /**
      * {@return a {@code PermittedSubclasses} attribute}
-     * @param permittedSubclasses the permitted subclasses
+     *
+     * @param permittedSubclasses the permitted subclasses or subinterfaces
      */
     static PermittedSubclassesAttribute of(ClassEntry... permittedSubclasses) {
         return of(List.of(permittedSubclasses));
@@ -76,7 +93,9 @@ static PermittedSubclassesAttribute of(ClassEntry... permittedSubclasses) {
 
     /**
      * {@return a {@code PermittedSubclasses} attribute}
-     * @param permittedSubclasses the permitted subclasses
+     *
+     * @param permittedSubclasses the permitted subclasses or subinterfaces
+     * @throws IllegalArgumentException if any of {@code permittedSubclasses} is primitive
      */
     static PermittedSubclassesAttribute ofSymbols(List<ClassDesc> permittedSubclasses) {
         return of(Util.entryList(permittedSubclasses));
@@ -84,10 +103,12 @@ static PermittedSubclassesAttribute ofSymbols(List<ClassDesc> permittedSubclasse
 
     /**
      * {@return a {@code PermittedSubclasses} attribute}
-     * @param permittedSubclasses the permitted subclasses
+     *
+     * @param permittedSubclasses the permitted subclasses or subinterfaces
+     * @throws IllegalArgumentException if any of {@code permittedSubclasses} is primitive
      */
     static PermittedSubclassesAttribute ofSymbols(ClassDesc... permittedSubclasses) {
-        // List view, since ref to nestMembers is temporary
+        // List version does defensive copy
         return ofSymbols(Arrays.asList(permittedSubclasses));
     }
 }
diff --git a/src/java.base/share/classes/java/lang/classfile/attribute/RecordAttribute.java b/src/java.base/share/classes/java/lang/classfile/attribute/RecordAttribute.java
index b0c4fa7c61c..8f55b3a1cf9 100644
--- a/src/java.base/share/classes/java/lang/classfile/attribute/RecordAttribute.java
+++ b/src/java.base/share/classes/java/lang/classfile/attribute/RecordAttribute.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2022, 2024, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2022, 2025, 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
@@ -26,24 +26,32 @@
 package java.lang.classfile.attribute;
 
 import java.lang.classfile.Attribute;
+import java.lang.classfile.AttributeMapper;
+import java.lang.classfile.AttributeMapper.AttributeStability;
+import java.lang.classfile.Attributes;
 import java.lang.classfile.ClassElement;
+import java.lang.classfile.ClassFile;
 import java.util.List;
 
 import jdk.internal.classfile.impl.BoundAttribute;
 import jdk.internal.classfile.impl.UnboundAttribute;
 
 /**
- * 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}.
+ * Models the {@link Attributes#record() Record} attribute (JVMS {@jvms 4.7.30}),
+ * which indicates that this class is a record class and the record
+ * components.
  * <p>
- * The attribute does not permit multiple instances in a given location.
- * Subsequent occurrence of the attribute takes precedence during the attributed
- * element build or transformation.
+ * This attribute only appears on classes, and does not permit {@linkplain
+ * AttributeMapper#allowMultiple multiple instances} in a class.  It has a
+ * data dependency on the {@linkplain AttributeStability#CP_REFS constant pool}.
  * <p>
- * The attribute was introduced in the Java SE Platform version 16.
+ * The attribute was introduced in the Java SE Platform version 16, major
+ * version {@value ClassFile#JAVA_16_VERSION}.
  *
+ * @see Attributes#record()
+ * @see Class#isRecord()
+ * @see Class#getRecordComponents()
+ * @jvms 4.7.30 The {@code Record} Attribute
  * @since 24
  */
 public sealed interface RecordAttribute extends Attribute<RecordAttribute>, ClassElement
@@ -51,11 +59,14 @@ public sealed interface RecordAttribute extends Attribute<RecordAttribute>, Clas
 
     /**
      * {@return the components of this record class}
+     *
+     * @see Class#getRecordComponents()
      */
     List<RecordComponentInfo> components();
 
     /**
      * {@return a {@code Record} attribute}
+     *
      * @param components the record components
      */
     static RecordAttribute of(List<RecordComponentInfo> components) {
@@ -64,6 +75,7 @@ static RecordAttribute of(List<RecordComponentInfo> components) {
 
     /**
      * {@return a {@code Record} attribute}
+     *
      * @param components the record components
      */
     static RecordAttribute of(RecordComponentInfo... components) {
diff --git a/src/java.base/share/classes/java/lang/classfile/attribute/RecordComponentInfo.java b/src/java.base/share/classes/java/lang/classfile/attribute/RecordComponentInfo.java
index 73e4497915e..f3c74f066cf 100644
--- a/src/java.base/share/classes/java/lang/classfile/attribute/RecordComponentInfo.java
+++ b/src/java.base/share/classes/java/lang/classfile/attribute/RecordComponentInfo.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2022, 2024, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2022, 2025, 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
@@ -28,6 +28,7 @@
 import java.lang.classfile.AttributedElement;
 import java.lang.classfile.constantpool.Utf8Entry;
 import java.lang.constant.ClassDesc;
+import java.lang.reflect.RecordComponent;
 import java.util.List;
 
 import jdk.internal.classfile.impl.BoundRecordComponentInfo;
@@ -36,8 +37,17 @@
 import jdk.internal.classfile.impl.Util;
 
 /**
- * Models a single record component in the {@link java.lang.classfile.attribute.RecordAttribute}.
+ * Models a single record component in the {@link RecordAttribute}.
+ * <p>
+ * {@link SignatureAttribute}, {@link RuntimeVisibleAnnotationsAttribute},
+ * {@link RuntimeInvisibleAnnotationsAttribute}, {@link
+ * RuntimeVisibleTypeAnnotationsAttribute}, and {@link
+ * RuntimeInvisibleTypeAnnotationsAttribute} are the only predefined attributes
+ * that may exist on record components.
  *
+ * @see RecordAttribute#components()
+ * @see RecordComponent
+ * @jvms 4.7.30 The {@code Record} Attribute
  * @since 24
  */
 public sealed interface RecordComponentInfo
@@ -45,16 +55,30 @@ public sealed interface RecordComponentInfo
         permits BoundRecordComponentInfo, UnboundAttribute.UnboundRecordComponentInfo {
     /**
      * {@return the name of this component}
+     *
+     * @see RecordComponent#getName()
      */
     Utf8Entry name();
 
     /**
-     * {@return the field descriptor of this component}
+     * {@return the field descriptor string of this component}
+     *
+     * @apiNote
+     * A record component may have a generic type; this information is stored
+     * in the {@link SignatureAttribute Signature} attribute in this component.
+     *
+     * @see RecordComponent#getType()
      */
     Utf8Entry descriptor();
 
     /**
-     * {@return the field descriptor of this component, as a {@linkplain ClassDesc}}
+     * {@return the symbolic field descriptor of this component}
+     *
+     * @apiNote
+     * A record component may have a generic type; this information is stored
+     * in the {@link SignatureAttribute Signature} attribute in this component.
+     *
+     * @see RecordComponent#getType()
      */
     default ClassDesc descriptorSymbol() {
         return Util.fieldTypeSymbol(descriptor());
@@ -62,8 +86,9 @@ default ClassDesc descriptorSymbol() {
 
     /**
      * {@return a record component description}
+     *
      * @param name the component name
-     * @param descriptor the component field descriptor
+     * @param descriptor the component field descriptor string
      * @param attributes the component attributes
      */
     static RecordComponentInfo of(Utf8Entry name,
@@ -74,8 +99,9 @@ static RecordComponentInfo of(Utf8Entry name,
 
     /**
      * {@return a record component description}
+     *
      * @param name the component name
-     * @param descriptor the component field descriptor
+     * @param descriptor the component field descriptor sting
      * @param attributes the component attributes
      */
     static RecordComponentInfo of(Utf8Entry name,
@@ -86,8 +112,9 @@ static RecordComponentInfo of(Utf8Entry name,
 
     /**
      * {@return a record component description}
+     *
      * @param name the component name
-     * @param descriptor the component field descriptor
+     * @param descriptor the component symbolic field descriptor
      * @param attributes the component attributes
      */
     static RecordComponentInfo of(String name,
@@ -100,8 +127,9 @@ static RecordComponentInfo of(String name,
 
     /**
      * {@return a record component description}
+     *
      * @param name the component name
-     * @param descriptor the component field descriptor
+     * @param descriptor the component symbolic field descriptor
      * @param attributes the component attributes
      */
     static RecordComponentInfo of(String name,
diff --git a/src/java.base/share/classes/java/lang/classfile/attribute/RuntimeInvisibleAnnotationsAttribute.java b/src/java.base/share/classes/java/lang/classfile/attribute/RuntimeInvisibleAnnotationsAttribute.java
index 58903859464..da453ad4f5e 100644
--- a/src/java.base/share/classes/java/lang/classfile/attribute/RuntimeInvisibleAnnotationsAttribute.java
+++ b/src/java.base/share/classes/java/lang/classfile/attribute/RuntimeInvisibleAnnotationsAttribute.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2022, 2024, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2022, 2025, 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
@@ -25,30 +25,39 @@
 
 package java.lang.classfile.attribute;
 
-import java.lang.classfile.Annotation;
-import java.lang.classfile.Attribute;
-import java.lang.classfile.ClassElement;
-import java.lang.classfile.FieldElement;
-import java.lang.classfile.MethodElement;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.classfile.*;
+import java.lang.classfile.AttributeMapper.AttributeStability;
+import java.lang.reflect.AnnotatedElement;
 import java.util.List;
 
 import jdk.internal.classfile.impl.BoundAttribute;
 import jdk.internal.classfile.impl.UnboundAttribute;
 
 /**
- * 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.
+ * Models the {@link Attributes#runtimeInvisibleAnnotations()
+ * RuntimeInvisibleAnnotations} attribute (JVMS {@jvms 4.7.17}), which stores
+ * declaration annotations on this structure that are visible to {@code
+ * class} file consumers but are not visible to {@linkplain AnnotatedElement
+ * core reflection}.
  * <p>
- * The attribute does not permit multiple instances in a given location.
- * Subsequent occurrence of the attribute takes precedence during the attributed
- * element build or transformation.
+ * This attribute appears on classes, fields, methods, and record components,
+ * and does not permit {@linkplain AttributeMapper#allowMultiple multiple
+ * instances} in one structure.  It has a data dependency on the {@linkplain
+ * AttributeStability#CP_REFS constant pool}.
  * <p>
- * The attribute was introduced in the Java SE Platform version 5.0.
+ * The attribute was introduced in the Java SE Platform version 5.0, major
+ * version {@value ClassFile#JAVA_5_VERSION}.
  *
+ * @see Attributes#runtimeInvisibleAnnotations()
+ * @see java.compiler/javax.lang.model.element.Element
+ * @see ElementType
+ * @see RetentionPolicy#CLASS
+ * @jvms 4.7.17 The {@code RuntimeInvisibleAnnotations} Attribute
  * @since 24
  */
+@SuppressWarnings("doclint:reference")
 public sealed interface RuntimeInvisibleAnnotationsAttribute
         extends Attribute<RuntimeInvisibleAnnotationsAttribute>,
                 ClassElement, MethodElement, FieldElement
@@ -56,12 +65,13 @@ public sealed interface RuntimeInvisibleAnnotationsAttribute
                 UnboundAttribute.UnboundRuntimeInvisibleAnnotationsAttribute {
 
     /**
-     * {@return the non-runtime-visible annotations on this class, field, or method}
+     * {@return the run-time invisible declaration annotations on this structure}
      */
     List<Annotation> annotations();
 
     /**
      * {@return a {@code RuntimeInvisibleAnnotations} attribute}
+     *
      * @param annotations the annotations
      */
     static RuntimeInvisibleAnnotationsAttribute of(List<Annotation> annotations) {
@@ -70,6 +80,7 @@ static RuntimeInvisibleAnnotationsAttribute of(List<Annotation> annotations) {
 
     /**
      * {@return a {@code RuntimeInvisibleAnnotations} attribute}
+     *
      * @param annotations the annotations
      */
     static RuntimeInvisibleAnnotationsAttribute of(Annotation... annotations) {
diff --git a/src/java.base/share/classes/java/lang/classfile/attribute/RuntimeInvisibleParameterAnnotationsAttribute.java b/src/java.base/share/classes/java/lang/classfile/attribute/RuntimeInvisibleParameterAnnotationsAttribute.java
index f1c02b77e1e..2051cd5dcdf 100644
--- a/src/java.base/share/classes/java/lang/classfile/attribute/RuntimeInvisibleParameterAnnotationsAttribute.java
+++ b/src/java.base/share/classes/java/lang/classfile/attribute/RuntimeInvisibleParameterAnnotationsAttribute.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2022, 2024, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2022, 2025, 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
@@ -25,26 +25,39 @@
 
 package java.lang.classfile.attribute;
 
+import java.lang.annotation.ElementType;
+import java.lang.annotation.RetentionPolicy;
 import java.lang.classfile.Annotation;
 import java.lang.classfile.Attribute;
+import java.lang.classfile.AttributeMapper;
+import java.lang.classfile.AttributeMapper.AttributeStability;
+import java.lang.classfile.Attributes;
+import java.lang.classfile.ClassFile;
 import java.lang.classfile.MethodElement;
-import java.lang.classfile.MethodModel;
+import java.lang.reflect.AnnotatedElement;
 import java.util.List;
 
 import jdk.internal.classfile.impl.BoundAttribute;
 import jdk.internal.classfile.impl.UnboundAttribute;
 
 /**
- * Models the {@code RuntimeInvisibleParameterAnnotations} attribute
- * (JVMS {@jvms 4.7.19}), which can appear on methods. Delivered as a {@link
- * java.lang.classfile.MethodElement} when traversing a {@link MethodModel}.
+ * Models the {@link Attributes#runtimeInvisibleParameterAnnotations()
+ * RuntimeInvisibleParameterAnnotations} attribute (JVMS {@jvms 4.7.19}), which
+ * stores declaration annotations on the method parameters of this method
+ * that are visible to {@code class} file consumers but are not visible to
+ * {@linkplain AnnotatedElement core reflection}.
  * <p>
- * The attribute does not permit multiple instances in a given location.
- * Subsequent occurrence of the attribute takes precedence during the attributed
- * element build or transformation.
+ * This attribute only appears on methods, and does not permit {@linkplain
+ * AttributeMapper#allowMultiple multiple instances} in a method.  It has a
+ * data dependency on the {@linkplain AttributeStability#CP_REFS constant pool}.
  * <p>
- * The attribute was introduced in the Java SE Platform version 5.0.
+ * The attribute was introduced in the Java SE Platform version 5.0, major
+ * version {@value ClassFile#JAVA_5_VERSION}.
  *
+ * @see Attributes#runtimeInvisibleParameterAnnotations()
+ * @see ElementType#PARAMETER
+ * @see RetentionPolicy#CLASS
+ * @jvms 4.7.19 The {@code RuntimeInvisibleParameterAnnotations} Attribute
  * @since 24
  */
 public sealed interface RuntimeInvisibleParameterAnnotationsAttribute
@@ -53,15 +66,26 @@ public sealed interface RuntimeInvisibleParameterAnnotationsAttribute
                 UnboundAttribute.UnboundRuntimeInvisibleParameterAnnotationsAttribute {
 
     /**
-     * {@return the list of annotations corresponding to each method parameter}
+     * {@return the list of run-time invisible annotations on the method parameters}
      * The element at the i'th index corresponds to the annotations on the i'th
-     * parameter.
+     * formal parameter, but note that some synthetic or implicit parameters
+     * may be omitted by this list.  If a parameter has no annotations, that
+     * element is left empty, but is not omitted; thus, the list will never be
+     * truncated because trailing parameters are not annotated.
+     *
+     * @see java.lang.reflect##LanguageJvmModel Java programming language and
+     *      JVM modeling in core reflection
      */
     List<List<Annotation>> parameterAnnotations();
 
     /**
      * {@return a {@code RuntimeInvisibleParameterAnnotations} attribute}
-     * @param parameterAnnotations a list of parameter annotations for each parameter
+     * The {@code parameterAnnotations} list should not be truncated, and must
+     * have a length equal to the number of formal parameters; elements for
+     * unannotated parameters may be empty, but may not be omitted.  It may omit
+     * some synthetic or implicit parameters.
+     *
+     * @param parameterAnnotations a list of run-time invisible annotations for each parameter
      */
     static RuntimeInvisibleParameterAnnotationsAttribute of(List<List<Annotation>> parameterAnnotations) {
         return new UnboundAttribute.UnboundRuntimeInvisibleParameterAnnotationsAttribute(parameterAnnotations);
diff --git a/src/java.base/share/classes/java/lang/classfile/attribute/RuntimeInvisibleTypeAnnotationsAttribute.java b/src/java.base/share/classes/java/lang/classfile/attribute/RuntimeInvisibleTypeAnnotationsAttribute.java
index 7500d39fc19..3ff1a643a82 100644
--- a/src/java.base/share/classes/java/lang/classfile/attribute/RuntimeInvisibleTypeAnnotationsAttribute.java
+++ b/src/java.base/share/classes/java/lang/classfile/attribute/RuntimeInvisibleTypeAnnotationsAttribute.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2022, 2024, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2022, 2025, 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
@@ -25,32 +25,44 @@
 
 package java.lang.classfile.attribute;
 
-import java.lang.classfile.Attribute;
-import java.lang.classfile.ClassElement;
-import java.lang.classfile.CodeElement;
-import java.lang.classfile.FieldElement;
-import java.lang.classfile.MethodElement;
-import java.lang.classfile.TypeAnnotation;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.classfile.*;
+import java.lang.classfile.AttributeMapper.AttributeStability;
+import java.lang.reflect.AnnotatedType;
 import java.util.List;
 
 import jdk.internal.classfile.impl.BoundAttribute;
 import jdk.internal.classfile.impl.UnboundAttribute;
 
 /**
- * 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
- * the corresponding model type.
+ * Models the {@link Attributes#runtimeInvisibleTypeAnnotations()
+ * RuntimeInvisibleTypeAnnotations} attribute (JVMS {@jvms 4.7.21}), which
+ * stores type-use annotations for the annotated uses of types in this
+ * structure that are visible to {@code class} file consumers but are not
+ * visible to {@linkplain AnnotatedType core reflection}.  Its delivery in the
+ * traversal of a {@link CodeModel} may be toggled by {@link
+ * ClassFile.DebugElementsOption}.
  * <p>
- * The attribute does not permit multiple instances in a given location.
- * Subsequent occurrence of the attribute takes precedence during the attributed
- * element build or transformation.
+ * This attribute appears on classes, fields, methods, {@code Code} attributes,
+ * and record components, and does not permit {@linkplain
+ * AttributeMapper#allowMultiple multiple instances} in one structure.  It has a
+ * data dependency on {@linkplain AttributeStability#UNSTABLE arbitrary indices}
+ * in the {@code class} file format, so users must take great care to ensure
+ * this attribute is still correct after a {@code class} file has been transformed.
  * <p>
- * The attribute was introduced in the Java SE Platform version 8.
+ * The attribute was introduced in the Java SE Platform version 8, major version
+ * {@value ClassFile#JAVA_8_VERSION}.
  *
+ * @see Attributes#runtimeInvisibleTypeAnnotations()
+ * @see java.compiler/javax.lang.model.type.TypeMirror
+ * @see ElementType#TYPE_PARAMETER
+ * @see ElementType#TYPE_USE
+ * @see RetentionPolicy#CLASS
+ * @jvms 4.7.21 The {@code RuntimeInvisibleTypeAnnotations} Attribute
  * @since 24
  */
+@SuppressWarnings("doclint:reference")
 public sealed interface RuntimeInvisibleTypeAnnotationsAttribute
         extends Attribute<RuntimeInvisibleTypeAnnotationsAttribute>,
                 ClassElement, MethodElement, FieldElement, CodeElement
@@ -58,12 +70,14 @@ public sealed interface RuntimeInvisibleTypeAnnotationsAttribute
                 UnboundAttribute.UnboundRuntimeInvisibleTypeAnnotationsAttribute {
 
     /**
-     * {@return the non-runtime-visible type annotations on parts of this class, field, or method}
+     * {@return the run-time invisible annotations on uses of types in this
+     * structure}
      */
     List<TypeAnnotation> annotations();
 
     /**
      * {@return a {@code RuntimeInvisibleTypeAnnotations} attribute}
+     *
      * @param annotations the annotations
      */
     static RuntimeInvisibleTypeAnnotationsAttribute of(List<TypeAnnotation> annotations) {
@@ -72,6 +86,7 @@ static RuntimeInvisibleTypeAnnotationsAttribute of(List<TypeAnnotation> annotati
 
     /**
      * {@return a {@code RuntimeInvisibleTypeAnnotations} attribute}
+     *
      * @param annotations the annotations
      */
     static RuntimeInvisibleTypeAnnotationsAttribute of(TypeAnnotation... annotations) {
diff --git a/src/java.base/share/classes/java/lang/classfile/attribute/RuntimeVisibleAnnotationsAttribute.java b/src/java.base/share/classes/java/lang/classfile/attribute/RuntimeVisibleAnnotationsAttribute.java
index d41fcf3794b..ceabe2131af 100644
--- a/src/java.base/share/classes/java/lang/classfile/attribute/RuntimeVisibleAnnotationsAttribute.java
+++ b/src/java.base/share/classes/java/lang/classfile/attribute/RuntimeVisibleAnnotationsAttribute.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2022, 2024, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2022, 2025, 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
@@ -25,30 +25,39 @@
 
 package java.lang.classfile.attribute;
 
-import java.lang.classfile.Annotation;
-import java.lang.classfile.Attribute;
-import java.lang.classfile.ClassElement;
-import java.lang.classfile.FieldElement;
-import java.lang.classfile.MethodElement;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.classfile.*;
+import java.lang.classfile.AttributeMapper.AttributeStability;
+import java.lang.reflect.AnnotatedElement;
 import java.util.List;
 
 import jdk.internal.classfile.impl.BoundAttribute;
 import jdk.internal.classfile.impl.UnboundAttribute;
 
 /**
- * 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.
+ * Models the {@link Attributes#runtimeVisibleAnnotations()
+ * RuntimeVisibleAnnotations} attribute (JVMS {@jvms 4.7.16}), which stores
+ * declaration annotations on this structure that are visible to both
+ * {@code class} file consumers and {@linkplain AnnotatedElement core reflection}.
  * <p>
- * The attribute does not permit multiple instances in a given location.
- * Subsequent occurrence of the attribute takes precedence during the attributed
- * element build or transformation.
+ * This attribute appears on classes, fields, methods, and record components,
+ * and does not permit {@linkplain AttributeMapper#allowMultiple multiple
+ * instances} in one structure.  It has a data dependency on the {@linkplain
+ * AttributeStability#CP_REFS constant pool}.
  * <p>
- * The attribute was introduced in the Java SE Platform version 5.0.
+ * The attribute was introduced in the Java SE Platform version 5.0, major
+ * version {@value ClassFile#JAVA_5_VERSION}.
  *
+ * @see Attributes#runtimeVisibleAnnotations()
+ * @see java.compiler/javax.lang.model.element.Element
+ * @see AnnotatedElement
+ * @see ElementType
+ * @see RetentionPolicy#RUNTIME
+ * @jvms 4.7.16 The {@code RuntimeVisibleAnnotations} Attribute
  * @since 24
  */
+@SuppressWarnings("doclint:reference")
 public sealed interface RuntimeVisibleAnnotationsAttribute
         extends Attribute<RuntimeVisibleAnnotationsAttribute>,
                 ClassElement, MethodElement, FieldElement
@@ -56,7 +65,7 @@ public sealed interface RuntimeVisibleAnnotationsAttribute
                 UnboundAttribute.UnboundRuntimeVisibleAnnotationsAttribute {
 
     /**
-     * {@return the runtime-visible annotations on this class, field, or method}
+     * {@return the run-time visible declaration annotations on this structure}
      */
     List<Annotation> annotations();
 
diff --git a/src/java.base/share/classes/java/lang/classfile/attribute/RuntimeVisibleParameterAnnotationsAttribute.java b/src/java.base/share/classes/java/lang/classfile/attribute/RuntimeVisibleParameterAnnotationsAttribute.java
index 5ed9817eeb9..2cf462d246c 100644
--- a/src/java.base/share/classes/java/lang/classfile/attribute/RuntimeVisibleParameterAnnotationsAttribute.java
+++ b/src/java.base/share/classes/java/lang/classfile/attribute/RuntimeVisibleParameterAnnotationsAttribute.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2022, 2024, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2022, 2025, 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
@@ -25,26 +25,41 @@
 
 package java.lang.classfile.attribute;
 
+import java.lang.annotation.ElementType;
+import java.lang.annotation.RetentionPolicy;
 import java.lang.classfile.Annotation;
 import java.lang.classfile.Attribute;
+import java.lang.classfile.AttributeMapper;
+import java.lang.classfile.AttributeMapper.AttributeStability;
+import java.lang.classfile.Attributes;
+import java.lang.classfile.ClassFile;
 import java.lang.classfile.MethodElement;
-import java.lang.classfile.MethodModel;
+import java.lang.reflect.AnnotatedElement;
+import java.lang.reflect.Executable;
 import java.util.List;
 
 import jdk.internal.classfile.impl.BoundAttribute;
 import jdk.internal.classfile.impl.UnboundAttribute;
 
 /**
- * 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}.
- *
- * @apiNote The attribute does not permit multiple instances in a given location.
- * Subsequent occurrence of the attribute takes precedence during the attributed
- * element build or transformation.
+ * Models the {@link Attributes#runtimeVisibleParameterAnnotations()
+ * RuntimeVisibleParameterAnnotations} attribute (JVMS {@jvms 4.7.18}), which
+ * stores declaration annotations on the method parameters of this method
+ * that are visible to both {@code class} file consumers and {@linkplain
+ * AnnotatedElement core reflection}.
+ * <p>
+ * This attribute only appears on methods, and does not permit {@linkplain
+ * AttributeMapper#allowMultiple multiple instances} in a method.  It has a
+ * data dependency on the {@linkplain AttributeStability#CP_REFS constant pool}.
  * <p>
- * The attribute was introduced in the Java SE Platform version 5.0.
+ * The attribute was introduced in the Java SE Platform version 5.0, major
+ * version {@value ClassFile#JAVA_5_VERSION}.
  *
+ * @see Attributes#runtimeVisibleParameterAnnotations()
+ * @see Executable#getParameterAnnotations()
+ * @see ElementType#PARAMETER
+ * @see RetentionPolicy#RUNTIME
+ * @jvms 4.7.18 The {@code RuntimeVisibleParameterAnnotations} Attribute
  * @since 24
  */
 public sealed interface RuntimeVisibleParameterAnnotationsAttribute
@@ -53,15 +68,26 @@ public sealed interface RuntimeVisibleParameterAnnotationsAttribute
                 UnboundAttribute.UnboundRuntimeVisibleParameterAnnotationsAttribute {
 
     /**
-     * {@return the list of annotations corresponding to each method parameter}
+     * {@return the list of run-time visible annotations on the method parameters}
      * The element at the i'th index corresponds to the annotations on the i'th
-     * parameter.
+     * formal parameter, but note that some synthetic or implicit parameters
+     * may be omitted by this list.  If a parameter has no annotations, that
+     * element is left empty, but is not omitted; thus, the list will never be
+     * truncated because trailing parameters are not annotated.
+     *
+     * @see java.lang.reflect##LanguageJvmModel Java programming language and
+     *      JVM modeling in core reflection
      */
     List<List<Annotation>> parameterAnnotations();
 
     /**
      * {@return a {@code RuntimeVisibleParameterAnnotations} attribute}
-     * @param parameterAnnotations a list of parameter annotations for each parameter
+     * The {@code parameterAnnotations} list should not be truncated, and must
+     * have a length equal to the number of formal parameters; elements for
+     * unannotated parameters may be empty, but may not be omitted.  It may omit
+     * some synthetic or implicit parameters.
+     *
+     * @param parameterAnnotations a list of run-time visible annotations for each parameter
      */
     static RuntimeVisibleParameterAnnotationsAttribute of(List<List<Annotation>> parameterAnnotations) {
         return new UnboundAttribute.UnboundRuntimeVisibleParameterAnnotationsAttribute(parameterAnnotations);
diff --git a/src/java.base/share/classes/java/lang/classfile/attribute/RuntimeVisibleTypeAnnotationsAttribute.java b/src/java.base/share/classes/java/lang/classfile/attribute/RuntimeVisibleTypeAnnotationsAttribute.java
index a4e780c4536..ad4595ffb6b 100644
--- a/src/java.base/share/classes/java/lang/classfile/attribute/RuntimeVisibleTypeAnnotationsAttribute.java
+++ b/src/java.base/share/classes/java/lang/classfile/attribute/RuntimeVisibleTypeAnnotationsAttribute.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2022, 2024, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2022, 2025, 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
@@ -25,32 +25,44 @@
 
 package java.lang.classfile.attribute;
 
-import java.lang.classfile.Attribute;
-import java.lang.classfile.ClassElement;
-import java.lang.classfile.CodeElement;
-import java.lang.classfile.FieldElement;
-import java.lang.classfile.MethodElement;
-import java.lang.classfile.TypeAnnotation;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.classfile.*;
+import java.lang.classfile.AttributeMapper.AttributeStability;
+import java.lang.reflect.AnnotatedType;
 import java.util.List;
 
 import jdk.internal.classfile.impl.BoundAttribute;
 import jdk.internal.classfile.impl.UnboundAttribute;
 
 /**
- * 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
- * the corresponding model type.
+ * Models the {@link Attributes#runtimeVisibleTypeAnnotations()
+ * RuntimeVisibleTypeAnnotations} attribute (JVMS {@jvms 4.7.20}), which
+ * stores type-use annotations for the annotated uses of types in this
+ * structure that are visible to both {@code class} file consumers and
+ * {@linkplain AnnotatedType core reflection}.  Its delivery in the traversal of
+ * a {@link CodeModel} may be toggled by {@link ClassFile.DebugElementsOption}.
  * <p>
- * The attribute does not permit multiple instances in a given location.
- * Subsequent occurrence of the attribute takes precedence during the attributed
- * element build or transformation.
+ * This attribute appears on classes, fields, methods, {@code Code} attributes,
+ * and record components, and does not permit {@linkplain
+ * AttributeMapper#allowMultiple multiple instances} in one structure.  It has a
+ * data dependency on {@linkplain AttributeStability#UNSTABLE arbitrary indices}
+ * in the {@code class} file format, so users must take great care to ensure
+ * this attribute is still correct after a {@code class} file has been transformed.
  * <p>
- * The attribute was introduced in the Java SE Platform version 8.
+ * The attribute was introduced in the Java SE Platform version 8, major version
+ * {@value ClassFile#JAVA_8_VERSION}.
  *
+ * @see Attributes#runtimeVisibleTypeAnnotations()
+ * @see java.compiler/javax.lang.model.type.TypeMirror
+ * @see AnnotatedType
+ * @see ElementType#TYPE_PARAMETER
+ * @see ElementType#TYPE_USE
+ * @see RetentionPolicy#RUNTIME
+ * @jvms 4.7.20 the {@code RuntimeVisibleTypeAnnotations} Attribute
  * @since 24
  */
+@SuppressWarnings("doclint:reference")
 public sealed interface RuntimeVisibleTypeAnnotationsAttribute
         extends Attribute<RuntimeVisibleTypeAnnotationsAttribute>,
                 ClassElement, MethodElement, FieldElement, CodeElement
@@ -58,12 +70,14 @@ public sealed interface RuntimeVisibleTypeAnnotationsAttribute
                 UnboundAttribute.UnboundRuntimeVisibleTypeAnnotationsAttribute {
 
     /**
-     * {@return the runtime-visible type annotations on parts of this class, field, or method}
+     * {@return the run-time visible annotations on uses of types in this
+     * structure}
      */
     List<TypeAnnotation> annotations();
 
     /**
      * {@return a {@code RuntimeVisibleTypeAnnotations} attribute}
+     *
      * @param annotations the annotations
      */
     static RuntimeVisibleTypeAnnotationsAttribute of(List<TypeAnnotation> annotations) {
@@ -72,6 +86,7 @@ static RuntimeVisibleTypeAnnotationsAttribute of(List<TypeAnnotation> annotation
 
     /**
      * {@return a {@code RuntimeVisibleTypeAnnotations} attribute}
+     *
      * @param annotations the annotations
      */
     static RuntimeVisibleTypeAnnotationsAttribute of(TypeAnnotation... annotations) {
diff --git a/src/java.base/share/classes/java/lang/classfile/attribute/SignatureAttribute.java b/src/java.base/share/classes/java/lang/classfile/attribute/SignatureAttribute.java
index 8f06e16a1b1..2be07e38a58 100644
--- a/src/java.base/share/classes/java/lang/classfile/attribute/SignatureAttribute.java
+++ b/src/java.base/share/classes/java/lang/classfile/attribute/SignatureAttribute.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2022, 2024, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2022, 2025, 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
@@ -27,24 +27,29 @@
 
 import java.lang.classfile.*;
 import java.lang.classfile.constantpool.Utf8Entry;
+import java.lang.reflect.Field;
+import java.lang.reflect.RecordComponent;
 
 import jdk.internal.classfile.impl.BoundAttribute;
 import jdk.internal.classfile.impl.TemporaryConstantPool;
 import jdk.internal.classfile.impl.UnboundAttribute;
 
 /**
- * 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
- * the corresponding model type.
+ * Models the {@link Attributes#signature() Signature} attribute (JVMS {@jvms
+ * 4.7.9}), which indicates the generic signature of this structure.
  * <p>
- * The attribute does not permit multiple instances in a given location.
- * Subsequent occurrence of the attribute takes precedence during the attributed
- * element build or transformation.
+ * This attribute appears on classes, fields, methods, and record components,
+ * and does not permit {@linkplain AttributeMapper#allowMultiple multiple
+ * instances} in one structure.  It has a data dependency on the {@linkplain
+ * AttributeMapper.AttributeStability#CP_REFS constant pool}.
  * <p>
- * The attribute was introduced in the Java SE Platform version 5.0.
+ * The attribute was introduced in the Java SE Platform version 5.0, major
+ * version {@value ClassFile#JAVA_5_VERSION}.
  *
+ * @see Signature
+ * @see ClassSignature
+ * @see MethodSignature
+ * @jvms 4.7.9 The {@code Signature} Attribute
  * @since 24
  */
 public sealed interface SignatureAttribute
@@ -53,29 +58,46 @@ public sealed interface SignatureAttribute
         permits BoundAttribute.BoundSignatureAttribute, UnboundAttribute.UnboundSignatureAttribute {
 
     /**
-     * {@return the signature for the class, method, or field}
+     * {@return the signature string for the class, method, field, or record
+     * component}  It is a class signature string if this attribute is on a
+     * class, a method signature string if this attribute is on a method, or
+     * a field signature string if this attribute is on a field or a record
+     * component.
+     *
+     * @jvms 4.7.9.1 Signatures
      */
     Utf8Entry signature();
 
     /**
-     * Parse the signature as a class signature.
+     * Parses the signature string as a class signature.
+     *
      * @return the class signature
+     * @throws IllegalArgumentException if the signature string is not a valid
+     *         class signature string
      */
     default ClassSignature asClassSignature() {
         return ClassSignature.parseFrom(signature().stringValue());
     }
 
     /**
-     * Parse the signature as a method signature.
+     * Parse the signature string as a method signature.
+     *
      * @return the method signature
+     * @throws IllegalArgumentException if the signature string is not a valid
+     *         method signature string
      */
     default MethodSignature asMethodSignature() {
         return MethodSignature.parseFrom(signature().stringValue());
     }
 
     /**
-     * Parse the signature as a type signature.
+     * Parses the signature string as a Java type signature.
+     *
      * @return the type signature
+     * @throws IllegalArgumentException if the signature string is not a valid
+     *         Java type signature string
+     * @see Field#getGenericType()
+     * @see RecordComponent#getGenericType()
      */
     default Signature asTypeSignature() {
         return Signature.parseFrom(signature().stringValue());
@@ -83,7 +105,8 @@ default Signature asTypeSignature() {
 
     /**
      * {@return a {@code Signature} attribute for a class}
-     * @param classSignature the signature
+     *
+     * @param classSignature the class signature
      */
     static SignatureAttribute of(ClassSignature classSignature) {
         return of(TemporaryConstantPool.INSTANCE.utf8Entry(classSignature.signatureString()));
@@ -91,15 +114,17 @@ static SignatureAttribute of(ClassSignature classSignature) {
 
     /**
      * {@return a {@code Signature} attribute for a method}
-     * @param methodSignature the signature
+     *
+     * @param methodSignature the method signature
      */
     static SignatureAttribute of(MethodSignature methodSignature) {
         return of(TemporaryConstantPool.INSTANCE.utf8Entry(methodSignature.signatureString()));
     }
 
     /**
-     * {@return a {@code Signature} attribute}
-     * @param signature the signature
+     * {@return a {@code Signature} attribute for a field or a record component}
+     *
+     * @param signature the Java type signature
      */
     static SignatureAttribute of(Signature signature) {
         return of(TemporaryConstantPool.INSTANCE.utf8Entry(signature.signatureString()));
@@ -107,7 +132,8 @@ static SignatureAttribute of(Signature signature) {
 
     /**
      * {@return a {@code Signature} attribute}
-     * @param signature the signature
+     *
+     * @param signature the signature string
      */
     static SignatureAttribute of(Utf8Entry signature) {
         return new UnboundAttribute.UnboundSignatureAttribute(signature);
diff --git a/src/java.base/share/classes/java/lang/classfile/attribute/SourceDebugExtensionAttribute.java b/src/java.base/share/classes/java/lang/classfile/attribute/SourceDebugExtensionAttribute.java
index 0e6b7267263..9634ebe3011 100644
--- a/src/java.base/share/classes/java/lang/classfile/attribute/SourceDebugExtensionAttribute.java
+++ b/src/java.base/share/classes/java/lang/classfile/attribute/SourceDebugExtensionAttribute.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2022, 2024, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2022, 2025, 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
@@ -25,23 +25,31 @@
 
 package java.lang.classfile.attribute;
 
+import java.io.DataInput;
 import java.lang.classfile.Attribute;
+import java.lang.classfile.AttributeMapper;
+import java.lang.classfile.AttributeMapper.AttributeStability;
+import java.lang.classfile.Attributes;
 import java.lang.classfile.ClassElement;
+import java.lang.classfile.ClassFile;
 
 import jdk.internal.classfile.impl.BoundAttribute;
 import jdk.internal.classfile.impl.UnboundAttribute;
 
 /**
- * Models the {@code SourceDebugExtension} attribute.
- * Delivered as a {@link java.lang.classfile.ClassElement} when traversing the elements of
- * a {@link java.lang.classfile.ClassModel}.
+ * Models the {@link Attributes#sourceDebugExtension() SourceDebugExtension}
+ * attribute (JVMS {@jvms 4.7.11}), which stores arbitrary {@linkplain
+ * DataInput##modified-utf-8 modified UTF-8} data.
  * <p>
- * The attribute does not permit multiple instances in a given location.
- * Subsequent occurrence of the attribute takes precedence during the attributed
- * element build or transformation.
+ * This attribute only appears on classes, and does not permit {@linkplain
+ * AttributeMapper#allowMultiple multiple instances} in a class.  It has
+ * {@linkplain AttributeStability#STATELESS no data dependency}.
  * <p>
- * The attribute was introduced in the Java SE Platform version 5.0.
+ * The attribute was introduced in the Java SE Platform version 5.0, major
+ * version {@value ClassFile#JAVA_5_VERSION}.
  *
+ * @see Attributes#sourceDebugExtension()
+ * @jvms 4.7.11 The {@code SourceDebugExtension} Attribute
  * @since 24
  */
 public sealed interface SourceDebugExtensionAttribute
@@ -49,7 +57,8 @@ public sealed interface SourceDebugExtensionAttribute
         permits BoundAttribute.BoundSourceDebugExtensionAttribute, UnboundAttribute.UnboundSourceDebugExtensionAttribute {
 
     /**
-     * {@return the debug extension payload}
+     * {@return the debug extension payload}  The payload may denote a string
+     * longer than that which can be represented with a {@link String}.
      */
     byte[] contents();
 
diff --git a/src/java.base/share/classes/java/lang/classfile/attribute/SourceFileAttribute.java b/src/java.base/share/classes/java/lang/classfile/attribute/SourceFileAttribute.java
index 70f3d1e72ce..e2621d241fb 100644
--- a/src/java.base/share/classes/java/lang/classfile/attribute/SourceFileAttribute.java
+++ b/src/java.base/share/classes/java/lang/classfile/attribute/SourceFileAttribute.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2022, 2024, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2022, 2025, 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
@@ -26,8 +26,11 @@
 package java.lang.classfile.attribute;
 
 import java.lang.classfile.Attribute;
+import java.lang.classfile.AttributeMapper;
+import java.lang.classfile.AttributeMapper.AttributeStability;
+import java.lang.classfile.Attributes;
 import java.lang.classfile.ClassElement;
-import java.lang.classfile.ClassModel;
+import java.lang.classfile.ClassFile;
 import java.lang.classfile.constantpool.Utf8Entry;
 
 import jdk.internal.classfile.impl.BoundAttribute;
@@ -35,14 +38,19 @@
 import jdk.internal.classfile.impl.UnboundAttribute;
 
 /**
- * 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}.
+ * Models the {@link Attributes#sourceFile() SourceFile} attribute (JVMS {@jvms
+ * 4.7.10}), which indicates the name of the source file from which this {@code
+ * class} file was compiled.
  * <p>
- * The attribute does not permit multiple instances in a given location.
- * Subsequent occurrence of the attribute takes precedence during the attributed
- * element build or transformation.
+ * This attribute only appears on classes, and does not permit {@linkplain
+ * AttributeMapper#allowMultiple multiple instances} in a class.  It has a data
+ * dependency on the {@linkplain AttributeStability#CP_REFS constant pool}.
+ * <p>
+ * The attribute was introduced in the Java SE Platform version 5.0, major
+ * version {@value ClassFile#JAVA_5_VERSION}.
  *
+ * @see Attributes#sourceFile()
+ * @jvms 4.7.10 The {@code SourceFile} Attribute
  * @since 24
  */
 public sealed interface SourceFileAttribute
@@ -56,6 +64,7 @@ public sealed interface SourceFileAttribute
 
     /**
      * {@return a source file attribute}
+     *
      * @param sourceFile the source file name
      */
     static SourceFileAttribute of(String sourceFile) {
@@ -64,6 +73,7 @@ static SourceFileAttribute of(String sourceFile) {
 
     /**
      * {@return a source file attribute}
+     *
      * @param sourceFile the source file name
      */
     static SourceFileAttribute of(Utf8Entry sourceFile) {
diff --git a/src/java.base/share/classes/java/lang/classfile/attribute/SourceIDAttribute.java b/src/java.base/share/classes/java/lang/classfile/attribute/SourceIDAttribute.java
index 71fd9d5b059..b7d2e3cf9b7 100644
--- a/src/java.base/share/classes/java/lang/classfile/attribute/SourceIDAttribute.java
+++ b/src/java.base/share/classes/java/lang/classfile/attribute/SourceIDAttribute.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2022, 2024, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2022, 2025, 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
@@ -26,8 +26,10 @@
 package java.lang.classfile.attribute;
 
 import java.lang.classfile.Attribute;
+import java.lang.classfile.AttributeMapper;
+import java.lang.classfile.AttributeMapper.AttributeStability;
+import java.lang.classfile.Attributes;
 import java.lang.classfile.ClassElement;
-import java.lang.classfile.ClassModel;
 import java.lang.classfile.constantpool.Utf8Entry;
 
 import jdk.internal.classfile.impl.BoundAttribute;
@@ -35,14 +37,21 @@
 import jdk.internal.classfile.impl.UnboundAttribute;
 
 /**
- * Models the {@code SourceID} attribute, which can
- * appear on classes. Delivered as a {@link java.lang.classfile.ClassElement} when
- * traversing a {@link ClassModel}.
+ * Models the {@link Attributes#sourceId() SourceID} attribute, which records
+ * the last modified time of the source file from which this {@code class} file
+ * was compiled.
  * <p>
- * The attribute does not permit multiple instances in a given location.
- * Subsequent occurrence of the attribute takes precedence during the attributed
- * element build or transformation.
+ * This attribute only appears on classes, and does not permit {@linkplain
+ * AttributeMapper#allowMultiple multiple instances} in a class.  It has a
+ * data dependency on the {@linkplain AttributeStability#CP_REFS constant pool}.
+ * <p>
+ * This attribute is not predefined in the Java SE Platform.  This is a
+ * JDK-specific nonstandard attribute produced by the reference implementation
+ * of the system Java compiler, defined by the {@code jdk.compiler} module.
  *
+ * @see Attributes#sourceId()
+ * @see CompilationIDAttribute
+ * @see CharacterRangeTableAttribute
  * @since 24
  */
 public sealed interface SourceIDAttribute
@@ -51,13 +60,14 @@ public sealed interface SourceIDAttribute
 
     /**
      * {@return the source id}  The source id is the last modified time of the
-     * source file (as reported by the filesystem, in milliseconds) when the
-     * classfile is compiled.
+     * source file (as reported by the file system, in milliseconds) when this
+     * {@code class} file is compiled.
      */
     Utf8Entry sourceId();
 
     /**
      * {@return a {@code SourceID} attribute}
+     *
      * @param sourceId the source id
      */
     static SourceIDAttribute of(Utf8Entry sourceId) {
@@ -66,6 +76,7 @@ static SourceIDAttribute of(Utf8Entry sourceId) {
 
     /**
      * {@return a {@code SourceID} attribute}
+     *
      * @param sourceId the source id
      */
     static SourceIDAttribute of(String sourceId) {
diff --git a/src/java.base/share/classes/java/lang/classfile/attribute/StackMapFrameInfo.java b/src/java.base/share/classes/java/lang/classfile/attribute/StackMapFrameInfo.java
index 920db8ac9d7..71d5ccc79a4 100644
--- a/src/java.base/share/classes/java/lang/classfile/attribute/StackMapFrameInfo.java
+++ b/src/java.base/share/classes/java/lang/classfile/attribute/StackMapFrameInfo.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2023, 2024, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2023, 2025, 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
@@ -25,8 +25,11 @@
 
 package java.lang.classfile.attribute;
 
+import java.lang.classfile.ClassFile;
 import java.lang.classfile.Label;
+import java.lang.classfile.Opcode;
 import java.lang.classfile.constantpool.ClassEntry;
+import java.lang.classfile.instruction.BranchInstruction;
 import java.lang.constant.ClassDesc;
 import java.util.List;
 
@@ -34,15 +37,28 @@
 import jdk.internal.classfile.impl.TemporaryConstantPool;
 
 /**
- * Models stack map frame of {@code StackMapTable} attribute (JVMS {@jvms 4.7.4}).
+ * Models a stack map frame in a {@link StackMapTableAttribute StackMapTable}
+ * attribute (JVMS {@jvms 4.7.4}).  A stack map frame must appear at the
+ * beginning of each basic block in a method (JVMS {@jvms 4.10.1}).
  *
+ * @apiNote
+ * In general, a stack map frame should be defined for each target of a
+ * {@link BranchInstruction}, or unreachable code right after an unconditional
+ * branch instruction like {@link Opcode#GOTO goto}.  The automatic stack map
+ * generation cannot handle unreachable code right after an unconditional jump;
+ * The {@link ClassFile.DeadCodeOption} allows substituting such code, or
+ * advanced users can provide their own stack maps for dead code.
+ *
+ * @see StackMapTableAttribute#entries()
+ * @jvms 4.7.4 The {@code StackMapTable} Attribute
+ * @jvms 4.10.1 Verification by Type Checking
  * @since 24
  */
 public sealed interface StackMapFrameInfo
             permits StackMapDecoder.StackMapFrameImpl {
 
     /**
-     * {@return the frame compact form type}
+     * {@return the raw {@code u1 frame_type}}
      */
     int frameType();
 
@@ -57,12 +73,13 @@ public sealed interface StackMapFrameInfo
     List<VerificationTypeInfo> locals();
 
     /**
-     * {@return the expanded stack types}
+     * {@return the expanded operand stack types}
      */
     List<VerificationTypeInfo> stack();
 
     /**
      * {@return a new stack map frame}
+     *
      * @param target the location of the frame
      * @param locals the complete list of frame locals
      * @param stack the complete frame stack
@@ -70,13 +87,15 @@ public sealed interface StackMapFrameInfo
     public static StackMapFrameInfo of(Label target,
             List<VerificationTypeInfo> locals,
             List<VerificationTypeInfo> stack) {
-
         return new StackMapDecoder.StackMapFrameImpl(255, target, locals, stack);
     }
 
     /**
-     * The type of a stack value.
+     * The type of a stack or local variable value.
      *
+     * @see #locals()
+     * @see #stack()
+     * @jvms 4.7.4 The {@code StackMapTable} Attribute
      * @since 24
      */
     sealed interface VerificationTypeInfo {
@@ -125,25 +144,25 @@ sealed interface VerificationTypeInfo {
      */
     public enum SimpleVerificationTypeInfo implements VerificationTypeInfo {
 
-        /** verification type top */
+        /** Verification type top. */
         TOP(ITEM_TOP),
 
-        /** verification type int */
+        /** Verification type int. */
         INTEGER(ITEM_INTEGER),
 
-        /** verification type float */
+        /** Verification type float. */
         FLOAT(ITEM_FLOAT),
 
-        /** verification type double */
+        /** Verification type double. */
         DOUBLE(ITEM_DOUBLE),
 
-        /** verification type long */
+        /** Verification type long. */
         LONG(ITEM_LONG),
 
-        /** verification type null */
+        /** Verification type null. */
         NULL(ITEM_NULL),
 
-        /** verification type uninitializedThis */
+        /** Verification type uninitializedThis. */
         UNINITIALIZED_THIS(ITEM_UNINITIALIZED_THIS);
 
 
@@ -162,6 +181,7 @@ public int tag() {
     /**
      * A stack value for an object type. Its {@link #tag() tag} is {@value #ITEM_OBJECT}.
      *
+     * @jvms 4.7.4 The {@code StackMapTable} Attribute
      * @since 24
      */
     sealed interface ObjectVerificationTypeInfo extends VerificationTypeInfo
@@ -190,7 +210,7 @@ public static ObjectVerificationTypeInfo of(ClassDesc classDesc) {
         ClassEntry className();
 
         /**
-         * {@return the class of the object}
+         * {@return the class of the object, as a symbolic descriptor}
          */
         default ClassDesc classSymbol() {
             return className().asSymbol();
@@ -200,19 +220,22 @@ default ClassDesc classSymbol() {
     /**
      * An uninitialized stack value. Its {@link #tag() tag} is {@value #ITEM_UNINITIALIZED}.
      *
+     * @jvms 4.7.4 The {@code StackMapTable} Attribute
      * @since 24
      */
     sealed interface UninitializedVerificationTypeInfo extends VerificationTypeInfo
             permits StackMapDecoder.UninitializedVerificationTypeInfoImpl {
 
         /**
-         * {@return the {@code new} instruction position that creates this unitialized object}
+         * {@return the label immediately before the {@link Opcode#NEW new}
+         * instruction that creates this uninitialized object}
          */
         Label newTarget();
 
         /**
-         * {@return an unitialized verification type info}
-         * @param newTarget the {@code new} instruction position that creates this unitialized object
+         * {@return an uninitialized verification type info}
+         * @param newTarget the label immediately before the {@link Opcode#NEW new}
+         *                  instruction that creates this uninitialized object
          */
         public static UninitializedVerificationTypeInfo of(Label newTarget) {
             return new StackMapDecoder.UninitializedVerificationTypeInfoImpl(newTarget);
diff --git a/src/java.base/share/classes/java/lang/classfile/attribute/StackMapTableAttribute.java b/src/java.base/share/classes/java/lang/classfile/attribute/StackMapTableAttribute.java
index 0d577fb6cd5..e9b3acbff5b 100644
--- a/src/java.base/share/classes/java/lang/classfile/attribute/StackMapTableAttribute.java
+++ b/src/java.base/share/classes/java/lang/classfile/attribute/StackMapTableAttribute.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2022, 2024, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2022, 2025, 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
@@ -26,22 +26,40 @@
 package java.lang.classfile.attribute;
 
 import java.lang.classfile.Attribute;
+import java.lang.classfile.AttributeMapper;
+import java.lang.classfile.AttributeMapper.AttributeStability;
+import java.lang.classfile.Attributes;
+import java.lang.classfile.ClassFile;
 import java.lang.classfile.CodeElement;
+import java.lang.classfile.instruction.DiscontinuedInstruction;
 import java.util.List;
 
 import jdk.internal.classfile.impl.BoundAttribute;
 import jdk.internal.classfile.impl.UnboundAttribute;
 
 /**
- * Models the {@code StackMapTable} attribute (JVMS {@jvms 4.7.4}), which can appear
- * on a {@code Code} attribute.
+ * Models the {@link Attributes#stackMapTable() StackMapTable} attribute (JVMS
+ * {@jvms 4.7.4}), which is used for verification by type checking ({@jvms
+ * 4.10.1}).
  * <p>
- * The attribute does not permit multiple instances in a given location.
- * Subsequent occurrence of the attribute takes precedence during the attributed
- * element build or transformation.
+ * This attribute is not delivered in the traversal of a {@link CodeAttribute},
+ * but instead automatically generated upon {@code class} file writing.
+ * Advanced users can supply their own stack maps according to the {@link
+ * ClassFile.StackMapsOption}.
  * <p>
- * The attribute was introduced in the Java SE Platform version 6.
+ * This attribute only appears on {@code Code} attributes, and does not permit
+ * {@linkplain AttributeMapper#allowMultiple multiple instances} in a {@code
+ * Code} attribute.  It has a data dependency on {@linkplain
+ * AttributeStability#LABELS labels} in the {@code code} array.
+ * <p>
+ * This attribute was introduced in the Java SE Platform version 6, major
+ * version {@value ClassFile#JAVA_6_VERSION}.
  *
+ * @see Attributes#stackMapTable()
+ * @see DiscontinuedInstruction.JsrInstruction
+ * @see DiscontinuedInstruction.RetInstruction
+ * @jvms 4.7.4 The {@code StackMapTable} Attribute
+ * @jvms 4.10.1 Verification by Type Checking
  * @since 24
  */
 public sealed interface StackMapTableAttribute
@@ -55,6 +73,7 @@ public sealed interface StackMapTableAttribute
 
     /**
      * {@return a stack map table attribute}
+     *
      * @param entries the stack map frames
      */
     public static StackMapTableAttribute of(List<StackMapFrameInfo> entries) {
diff --git a/src/java.base/share/classes/java/lang/classfile/attribute/SyntheticAttribute.java b/src/java.base/share/classes/java/lang/classfile/attribute/SyntheticAttribute.java
index 1e6b706ec08..6a38e4c34d6 100644
--- a/src/java.base/share/classes/java/lang/classfile/attribute/SyntheticAttribute.java
+++ b/src/java.base/share/classes/java/lang/classfile/attribute/SyntheticAttribute.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2022, 2024, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2022, 2025, 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
@@ -25,24 +25,37 @@
 
 package java.lang.classfile.attribute;
 
-import java.lang.classfile.Attribute;
-import java.lang.classfile.ClassElement;
-import java.lang.classfile.FieldElement;
-import java.lang.classfile.MethodElement;
+import java.lang.classfile.*;
+import java.lang.classfile.AttributeMapper.AttributeStability;
+import java.lang.reflect.AccessFlag;
 
 import jdk.internal.classfile.impl.BoundAttribute;
 import jdk.internal.classfile.impl.UnboundAttribute;
 
 /**
- * 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.
+ * Models the {@link Attributes#synthetic() Synthetic} attribute (JVMS {@jvms
+ * 4.7.8}), which marks a class member as implementation-specific artifacts.
  * <p>
- * The attribute permits multiple instances in a given location.
+ * This attribute can appear on classes, methods, and fields, and permits
+ * {@linkplain AttributeMapper#allowMultiple multiple instances} in a structure.
+ * It has {@linkplain AttributeStability#STATELESS no data dependency}.
+ * <p>
+ * This attribute was introduced in the Java SE Platform version 1.1, major
+ * version {@value ClassFile#JAVA_1_VERSION}.
+ *
+ * @apiNote
+ * This attribute has been largely superseded by the {@link AccessFlag#SYNTHETIC
+ * ACC_SYNTHETIC} modifier in newer {@code class} files.  See {@link
+ * java.compiler/javax.lang.model.util.Elements.Origin} for a more in-depth
+ * description about the differences between synthetic and implicit (mandated)
+ * constructs generated by compilers.
  *
+ * @see Attributes#synthetic()
+ * @see AccessFlag#SYNTHETIC
+ * @jvms 4.7.8 The {@code Synthetic} Attribute
  * @since 24
  */
+@SuppressWarnings("doclint:reference")
 public sealed interface SyntheticAttribute
         extends Attribute<SyntheticAttribute>,
                 ClassElement, MethodElement, FieldElement
diff --git a/src/java.base/share/classes/java/lang/classfile/attribute/UnknownAttribute.java b/src/java.base/share/classes/java/lang/classfile/attribute/UnknownAttribute.java
index ad47f35a856..c35942bc42c 100644
--- a/src/java.base/share/classes/java/lang/classfile/attribute/UnknownAttribute.java
+++ b/src/java.base/share/classes/java/lang/classfile/attribute/UnknownAttribute.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2022, 2024, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2022, 2025, 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
@@ -25,16 +25,22 @@
 
 package java.lang.classfile.attribute;
 
-import java.lang.classfile.Attribute;
-import java.lang.classfile.ClassElement;
-import java.lang.classfile.FieldElement;
-import java.lang.classfile.MethodElement;
+import java.lang.classfile.*;
+import java.lang.classfile.AttributeMapper.AttributeStability;
 
 import jdk.internal.classfile.impl.BoundAttribute;
 
 /**
- * Models an unknown attribute on a class, method, or field.
+ * Models an unknown attribute read from a {@code class} file.  An attribute is
+ * unknown if it is not recognized by one of the mappers in {@link Attributes}
+ * and is not recognized by the {@link ClassFile.AttributesProcessingOption}.
+ * <p>
+ * This attribute is not delivered in the traversal of a {@link CodeModel}.
+ * <p>
+ * An unknown attribute may appear anywhere where an attribute may appear, and
+ * has an {@linkplain AttributeStability#UNKNOWN unknown} data dependency.
  *
+ * @see CustomAttribute
  * @since 24
  */
 public sealed interface UnknownAttribute
diff --git a/src/java.base/share/classes/java/lang/classfile/attribute/package-info.java b/src/java.base/share/classes/java/lang/classfile/attribute/package-info.java
index 08bd28cbc58..1ddd0511d85 100644
--- a/src/java.base/share/classes/java/lang/classfile/attribute/package-info.java
+++ b/src/java.base/share/classes/java/lang/classfile/attribute/package-info.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2023, 2024, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2023, 2025, 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
@@ -24,11 +24,79 @@
  */
 
 /**
- * <h2>Provides interfaces describing classfile attributes for the {@link java.lang.classfile} library.</h2>
+ * <h2>Provides interfaces describing {@code class} file attributes for the {@link java.lang.classfile} library.</h2>
  *
- * The {@code java.lang.classfile.attribute} package contains interfaces describing classfile attributes.
+ * The {@code java.lang.classfile.attribute} package contains interfaces describing specific {@code class} file
+ * attributes, including predefined (JVMS {@jvms 4.7}) and JDK-specific nonstandard attributes, whose mappers are
+ * defined in {@link Attributes}.  This package summary provides an overview to the {@code class} file attribute system,
+ * including {@link Attribute}, {@link AttributedElement}, {@link AttributeMapper}, and {@link CustomAttribute}, which
+ * do not reside in this package.
+ * <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 Attributes</h2>
+ * The general way to obtain attributes is through {@link AttributedElement}.  In addition to that, many attributes
+ * implement {@link ClassElement}, {@link FieldElement}, {@link MethodElement}, or {@link CodeElement}, and these
+ * attributes are generally delivered when their enclosing elements are viewed as {@link CompoundElement}s in streaming
+ * traversal, unless otherwise specified.
+ * <p>
+ * When read from {@code class} files, the attributes are lazily inflated; the contents of these attributes are not
+ * evaluated to speed up parsing, and user-defined attributes from {@link AttributeMapper#readAttribute} should be
+ * lazy too.  Contents to users interest can be read on demand, so errors in one attribute does not prevent access to
+ * other attributes.
+ * <p>
+ * Attribute contents are represented with constant pool entries to closely represent the original {@code class} file.
+ * These entries provide conversion methods to view them as validated symbolic descriptors.  Check {@link
+ * java.lang.classfile.constantpool} for effective reading of constant pool entries, which can affect attribute reading
+ * speed as well.  See this example of checking the presence of a {@link Deprecated} annotation:
+ * {@snippet lang="java" class="PackageSnippets" region="hasDeprecated"}
+ * <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, either from the attribute itself due to structural
+ * corruption, or from a constant pool entry referred by the attribute.  Some attributes, such as annotation attributes,
+ * must be ignored silently if they are malformed per JVMS; as a result, attribute processing code should anticipate
+ * {@link IllegalArgumentException} and skip, instead of propagating the failure, on such attributes.
+ *
+ * <h2 id="writing">Writing Attributes</h2>
+ * Most attributes implement at least one of {@link ClassElement}, {@link FieldElement}, {@link MethodElement}, or
+ * {@link CodeElement}, so they can be sent to the respective {@link ClassFileBuilder} to be written as part of those
+ * structure.  Attributes define if they can {@linkplain AttributeMapper#allowMultiple() appear multiple times} in one
+ * structure; if they cannot, the last attribute instance supplied to the builder is the one written to the final
+ * structure.  Some attributes, such as {@link BootstrapMethodsAttribute}, implement none of those interfaces.  They are
+ * created through other means, specified in the modeling interface for each of the attributes.  Attributes for a {@link
+ * RecordComponentInfo} are supplied through its factory methods.
+ * <p>
+ * The attribute factories generally have two sets of factory methods: one that accepts symbolic information
+ * representing the uses, and another that accepts constant pool entries.  Most of time, the symbolic factories are
+ * sufficent, but the constant pool entry ones can be used for fine-grained control over {@code class} file generation;
+ * see "{@linkplain java.lang.classfile.constantpool##writing Writing the constant pool entries}" for more details.
+ * <p>
+ * Many attributes can be bulk-copied if the data it depends on does not change; this information is exposed in {@link
+ * AttributeMapper#stability()} and is documented for each attribute on its modeling interface.  Ability to bulk-copy
+ * can massively speed up {@code class} file generation or transformation.  In addition, in conjunction with {@link
+ * ClassFile.AttributesProcessingOption}, attributes read from other {@code class} files that cannot confirm its data
+ * is still valid for the currently building {@code class} file may be dropped.
+ *
+ * @see Attribute
+ * @see AttributeMapper
+ * @see Attributes
+ * @jvms 4.7 Attributes
  * @since 24
  */
 package java.lang.classfile.attribute;
 
+import java.lang.classfile.Attribute;
+import java.lang.classfile.AttributeMapper;
+import java.lang.classfile.AttributedElement;
+import java.lang.classfile.Attributes;
+import java.lang.classfile.ClassElement;
+import java.lang.classfile.ClassFile;
+import java.lang.classfile.ClassFileBuilder;
+import java.lang.classfile.ClassModel;
+import java.lang.classfile.CodeElement;
+import java.lang.classfile.CompoundElement;
+import java.lang.classfile.CustomAttribute;
+import java.lang.classfile.FieldElement;
+import java.lang.classfile.MethodElement;
diff --git a/src/java.base/share/classes/java/lang/classfile/attribute/snippet-files/PackageSnippets.java b/src/java.base/share/classes/java/lang/classfile/attribute/snippet-files/PackageSnippets.java
new file mode 100644
index 00000000000..452f39f56db
--- /dev/null
+++ b/src/java.base/share/classes/java/lang/classfile/attribute/snippet-files/PackageSnippets.java
@@ -0,0 +1,63 @@
+/*
+ * Copyright (c) 2025, 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
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation.  Oracle designates this
+ * particular file as subject to the "Classpath" exception as provided
+ * by Oracle in the LICENSE file that accompanied this code.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
+ * or visit www.oracle.com if you need additional information or have any
+ * questions.
+ */
+package java.lang.classfile.attribute.snippet;
+
+import java.lang.classfile.AttributedElement;
+import java.lang.classfile.Attributes;
+import java.lang.classfile.CodeBuilder;
+import java.lang.classfile.MethodModel;
+import java.lang.classfile.attribute.RuntimeVisibleAnnotationsAttribute;
+import java.util.List;
+
+class PackageSnippets {
+
+    // @start region=hasDeprecated
+    private static final String DEPRECATED_DESC = Deprecated.class.descriptorString();
+
+    static boolean hasDeprecated(AttributedElement element) {
+        var annotations = element.findAttribute(Attributes.runtimeVisibleAnnotations())
+                .map(RuntimeVisibleAnnotationsAttribute::annotations)
+                .orElse(List.of());
+        for (var anno : annotations) {
+            // equalsString reduces extra computations for raw UTF-8 entries
+            if (anno.className().equalsString(DEPRECATED_DESC)) {
+                return true;
+            }
+        }
+        return false;
+    }
+    // @end
+
+    // @start region=reuseStackMaps
+    static void reuseStackMaps(MethodModel oldMethod, CodeBuilder cob) {
+        var oldCode = oldMethod.code().orElseThrow();
+        // The StackMapTable attribute is not streamed in CodeModel, so this is
+        // the only way to obtain it
+        // @link substring="findAttribute" target="AttributedElement#findAttribute" :
+        var stackMaps = oldCode.findAttribute(Attributes.stackMapTable());
+        stackMaps.ifPresent(cob); // Note: CodeBuilder is a Consumer<CodeElement>
+    }
+    // @end
+}
diff --git a/src/java.base/share/classes/java/lang/classfile/constantpool/DoubleEntry.java b/src/java.base/share/classes/java/lang/classfile/constantpool/DoubleEntry.java
index bc6956b5bf5..f41dde8c966 100644
--- a/src/java.base/share/classes/java/lang/classfile/constantpool/DoubleEntry.java
+++ b/src/java.base/share/classes/java/lang/classfile/constantpool/DoubleEntry.java
@@ -34,8 +34,8 @@
  * <p>
  * The use of a {@code DoubleEntry} is modeled by a {@code double}.  Conversions
  * are through {@link ConstantPoolBuilder#doubleEntry} and {@link #doubleValue()}.
- * In the conversions, all NaN values of the {@code double} may be collapsed
- * into a single {@linkplain Double#NaN "canonical" NaN value}.
+ * In the conversions, all NaN values of the {@code double} may or may not be
+ * collapsed into a single {@linkplain Double#NaN "canonical" NaN value}.
  * <p>
  * A double entry has a {@linkplain #width() width} of {@code 2}, making its
  * subsequent constant pool index valid and unusable.
diff --git a/src/java.base/share/classes/java/lang/classfile/constantpool/FloatEntry.java b/src/java.base/share/classes/java/lang/classfile/constantpool/FloatEntry.java
index 2ccf3fb94e4..add8707ce82 100644
--- a/src/java.base/share/classes/java/lang/classfile/constantpool/FloatEntry.java
+++ b/src/java.base/share/classes/java/lang/classfile/constantpool/FloatEntry.java
@@ -34,8 +34,8 @@
  * <p>
  * The use of a {@code FloatEntry} is modeled by a {@code float}.  Conversions
  * are through {@link ConstantPoolBuilder#floatEntry} and {@link #floatValue()}.
- * In the conversions, all NaN values of the {@code float} may be collapsed into
- * a single {@linkplain Float#NaN "canonical" NaN value}.
+ * In the conversions, all NaN values of the {@code float} may or may not be
+ * collapsed into a single {@linkplain Float#NaN "canonical" NaN value}.
  *
  * @see ConstantPoolBuilder#floatEntry ConstantPoolBuilder::floatEntry
  * @jvms 4.4.4 The {@code CONSTANT_Integer_info} and {@code CONSTANT_Float_info}
diff --git a/src/java.base/share/classes/java/lang/classfile/instruction/DiscontinuedInstruction.java b/src/java.base/share/classes/java/lang/classfile/instruction/DiscontinuedInstruction.java
index 4170e142ffe..906aaea421d 100644
--- a/src/java.base/share/classes/java/lang/classfile/instruction/DiscontinuedInstruction.java
+++ b/src/java.base/share/classes/java/lang/classfile/instruction/DiscontinuedInstruction.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2023, 2024, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2023, 2025, 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
@@ -25,6 +25,7 @@
 package java.lang.classfile.instruction;
 
 import java.lang.classfile.*;
+import java.lang.classfile.attribute.StackMapTableAttribute;
 
 import jdk.internal.classfile.impl.AbstractInstruction;
 import jdk.internal.classfile.impl.BytecodeHelpers;
@@ -71,7 +72,13 @@ public sealed interface DiscontinuedInstruction extends Instruction {
      * astore} series of instructions can then store this value to a local
      * variable slot.
      *
+     * @apiNote
+     * Jump subroutine instructions are discontinued to enforce verification by
+     * type checking (JVMS {@jvms 4.10.1}) using the {@link StackMapTableAttribute
+     * StackMapTable} attribute.
+     *
      * @see Opcode.Kind#DISCONTINUED_JSR
+     * @see StackMapTableAttribute
      * @since 24
      */
     sealed interface JsrInstruction extends DiscontinuedInstruction
@@ -130,8 +137,14 @@ static JsrInstruction of(Label target) {
      * TypeKind##returnAddress returnAddress} value to a local variable slot,
      * making the slot usable by a return from subroutine instruction.
      *
+     * @apiNote
+     * Return from subroutine instructions are discontinued to enforce
+     * verification by type checking (JVMS {@jvms 4.10.1}) using the {@link
+     * StackMapTableAttribute StackMapTable} attribute.
+     *
      * @jvms 6.5.ret <em>ret</em>
      * @see Opcode.Kind#DISCONTINUED_RET
+     * @see StackMapTableAttribute
      * @since 24
      */
     sealed interface RetInstruction extends DiscontinuedInstruction
diff --git a/test/jdk/jdk/classfile/SnippetsTest.java b/test/jdk/jdk/classfile/SnippetsTest.java
index 2b84820e9b9..d15dbc0ca3d 100644
--- a/test/jdk/jdk/classfile/SnippetsTest.java
+++ b/test/jdk/jdk/classfile/SnippetsTest.java
@@ -42,6 +42,7 @@ public class SnippetsTest {
     @ParameterizedTest
     @ValueSource(strings = {
         "src/java.base/share/classes/java/lang/classfile/snippet-files/PackageSnippets.java",
+        "src/java.base/share/classes/java/lang/classfile/attribute/snippet-files/PackageSnippets.java",
         "src/java.base/share/classes/java/lang/classfile/constantpool/snippet-files/PackageSnippets.java",
         "src/java.base/share/classes/jdk/internal/classfile/components/snippet-files/PackageSnippets.java"
     })

From ab43ba0ef862a3bc1f9e1c5a7d4d0fecf3928582 Mon Sep 17 00:00:00 2001
From: Mikael Vidstedt <mikael@openjdk.org>
Date: Fri, 24 Jan 2025 18:07:26 +0000
Subject: [PATCH 2/3] 8348327: Incorrect march flag when building
 libsleef/vector_math_neon.c

Reviewed-by: erikj, shade
Backport-of: 3ebf88996f35f397f4396e3d139b9251048de751
---
 make/modules/jdk.incubator.vector/Lib.gmk | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/make/modules/jdk.incubator.vector/Lib.gmk b/make/modules/jdk.incubator.vector/Lib.gmk
index 69da7ed059a..7d2ef440b67 100644
--- a/make/modules/jdk.incubator.vector/Lib.gmk
+++ b/make/modules/jdk.incubator.vector/Lib.gmk
@@ -1,5 +1,5 @@
 #
-# Copyright (c) 2021, 2024, Oracle and/or its affiliates. All rights reserved.
+# Copyright (c) 2021, 2025, 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
@@ -64,7 +64,7 @@ ifeq ($(call isTargetOs, linux)+$(call isTargetCpu, aarch64)+$(INCLUDE_COMPILER2
       EXTRA_SRC := libsleef/generated, \
       DISABLED_WARNINGS_gcc := unused-function sign-compare tautological-compare ignored-qualifiers, \
       DISABLED_WARNINGS_clang := unused-function sign-compare tautological-compare ignored-qualifiers, \
-      CFLAGS := $(SVE_CFLAGS), \
+      vector_math_sve.c_CFLAGS := $(SVE_CFLAGS), \
   ))
 
   TARGETS += $(BUILD_LIBSLEEF)

From a315b9326b07a6241858c55d15e4cbec4ab3773b Mon Sep 17 00:00:00 2001
From: Justin Lu <jlu@openjdk.org>
Date: Mon, 27 Jan 2025 17:24:45 +0000
Subject: [PATCH 3/3] 8347498: JDK 24 RDP2 L10n resource files update

Reviewed-by: dnguyen, naoto, iris
Backport-of: dec93675ab3e4c271b14a254df75dc838f1346ea
---
 .../internal/res/XSLTErrorResources_de.java    |  6 +++---
 .../internal/res/XSLTErrorResources_ja.java    |  6 +++---
 .../internal/res/XSLTErrorResources_zh_CN.java |  6 +++---
 .../xsltc/compiler/util/ErrorMessages_de.java  |  8 +++++++-
 .../xsltc/compiler/util/ErrorMessages_ja.java  |  8 +++++++-
 .../compiler/util/ErrorMessages_zh_CN.java     |  8 +++++++-
 .../xsltc/runtime/ErrorMessages_de.java        |  8 ++++----
 .../xsltc/runtime/ErrorMessages_ja.java        |  8 ++++----
 .../xsltc/runtime/ErrorMessages_zh_CN.java     |  8 ++++----
 .../javac/resources/compiler_de.properties     |  6 ++----
 .../javac/resources/compiler_ja.properties     |  6 ++----
 .../javac/resources/compiler_zh_CN.properties  |  6 ++----
 .../javac/resources/launcher_de.properties     |  2 --
 .../javac/resources/launcher_ja.properties     |  2 --
 .../javac/resources/launcher_zh_CN.properties  |  2 --
 .../tools/jlink/resources/jlink_de.properties  | 18 ++++++++++--------
 .../tools/jlink/resources/jlink_ja.properties  |  6 ++++--
 .../jlink/resources/jlink_zh_CN.properties     |  6 ++++--
 .../tools/jmod/resources/jmod_de.properties    |  2 +-
 .../resources/HelpResources_de.properties      |  4 ++--
 .../resources/WinResources_de.properties       |  2 ++
 .../resources/WinResources_ja.properties       |  2 ++
 .../resources/WinResources_zh_CN.properties    |  2 ++
 .../jshell/tool/resources/l10n_de.properties   |  2 +-
 .../jshell/tool/resources/l10n_ja.properties   |  2 +-
 .../tool/resources/l10n_zh_CN.properties       |  2 +-
 26 files changed, 78 insertions(+), 60 deletions(-)

diff --git a/src/java.xml/share/classes/com/sun/org/apache/xalan/internal/res/XSLTErrorResources_de.java b/src/java.xml/share/classes/com/sun/org/apache/xalan/internal/res/XSLTErrorResources_de.java
index a6f8370a2d7..bcdb0f59f5c 100644
--- a/src/java.xml/share/classes/com/sun/org/apache/xalan/internal/res/XSLTErrorResources_de.java
+++ b/src/java.xml/share/classes/com/sun/org/apache/xalan/internal/res/XSLTErrorResources_de.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2017, 2022, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2017, 2024, Oracle and/or its affiliates. All rights reserved.
  */
 /*
  * Licensed to the Apache Software Foundation (ASF) under one or more
@@ -31,7 +31,7 @@
  * Array. You also need to update MAX_CODE for error strings
  * and MAX_WARNING for warnings ( Needed for only information
  * purpose )
- * @LastModified: May 2022
+ * @LastModified: Dec 2024
  */
 public class XSLTErrorResources_de extends ListResourceBundle
 {
@@ -1197,7 +1197,7 @@ public Object[][] getContents()
       "Das Feature \"{0}\" kann nicht f\u00FCr diese TransformerFactory festgelegt werden."},
 
     { ER_EXTENSION_ELEMENT_NOT_ALLOWED_IN_SECURE_PROCESSING,
-          "Verwendung des Erweiterungselements \"{0}\" ist nicht zul\u00E4ssig, wenn das Feature f\u00FCr die sichere Verarbeitung auf \"true\" gesetzt ist."},
+        "Verwendung der Erweiterungsfunktion \"{0}\" ist nicht zul\u00E4ssig, wenn die Erweiterungsfunktionen vom Feature f\u00FCr die sichere Verarbeitung oder der Eigenschaft \"jdk.xml.enableExtensionFunctions\" deaktiviert wurden. Setzen Sie \"jdk.xml.enableExtensionFunctions\" auf \"true\", um die Erweiterungsfunktionen zu aktivieren."},
 
     { ER_NAMESPACE_CONTEXT_NULL_NAMESPACE,
       "Pr\u00E4fix f\u00FCr Null-Namespace-URI kann nicht abgerufen werden."},
diff --git a/src/java.xml/share/classes/com/sun/org/apache/xalan/internal/res/XSLTErrorResources_ja.java b/src/java.xml/share/classes/com/sun/org/apache/xalan/internal/res/XSLTErrorResources_ja.java
index cf8a0f2563b..8555d69597b 100644
--- a/src/java.xml/share/classes/com/sun/org/apache/xalan/internal/res/XSLTErrorResources_ja.java
+++ b/src/java.xml/share/classes/com/sun/org/apache/xalan/internal/res/XSLTErrorResources_ja.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2017, 2022, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2017, 2024, Oracle and/or its affiliates. All rights reserved.
  */
 /*
  * Licensed to the Apache Software Foundation (ASF) under one or more
@@ -31,7 +31,7 @@
  * Array. You also need to update MAX_CODE for error strings
  * and MAX_WARNING for warnings ( Needed for only information
  * purpose )
- * @LastModified: May 2022
+ * @LastModified: Dec 2024
  */
 public class XSLTErrorResources_ja extends ListResourceBundle
 {
@@ -1197,7 +1197,7 @@ public Object[][] getContents()
       "\u6A5F\u80FD''{0}''\u3092\u3053\u306ETransformerFactory\u306B\u8A2D\u5B9A\u3067\u304D\u307E\u305B\u3093\u3002"},
 
     { ER_EXTENSION_ELEMENT_NOT_ALLOWED_IN_SECURE_PROCESSING,
-          "\u30BB\u30AD\u30E5\u30A2\u51E6\u7406\u6A5F\u80FD\u304Ctrue\u306B\u8A2D\u5B9A\u3055\u308C\u3066\u3044\u308B\u3068\u304D\u3001\u62E1\u5F35\u8981\u7D20''{0}''\u306E\u4F7F\u7528\u306F\u8A31\u53EF\u3055\u308C\u307E\u305B\u3093\u3002"},
+        "\u30BB\u30AD\u30E5\u30A2\u51E6\u7406\u6A5F\u80FD\u307E\u305F\u306F\u30D7\u30ED\u30D1\u30C6\u30A3''jdk.xml.enableExtensionFunctions''\u306B\u3088\u3063\u3066\u62E1\u5F35\u95A2\u6570\u304C\u7121\u52B9\u306B\u306A\u3063\u3066\u3044\u308B\u3068\u304D\u3001\u62E1\u5F35\u95A2\u6570''{0}''\u306E\u4F7F\u7528\u306F\u8A31\u53EF\u3055\u308C\u307E\u305B\u3093\u3002\u62E1\u5F35\u95A2\u6570\u3092\u6709\u52B9\u306B\u3059\u308B\u306B\u306F\u3001''jdk.xml.enableExtensionFunctions''\u3092''true''\u306B\u8A2D\u5B9A\u3057\u307E\u3059\u3002"},
 
     { ER_NAMESPACE_CONTEXT_NULL_NAMESPACE,
       "null\u306E\u30CD\u30FC\u30E0\u30B9\u30DA\u30FC\u30B9URI\u306B\u3064\u3044\u3066\u63A5\u982D\u8F9E\u3092\u53D6\u5F97\u3067\u304D\u307E\u305B\u3093\u3002"},
diff --git a/src/java.xml/share/classes/com/sun/org/apache/xalan/internal/res/XSLTErrorResources_zh_CN.java b/src/java.xml/share/classes/com/sun/org/apache/xalan/internal/res/XSLTErrorResources_zh_CN.java
index dc7ecef28f8..c5ae6af08c0 100644
--- a/src/java.xml/share/classes/com/sun/org/apache/xalan/internal/res/XSLTErrorResources_zh_CN.java
+++ b/src/java.xml/share/classes/com/sun/org/apache/xalan/internal/res/XSLTErrorResources_zh_CN.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2017, 2022, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2017, 2024, Oracle and/or its affiliates. All rights reserved.
  */
 /*
  * Licensed to the Apache Software Foundation (ASF) under one or more
@@ -31,7 +31,7 @@
  * Array. You also need to update MAX_CODE for error strings
  * and MAX_WARNING for warnings ( Needed for only information
  * purpose )
- * @LastModified: May 2022
+ * @LastModified: Dec 2024
  */
 public class XSLTErrorResources_zh_CN extends ListResourceBundle
 {
@@ -1197,7 +1197,7 @@ public Object[][] getContents()
       "\u65E0\u6CD5\u5BF9\u6B64 TransformerFactory \u8BBE\u7F6E\u529F\u80FD ''{0}''\u3002"},
 
     { ER_EXTENSION_ELEMENT_NOT_ALLOWED_IN_SECURE_PROCESSING,
-          "\u5F53\u5B89\u5168\u5904\u7406\u529F\u80FD\u8BBE\u7F6E\u4E3A\u201C\u771F\u201D\u65F6, \u4E0D\u5141\u8BB8\u4F7F\u7528\u6269\u5C55\u5143\u7D20 ''{0}''\u3002"},
+        "\u5F53\u6269\u5C55\u51FD\u6570\u88AB\u5B89\u5168\u5904\u7406\u529F\u80FD\u6216\u5C5E\u6027 ''jdk.xml.enableExtensionFunctions'' \u7981\u7528\u65F6\uFF0C\u4E0D\u5141\u8BB8\u4F7F\u7528\u6269\u5C55\u51FD\u6570 ''{0}''\u3002\u8981\u542F\u7528\u6269\u5C55\u51FD\u6570\uFF0C\u8BF7\u5C06 ''jdk.xml.enableExtensionFunctions'' \u8BBE\u7F6E\u4E3A ''true''\u3002"},
 
     { ER_NAMESPACE_CONTEXT_NULL_NAMESPACE,
       "\u65E0\u6CD5\u83B7\u53D6\u7A7A\u540D\u79F0\u7A7A\u95F4 uri \u7684\u524D\u7F00\u3002"},
diff --git a/src/java.xml/share/classes/com/sun/org/apache/xalan/internal/xsltc/compiler/util/ErrorMessages_de.java b/src/java.xml/share/classes/com/sun/org/apache/xalan/internal/xsltc/compiler/util/ErrorMessages_de.java
index 12ec243bbc9..c16620ec7b1 100644
--- a/src/java.xml/share/classes/com/sun/org/apache/xalan/internal/xsltc/compiler/util/ErrorMessages_de.java
+++ b/src/java.xml/share/classes/com/sun/org/apache/xalan/internal/xsltc/compiler/util/ErrorMessages_de.java
@@ -24,7 +24,7 @@
 
 /**
  * @author Morten Jorgensen
- * @LastModified: Nov 2024
+ * @LastModified: Dec 2024
  */
 public class ErrorMessages_de extends ListResourceBundle {
 
@@ -548,6 +548,12 @@ public Object[][] getContents()
         {ErrorMsg.DATA_CONVERSION_ERR,
         "Datentyp \"{0}\" kann nicht in \"{1}\" konvertiert werden."},
 
+        /*
+         * Note to translators:  property name "jdk.xml.enableExtensionFunctions"
+         * and value "true" should not be translated.
+         */
+        {ErrorMsg.UNSUPPORTED_EXT_FUNC_ERR,
+        "Verwendung der Erweiterungsfunktion \"{0}\" ist nicht zul\u00E4ssig, wenn die Erweiterungsfunktionen vom Feature f\u00FCr die sichere Verarbeitung oder der Eigenschaft \"jdk.xml.enableExtensionFunctions\" deaktiviert wurden. Setzen Sie \"jdk.xml.enableExtensionFunctions\" auf \"true\", um die Erweiterungsfunktionen zu aktivieren."},
         /*
          * Note to translators:  "Templates" is a Java class name that should
          * not be translated.
diff --git a/src/java.xml/share/classes/com/sun/org/apache/xalan/internal/xsltc/compiler/util/ErrorMessages_ja.java b/src/java.xml/share/classes/com/sun/org/apache/xalan/internal/xsltc/compiler/util/ErrorMessages_ja.java
index 5e03673aef5..48f7d63f353 100644
--- a/src/java.xml/share/classes/com/sun/org/apache/xalan/internal/xsltc/compiler/util/ErrorMessages_ja.java
+++ b/src/java.xml/share/classes/com/sun/org/apache/xalan/internal/xsltc/compiler/util/ErrorMessages_ja.java
@@ -24,7 +24,7 @@
 
 /**
  * @author Morten Jorgensen
- * @LastModified: Nov 2024
+ * @LastModified: Dec 2024
  */
 public class ErrorMessages_ja extends ListResourceBundle {
 
@@ -548,6 +548,12 @@ public Object[][] getContents()
         {ErrorMsg.DATA_CONVERSION_ERR,
         "\u30C7\u30FC\u30BF\u578B''{0}''\u3092''{1}''\u306B\u5909\u63DB\u3067\u304D\u307E\u305B\u3093\u3002"},
 
+        /*
+         * Note to translators:  property name "jdk.xml.enableExtensionFunctions"
+         * and value "true" should not be translated.
+         */
+        {ErrorMsg.UNSUPPORTED_EXT_FUNC_ERR,
+        "\u30BB\u30AD\u30E5\u30A2\u51E6\u7406\u6A5F\u80FD\u307E\u305F\u306F\u30D7\u30ED\u30D1\u30C6\u30A3''jdk.xml.enableExtensionFunctions''\u306B\u3088\u3063\u3066\u62E1\u5F35\u95A2\u6570\u304C\u7121\u52B9\u306B\u306A\u3063\u3066\u3044\u308B\u3068\u304D\u3001\u62E1\u5F35\u95A2\u6570''{0}''\u306E\u4F7F\u7528\u306F\u8A31\u53EF\u3055\u308C\u307E\u305B\u3093\u3002\u62E1\u5F35\u95A2\u6570\u3092\u6709\u52B9\u306B\u3059\u308B\u306B\u306F\u3001''jdk.xml.enableExtensionFunctions''\u3092''true''\u306B\u8A2D\u5B9A\u3057\u307E\u3059\u3002"},
         /*
          * Note to translators:  "Templates" is a Java class name that should
          * not be translated.
diff --git a/src/java.xml/share/classes/com/sun/org/apache/xalan/internal/xsltc/compiler/util/ErrorMessages_zh_CN.java b/src/java.xml/share/classes/com/sun/org/apache/xalan/internal/xsltc/compiler/util/ErrorMessages_zh_CN.java
index 728abc0df37..0affded17e3 100644
--- a/src/java.xml/share/classes/com/sun/org/apache/xalan/internal/xsltc/compiler/util/ErrorMessages_zh_CN.java
+++ b/src/java.xml/share/classes/com/sun/org/apache/xalan/internal/xsltc/compiler/util/ErrorMessages_zh_CN.java
@@ -24,7 +24,7 @@
 
 /**
  * @author Morten Jorgensen
- * @LastModified: Nov 2024
+ * @LastModified: Dec 2024
  */
 public class ErrorMessages_zh_CN extends ListResourceBundle {
 
@@ -548,6 +548,12 @@ public Object[][] getContents()
         {ErrorMsg.DATA_CONVERSION_ERR,
         "\u65E0\u6CD5\u5C06\u6570\u636E\u7C7B\u578B ''{0}'' \u8F6C\u6362\u4E3A ''{1}''\u3002"},
 
+        /*
+         * Note to translators:  property name "jdk.xml.enableExtensionFunctions"
+         * and value "true" should not be translated.
+         */
+        {ErrorMsg.UNSUPPORTED_EXT_FUNC_ERR,
+        "\u5F53\u6269\u5C55\u51FD\u6570\u88AB\u5B89\u5168\u5904\u7406\u529F\u80FD\u6216\u5C5E\u6027 ''jdk.xml.enableExtensionFunctions'' \u7981\u7528\u65F6\uFF0C\u4E0D\u5141\u8BB8\u4F7F\u7528\u6269\u5C55\u51FD\u6570 ''{0}''\u3002\u8981\u542F\u7528\u6269\u5C55\u51FD\u6570\uFF0C\u8BF7\u5C06 ''jdk.xml.enableExtensionFunctions'' \u8BBE\u7F6E\u4E3A ''true''\u3002"},
         /*
          * Note to translators:  "Templates" is a Java class name that should
          * not be translated.
diff --git a/src/java.xml/share/classes/com/sun/org/apache/xalan/internal/xsltc/runtime/ErrorMessages_de.java b/src/java.xml/share/classes/com/sun/org/apache/xalan/internal/xsltc/runtime/ErrorMessages_de.java
index dadea4ba3b0..c93e05d74e4 100644
--- a/src/java.xml/share/classes/com/sun/org/apache/xalan/internal/xsltc/runtime/ErrorMessages_de.java
+++ b/src/java.xml/share/classes/com/sun/org/apache/xalan/internal/xsltc/runtime/ErrorMessages_de.java
@@ -1,6 +1,5 @@
 /*
- * reserved comment block
- * DO NOT REMOVE OR ALTER!
+ * Copyright (c) 2024, Oracle and/or its affiliates. All rights reserved.
  */
 /*
  * Licensed to the Apache Software Foundation (ASF) under one or more
@@ -25,6 +24,7 @@
 
 /**
  * @author Morten Jorgensen
+ * @LastModified: Dec 2024
  */
 public class ErrorMessages_de extends ListResourceBundle {
 
@@ -275,10 +275,10 @@ public Object[][] getContents()
         "Ein Attribut, dessen Wert ein NCName sein muss, hatte den Wert \"{0}\""},
 
         {BasisLibrary.UNALLOWED_EXTENSION_FUNCTION_ERR,
-        "Verwendung der Erweiterungsfunktion \"{0}\" ist nicht zul\u00E4ssig, wenn das Feature f\u00FCr die sichere Verarbeitung auf \"true\" gesetzt ist."},
+        "Verwendung der Erweiterungsfunktion \"{0}\" ist nicht zul\u00E4ssig, wenn die Erweiterungsfunktionen vom Feature f\u00FCr die sichere Verarbeitung oder der Eigenschaft \"jdk.xml.enableExtensionFunctions\" deaktiviert wurden. Setzen Sie \"jdk.xml.enableExtensionFunctions\" auf \"true\", um die Erweiterungsfunktionen zu aktivieren."},
 
         {BasisLibrary.UNALLOWED_EXTENSION_ELEMENT_ERR,
-        "Verwendung des Erweiterungselements \"{0}\" ist nicht zul\u00E4ssig, wenn das Feature f\u00FCr die sichere Verarbeitung auf \"true\" gesetzt ist."},
+        "Verwendung des Erweiterungselements \"{0}\" ist nicht zul\u00E4ssig, wenn die Erweiterungsfunktionen vom Feature f\u00FCr die sichere Verarbeitung oder der Eigenschaft \"jdk.xml.enableExtensionFunctions\" deaktiviert wurden. Setzen Sie \"jdk.xml.enableExtensionFunctions\" auf \"true\", um die Erweiterungsfunktionen zu aktivieren."},
     };
     }
 
diff --git a/src/java.xml/share/classes/com/sun/org/apache/xalan/internal/xsltc/runtime/ErrorMessages_ja.java b/src/java.xml/share/classes/com/sun/org/apache/xalan/internal/xsltc/runtime/ErrorMessages_ja.java
index 8108e8f7218..941c1c38c00 100644
--- a/src/java.xml/share/classes/com/sun/org/apache/xalan/internal/xsltc/runtime/ErrorMessages_ja.java
+++ b/src/java.xml/share/classes/com/sun/org/apache/xalan/internal/xsltc/runtime/ErrorMessages_ja.java
@@ -1,6 +1,5 @@
 /*
- * reserved comment block
- * DO NOT REMOVE OR ALTER!
+ * Copyright (c) 2024, Oracle and/or its affiliates. All rights reserved.
  */
 /*
  * Licensed to the Apache Software Foundation (ASF) under one or more
@@ -25,6 +24,7 @@
 
 /**
  * @author Morten Jorgensen
+ * @LastModified: Dec 2024
  */
 public class ErrorMessages_ja extends ListResourceBundle {
 
@@ -275,10 +275,10 @@ public Object[][] getContents()
         "\u5024\u304CNCName\u3067\u3042\u308B\u3053\u3068\u304C\u5FC5\u8981\u306A\u5C5E\u6027\u306E\u5024\u304C''{0}''\u3067\u3057\u305F"},
 
         {BasisLibrary.UNALLOWED_EXTENSION_FUNCTION_ERR,
-        "\u30BB\u30AD\u30E5\u30A2\u51E6\u7406\u6A5F\u80FD\u304Ctrue\u306B\u8A2D\u5B9A\u3055\u308C\u3066\u3044\u308B\u3068\u304D\u3001\u62E1\u5F35\u95A2\u6570''{0}''\u306E\u4F7F\u7528\u306F\u8A31\u53EF\u3055\u308C\u307E\u305B\u3093\u3002"},
+        "\u30BB\u30AD\u30E5\u30A2\u51E6\u7406\u6A5F\u80FD\u307E\u305F\u306F\u30D7\u30ED\u30D1\u30C6\u30A3''jdk.xml.enableExtensionFunctions''\u306B\u3088\u3063\u3066\u62E1\u5F35\u95A2\u6570\u304C\u7121\u52B9\u306B\u306A\u3063\u3066\u3044\u308B\u3068\u304D\u3001\u62E1\u5F35\u95A2\u6570''{0}''\u306E\u4F7F\u7528\u306F\u8A31\u53EF\u3055\u308C\u307E\u305B\u3093\u3002\u62E1\u5F35\u95A2\u6570\u3092\u6709\u52B9\u306B\u3059\u308B\u306B\u306F\u3001''jdk.xml.enableExtensionFunctions''\u3092''true''\u306B\u8A2D\u5B9A\u3057\u307E\u3059\u3002"},
 
         {BasisLibrary.UNALLOWED_EXTENSION_ELEMENT_ERR,
-        "\u30BB\u30AD\u30E5\u30A2\u51E6\u7406\u6A5F\u80FD\u304Ctrue\u306B\u8A2D\u5B9A\u3055\u308C\u3066\u3044\u308B\u3068\u304D\u3001\u62E1\u5F35\u8981\u7D20''{0}''\u306E\u4F7F\u7528\u306F\u8A31\u53EF\u3055\u308C\u307E\u305B\u3093\u3002"},
+        "\u30BB\u30AD\u30E5\u30A2\u51E6\u7406\u6A5F\u80FD\u307E\u305F\u306F\u30D7\u30ED\u30D1\u30C6\u30A3''jdk.xml.enableExtensionFunctions''\u306B\u3088\u3063\u3066\u62E1\u5F35\u95A2\u6570\u304C\u7121\u52B9\u306B\u306A\u3063\u3066\u3044\u308B\u3068\u304D\u3001\u62E1\u5F35\u8981\u7D20''{0}''\u306E\u4F7F\u7528\u306F\u8A31\u53EF\u3055\u308C\u307E\u305B\u3093\u3002\u62E1\u5F35\u95A2\u6570\u3092\u6709\u52B9\u306B\u3059\u308B\u306B\u306F\u3001''jdk.xml.enableExtensionFunctions''\u3092''true''\u306B\u8A2D\u5B9A\u3057\u307E\u3059\u3002"},
     };
     }
 
diff --git a/src/java.xml/share/classes/com/sun/org/apache/xalan/internal/xsltc/runtime/ErrorMessages_zh_CN.java b/src/java.xml/share/classes/com/sun/org/apache/xalan/internal/xsltc/runtime/ErrorMessages_zh_CN.java
index 076b06d50db..55484c2b10c 100644
--- a/src/java.xml/share/classes/com/sun/org/apache/xalan/internal/xsltc/runtime/ErrorMessages_zh_CN.java
+++ b/src/java.xml/share/classes/com/sun/org/apache/xalan/internal/xsltc/runtime/ErrorMessages_zh_CN.java
@@ -1,6 +1,5 @@
 /*
- * reserved comment block
- * DO NOT REMOVE OR ALTER!
+ * Copyright (c) 2024, Oracle and/or its affiliates. All rights reserved.
  */
 /*
  * Licensed to the Apache Software Foundation (ASF) under one or more
@@ -25,6 +24,7 @@
 
 /**
  * @author Morten Jorgensen
+ * @LastModified: Dec 2024
  */
 public class ErrorMessages_zh_CN extends ListResourceBundle {
 
@@ -275,10 +275,10 @@ public Object[][] getContents()
         "\u5176\u503C\u5FC5\u987B\u4E3A NCName \u7684\u5C5E\u6027\u5177\u6709\u503C ''{0}''"},
 
         {BasisLibrary.UNALLOWED_EXTENSION_FUNCTION_ERR,
-        "\u5F53\u5B89\u5168\u5904\u7406\u529F\u80FD\u8BBE\u7F6E\u4E3A\u201C\u771F\u201D\u65F6, \u4E0D\u5141\u8BB8\u4F7F\u7528\u6269\u5C55\u51FD\u6570 ''{0}''\u3002"},
+        "\u5F53\u6269\u5C55\u51FD\u6570\u88AB\u5B89\u5168\u5904\u7406\u529F\u80FD\u6216\u5C5E\u6027 ''jdk.xml.enableExtensionFunctions'' \u7981\u7528\u65F6\uFF0C\u4E0D\u5141\u8BB8\u4F7F\u7528\u6269\u5C55\u51FD\u6570 ''{0}''\u3002\u8981\u542F\u7528\u6269\u5C55\u51FD\u6570\uFF0C\u8BF7\u5C06 ''jdk.xml.enableExtensionFunctions'' \u8BBE\u7F6E\u4E3A ''true''\u3002"},
 
         {BasisLibrary.UNALLOWED_EXTENSION_ELEMENT_ERR,
-        "\u5F53\u5B89\u5168\u5904\u7406\u529F\u80FD\u8BBE\u7F6E\u4E3A\u201C\u771F\u201D\u65F6, \u4E0D\u5141\u8BB8\u4F7F\u7528\u6269\u5C55\u5143\u7D20 ''{0}''\u3002"},
+        "\u5F53\u6269\u5C55\u51FD\u6570\u88AB\u5B89\u5168\u5904\u7406\u529F\u80FD\u6216\u5C5E\u6027 ''jdk.xml.enableExtensionFunctions'' \u7981\u7528\u65F6\uFF0C\u4E0D\u5141\u8BB8\u4F7F\u7528\u6269\u5C55\u5143\u7D20 ''{0}''\u3002\u8981\u542F\u7528\u6269\u5C55\u51FD\u6570\uFF0C\u8BF7\u5C06 ''jdk.xml.enableExtensionFunctions'' \u8BBE\u7F6E\u4E3A ''true''\u3002"},
     };
     }
 
diff --git a/src/jdk.compiler/share/classes/com/sun/tools/javac/resources/compiler_de.properties b/src/jdk.compiler/share/classes/com/sun/tools/javac/resources/compiler_de.properties
index 130a644da94..8761d334157 100644
--- a/src/jdk.compiler/share/classes/com/sun/tools/javac/resources/compiler_de.properties
+++ b/src/jdk.compiler/share/classes/com/sun/tools/javac/resources/compiler_de.properties
@@ -839,8 +839,6 @@ compiler.misc.user.selected.completion.failure=Von Benutzer ausgewählter Abschl
 # 0: collection of string
 compiler.err.proc.no.explicit.annotation.processing.requested=Klassennamen "{0}" werden nur akzeptiert, wenn die Annotationsverarbeitung explizit angefordert wird
 
-compiler.err.proc.no.service=ServiceLoader konnte nicht verwendet werden und ist für Annotationsverarbeitung erforderlich.
-
 # 0: string, 1: string
 compiler.err.proc.processor.bad.option.name=Ungültiger Optionsname "{0}" von Prozessor "{1}" angegeben
 
@@ -2300,7 +2298,7 @@ compiler.misc.feature.flexible.constructors=Flexible Konstruktoren
 compiler.misc.feature.module.imports=Modulimporte
 
 # L10N: do not localize: transitive
-compiler.misc.feature.java.base.transitive=transitive Modifikator für java.base
+compiler.misc.feature.java.base.transitive=Modifikator "transitive" für java.base
 
 compiler.warn.underscore.as.identifier=Ab Release 9 ist "_" ein Schlüsselwort und kann nicht als ID verwendet werden
 
@@ -2668,7 +2666,7 @@ compiler.misc.locn.module_path=Anwendungsmodulpfad
 
 compiler.misc.cant.resolve.modules=Module können nicht aufgelöst werden
 
-compiler.misc.bad.requires.flag=Ungültiges requires-Kennzeichen: {0}
+compiler.misc.bad.requires.flag=Ungültiges Kennzeichen für "requires java.base": {0}
 
 # 0: string
 compiler.err.invalid.module.specifier=Modulbezeichner nicht zulässig: {0}
diff --git a/src/jdk.compiler/share/classes/com/sun/tools/javac/resources/compiler_ja.properties b/src/jdk.compiler/share/classes/com/sun/tools/javac/resources/compiler_ja.properties
index 2c108edf692..9ab2862407f 100644
--- a/src/jdk.compiler/share/classes/com/sun/tools/javac/resources/compiler_ja.properties
+++ b/src/jdk.compiler/share/classes/com/sun/tools/javac/resources/compiler_ja.properties
@@ -839,8 +839,6 @@ compiler.misc.user.selected.completion.failure=クラス名によるユーザー
 # 0: collection of string
 compiler.err.proc.no.explicit.annotation.processing.requested=クラス名''{0}''が受け入れられるのは、注釈処理が明示的にリクエストされた場合のみです
 
-compiler.err.proc.no.service=サービス・ローダーが使用できませんでしたが、注釈処理に必要です。
-
 # 0: string, 1: string
 compiler.err.proc.processor.bad.option.name=プロセッサ''{1}''によって指定されたオプション名''{0}''が不正です
 
@@ -2300,7 +2298,7 @@ compiler.misc.feature.flexible.constructors=柔軟なコンストラクタ
 compiler.misc.feature.module.imports=モジュール・インポート
 
 # L10N: do not localize: transitive
-compiler.misc.feature.java.base.transitive=java.baseの推移的修飾子
+compiler.misc.feature.java.base.transitive=java.baseのtransitive 修飾子
 
 compiler.warn.underscore.as.identifier=リリース9から''_''はキーワードなので識別子として使用することはできません
 
@@ -2668,7 +2666,7 @@ compiler.misc.locn.module_path=アプリケーション・モジュール・パ
 
 compiler.misc.cant.resolve.modules=モジュールを解決できません
 
-compiler.misc.bad.requires.flag=不正な必須フラグ: {0}
+compiler.misc.bad.requires.flag="requires java.base"のフラグが無効です: {0}
 
 # 0: string
 compiler.err.invalid.module.specifier=モジュール指定子は許可されません: {0}
diff --git a/src/jdk.compiler/share/classes/com/sun/tools/javac/resources/compiler_zh_CN.properties b/src/jdk.compiler/share/classes/com/sun/tools/javac/resources/compiler_zh_CN.properties
index c841c3715fc..52a6ec23e51 100644
--- a/src/jdk.compiler/share/classes/com/sun/tools/javac/resources/compiler_zh_CN.properties
+++ b/src/jdk.compiler/share/classes/com/sun/tools/javac/resources/compiler_zh_CN.properties
@@ -839,8 +839,6 @@ compiler.misc.user.selected.completion.failure=按类名列出的用户选择输
 # 0: collection of string
 compiler.err.proc.no.explicit.annotation.processing.requested=仅当显式请求批注处理时才接受类名称 ''{0}''
 
-compiler.err.proc.no.service=ServiceLoader 不可用, 但它是批注处理所必需的。
-
 # 0: string, 1: string
 compiler.err.proc.processor.bad.option.name=处理程序 ''{1}'' 提供的选项名称 ''{0}'' 错误
 
@@ -2300,7 +2298,7 @@ compiler.misc.feature.flexible.constructors=灵活构造器
 compiler.misc.feature.module.imports=模块导入
 
 # L10N: do not localize: transitive
-compiler.misc.feature.java.base.transitive=java.base 的过渡修饰符
+compiler.misc.feature.java.base.transitive=java.base 的 transitive 修饰符
 
 compiler.warn.underscore.as.identifier=从发行版 9 开始, ''_'' 为关键字, 不能用作标识符
 
@@ -2668,7 +2666,7 @@ compiler.misc.locn.module_path=应用程序模块路径
 
 compiler.misc.cant.resolve.modules=无法解析模块
 
-compiler.misc.bad.requires.flag=错误的请求标记：{0}
+compiler.misc.bad.requires.flag="requires java.base" 的标记无效：{0}
 
 # 0: string
 compiler.err.invalid.module.specifier=不允许模块说明符: {0}
diff --git a/src/jdk.compiler/share/classes/com/sun/tools/javac/resources/launcher_de.properties b/src/jdk.compiler/share/classes/com/sun/tools/javac/resources/launcher_de.properties
index efcc594ca6c..0c67a60aa0a 100644
--- a/src/jdk.compiler/share/classes/com/sun/tools/javac/resources/launcher_de.properties
+++ b/src/jdk.compiler/share/classes/com/sun/tools/javac/resources/launcher_de.properties
@@ -82,8 +82,6 @@ launcher.error=Fehler:\u0020
 
 launcher.err.no.args=kein Pfad für Quelldatei
 
-launcher.err.security.manager=Quellcode-Launcher kann nicht mit aktiviertem Sicherheitsmanager verwendet werden
-
 # 0: string
 launcher.err.invalid.filename=ungültiger Pfad für Quelldatei: {0}
 
diff --git a/src/jdk.compiler/share/classes/com/sun/tools/javac/resources/launcher_ja.properties b/src/jdk.compiler/share/classes/com/sun/tools/javac/resources/launcher_ja.properties
index 72e2478bff3..ef4d0f1f9e0 100644
--- a/src/jdk.compiler/share/classes/com/sun/tools/javac/resources/launcher_ja.properties
+++ b/src/jdk.compiler/share/classes/com/sun/tools/javac/resources/launcher_ja.properties
@@ -82,8 +82,6 @@ launcher.error=エラー:\u0020
 
 launcher.err.no.args=ソース・ファイルのパスがありません
 
-launcher.err.security.manager=セキュリティ・マネージャが有効な状態でソースコード・ランチャを使用することはできません
-
 # 0: string
 launcher.err.invalid.filename=ソース・ファイルの無効なパス: {0}
 
diff --git a/src/jdk.compiler/share/classes/com/sun/tools/javac/resources/launcher_zh_CN.properties b/src/jdk.compiler/share/classes/com/sun/tools/javac/resources/launcher_zh_CN.properties
index 9382ac9e348..a442cfe1e68 100644
--- a/src/jdk.compiler/share/classes/com/sun/tools/javac/resources/launcher_zh_CN.properties
+++ b/src/jdk.compiler/share/classes/com/sun/tools/javac/resources/launcher_zh_CN.properties
@@ -82,8 +82,6 @@ launcher.error=错误:\u0020
 
 launcher.err.no.args=无源文件的路径
 
-launcher.err.security.manager=无法在启用安全管理器的情况下使用源代码启动程序
-
 # 0: string
 launcher.err.invalid.filename=源文件的路径无效：{0}
 
diff --git a/src/jdk.jlink/share/classes/jdk/tools/jlink/resources/jlink_de.properties b/src/jdk.jlink/share/classes/jdk/tools/jlink/resources/jlink_de.properties
index eebf34ce355..06ec470a877 100644
--- a/src/jdk.jlink/share/classes/jdk/tools/jlink/resources/jlink_de.properties
+++ b/src/jdk.jlink/share/classes/jdk/tools/jlink/resources/jlink_de.properties
@@ -65,17 +65,19 @@ main.extended.help.footer=Bei Optionen, die eine <Musterliste> erfordern, ist de
 main.runtime.image.linking.cap.enabled=aktiviert
 main.runtime.image.linking.cap.disabled=deaktiviert
 main.runtime.image.linking.cap.sect.header=Funktionen:
-main.runtime.image.linking.cap.msg=\      Assemblierung von Laufzeitimage {0}
+main.runtime.image.linking.cap.msg=\      Verknüpfung von Laufzeitimage {0}
 
 error.prefix=Fehler:
 warn.prefix=Warnung:
 
-err.runtime.link.not.linkable.runtime=Dieses JDK unterstützt keine Assemblierung vom aktuellen Laufzeitimage
-err.runtime.link.jdk.jlink.prohibited=Dieses JDK enthält keine als Pakete verpackten Module und kann nicht verwendet werden, um ein anderes Image mit dem Modul jdk.jlink zu erstellen
-err.runtime.link.packaged.mods=Dieses JDK enthält keine als Pakete verpackten Module. "--keep-packaged-modules" wird nicht unterstützt
-err.runtime.link.modified.file={0} wurde modifiziert
-err.runtime.link.patched.module=Datei {0} nicht im Modulimage gefunden. "--patch-module" wird beim Verknüpfen aus dem Laufzeitimage nicht unterstützt
-err.empty.module.path=leerer Modulpfad
+err.runtime.link.not.linkable.runtime=Dieses JDK unterstützt keine Verknüpfung vom aktuellen Laufzeitimage
+err.runtime.link.jdk.jlink.prohibited=Dieses JDK enthält keine verpackten Module und kann nicht verwendet werden, um ein anderes Image mit dem Modul jdk.jlink zu erstellen
+err.runtime.link.packaged.mods=Dieses JDK enthält keine verpackten Module. "--keep-packaged-modules" wird nicht unterstützt
+err.runtime.link.modified.file={0} wurde geändert
+err.runtime.link.patched.module=jlink unterstützt keine Verknüpfung vom Laufzeitimage unter einer gepatchten Laufzeit mit --patch-module
+err.no.module.path=--module-path Option muss mit --add-modules ALL-MODULE-PATH angegeben werden
+err.empty.module.path=Kein Modul im Modulpfad "{0}" mit --add-modules ALL-MODULE-PATH gefunden
+err.limit.modules=--limit-modules nicht mit --add-modules ALL-MODULE-PATH zulässig
 err.jlink.version.mismatch=jlink-Version {0}.{1} stimmt nicht mit Ziel-java.base-Version {2}.{3} überein
 err.automatic.module:automatisches Modul kann nicht mit jlink verwendet werden: {0} aus {1}
 err.unknown.byte.order:unbekannte Bytereihenfolge {0}
@@ -116,5 +118,5 @@ no.suggested.providers=Option --bind-services ist angegeben. Keine weiteren Prov
 suggested.providers.header=Vorgeschlagene Provider
 providers.header=Provider
 
-runtime.link.info=Assemblierung basierend auf dem aktuellen Laufzeitimage
+runtime.link.info=Verknüpfung basierend auf dem aktuellen Laufzeitimage
 runtime.link.jprt.path.extra=(Laufzeitimage)
diff --git a/src/jdk.jlink/share/classes/jdk/tools/jlink/resources/jlink_ja.properties b/src/jdk.jlink/share/classes/jdk/tools/jlink/resources/jlink_ja.properties
index a20a97bcfcb..85796abba7c 100644
--- a/src/jdk.jlink/share/classes/jdk/tools/jlink/resources/jlink_ja.properties
+++ b/src/jdk.jlink/share/classes/jdk/tools/jlink/resources/jlink_ja.properties
@@ -74,8 +74,10 @@ err.runtime.link.not.linkable.runtime=このJDKでは、現在のランタイム
 err.runtime.link.jdk.jlink.prohibited=このJDKは、パッケージ化されたモジュールを含んでおらず、jdk.jlinkモジュールによる別のイメージの作成に使用できません
 err.runtime.link.packaged.mods=このJDKにはパッケージ化されたモジュールがありません。--keep-packaged-modulesはサポートされていません
 err.runtime.link.modified.file={0}が変更されました
-err.runtime.link.patched.module=ファイル{0}がモジュール・イメージに見つかりません。ランタイム・イメージからリンクする際、--patch-moduleはサポートされていません
-err.empty.module.path=空のモジュール・パス
+err.runtime.link.patched.module=--patch-moduleを使用してパッチ済ランタイムで実行する際、jlinkではランタイム・イメージからのリンクをサポートしていません
+err.no.module.path=--module-pathオプションは--add-modules ALL-MODULE-PATHで指定する必要があります
+err.empty.module.path=モジュール・パス''{0}''に--add-modules ALL-MODULE-PATHを使用したモジュールが見つかりません
+err.limit.modules=--limit-modulesは--add-modules ALL-MODULE-PATHとともに指定できません
 err.jlink.version.mismatch=jlinkバージョン{0}.{1}がターゲットのjava.baseバージョン{2}.{3}と一致しません
 err.automatic.module:jlinkでは自動モジュールは使用できません: {1}からの{0}
 err.unknown.byte.order:不明なバイト順{0}
diff --git a/src/jdk.jlink/share/classes/jdk/tools/jlink/resources/jlink_zh_CN.properties b/src/jdk.jlink/share/classes/jdk/tools/jlink/resources/jlink_zh_CN.properties
index c6746c7705c..b027c4afaee 100644
--- a/src/jdk.jlink/share/classes/jdk/tools/jlink/resources/jlink_zh_CN.properties
+++ b/src/jdk.jlink/share/classes/jdk/tools/jlink/resources/jlink_zh_CN.properties
@@ -74,8 +74,10 @@ err.runtime.link.not.linkable.runtime=此 JDK 不支持从当前运行时映像
 err.runtime.link.jdk.jlink.prohibited=此 JDK 不包含打包模块，无法用于使用 jdk.jlink 模块创建其他映像
 err.runtime.link.packaged.mods=此 JDK 没有打包模块。不支持 --keep-packaged-modules
 err.runtime.link.modified.file=已修改 {0}
-err.runtime.link.patched.module=在模块映像中未找到文件 {0}。从运行时映像链接时，不支持 --patch-module
-err.empty.module.path=空模块路径
+err.runtime.link.patched.module=当使用 --patch-module 在打补丁的运行时上运行时，jlink 不支持从当前运行时映像链接
+err.no.module.path=--module-path 选项必须与 --add-modules ALL-MODULE-PATH 一起指定
+err.empty.module.path=在随 --add-modules ALL-MODULE-PATH 提供的模块路径 ''{0}'' 中找不到模块
+err.limit.modules=不允许将 --limit-modules 与 --add-modules ALL-MODULE-PATH 一起使用
 err.jlink.version.mismatch=jlink 版本 {0}.{1} 与目标 java.base 版本 {2}.{3} 不匹配
 err.automatic.module:自动模块不能用于来自 {1} 的 jlink: {0}
 err.unknown.byte.order:未知的字节顺序 {0}
diff --git a/src/jdk.jlink/share/classes/jdk/tools/jmod/resources/jmod_de.properties b/src/jdk.jlink/share/classes/jdk/tools/jmod/resources/jmod_de.properties
index 84abaee4ce3..a5896e94abb 100644
--- a/src/jdk.jlink/share/classes/jdk/tools/jmod/resources/jmod_de.properties
+++ b/src/jdk.jlink/share/classes/jdk/tools/jmod/resources/jmod_de.properties
@@ -57,7 +57,7 @@ main.opt.man-pages=Speicherort der Manpages
 main.opt.target-platform=Zielplattform
 main.opt.target-platform.arg=target-platform
 main.opt.module-path=Modulpfad
-main.opt.hash-modules=Berechnet und erfasst Hashes zur Bindung eines in ein Package integrierten Moduls an Module, die dem angegebenen <Regex-Muster> entsprechen und direkt oder indirekt davon abhängen. Die Hashes werden in der erstellten JMOD-Datei oder in einer JMOD- oder modularen JAR-Datei in dem Modulpfad erfasst, der im jmod-Hashbefehl angegeben ist.
+main.opt.hash-modules=Berechnet und erfasst Hashes zur Bindung eines verpackten Moduls an Module, die dem angegebenen <Regex-Muster> entsprechen und direkt oder indirekt davon abhängen. Die Hashes werden in der erstellten JMOD-Datei oder in einer JMOD- oder modularen JAR-Datei in dem Modulpfad erfasst, der im jmod-Hashbefehl angegeben ist.
 main.opt.do-not-resolve-by-default=Aus dem Standard-Root-Set von Modulen ausschließen
 main.opt.warn-if-resolved=Hinweis für ein Tool, eine Warnung auszugeben, wenn das Modul aufgelöst wird, entweder "deprecated", "deprecated-for-removal" oder "incubating"
 main.opt.date=Datum und Uhrzeit für die Zeitstempel von Einträgen, angegeben im erweiterten Datums-/Uhrzeitformat mit Zeitunterschied und optionaler Zeitzone nach ISO-8601. Beispiel: "2022-02-12T12:30:00-05:00"
diff --git a/src/jdk.jpackage/share/classes/jdk/jpackage/internal/resources/HelpResources_de.properties b/src/jdk.jpackage/share/classes/jdk/jpackage/internal/resources/HelpResources_de.properties
index f060abe314f..31d6e11d70c 100644
--- a/src/jdk.jpackage/share/classes/jdk/jpackage/internal/resources/HelpResources_de.properties
+++ b/src/jdk.jpackage/share/classes/jdk/jpackage/internal/resources/HelpResources_de.properties
@@ -25,8 +25,8 @@
 #
 
 MSG_Help=Verwendung: jpackage <Optionen>\n\nBeispielverwendungen:\n--------------\n    Generiert ein für das Hostsystem geeignetes Anwendungspackage:\n        Für eine modulare Anwendung:\n            jpackage -n name -p modulePath -m moduleName/className\n        Für eine nicht modulare Anwendung:\n            jpackage -i inputDir -n name \\\n                --main-class className --main-jar myJar.jar\n        Aus einem vorab erstellten Anwendungsimage:\n            jpackage -n name --app-image appImageDir\n    Generiert ein Anwendungsimage:\n        Für eine modulare Anwendung:\n            jpackage --type app-image -n name -p modulePath \\\n                -m moduleName/className\n        Für eine nicht modulare Anwendung:\n            jpackage --type app-image -i inputDir -n name \\\n                --main-class className --main-jar myJar.jar\n        Um eigene Optionen für jlink anzugeben, führen Sie jlink separat aus:\n            jlink --output appRuntimeImage -p modulePath \\\n                --add-modules moduleName \\\n                --no-header-files [<zusätzliche jlink-Optionen>...]\n            jpackage --type app-image -n name \\\n                -m moduleName/className --runtime-image appRuntimeImage\n    Generiert ein Java Runtime-Package:\n        jpackage -n name --runtime-image <Laufzeitimage>\n{6}\nAllgemeine Optionen:\n  @<Dateiname > \n          Liest Optionen und/oder Modus aus einer Datei \n          Diese Option kann mehrmals verwendet werden.\n  --type -t <Typ> \n          Der zu erstellende Packagetyp\n          Gültige Werte: {1} \n          Bei fehlender Angabe dieser Option wird ein plattformabhängiger\n          Standardtyp erstellt.\n  --app-version <Version>\n          Version der Anwendung und/oder des Packages\n  --copyright <Copyright-Zeichenfolge>\n          Copyright für die Anwendung\n  --description <Zeichenfolge für Beschreibung>\n          Beschreibung der Anwendung\n  --help -h \n          Gibt den Verwendungstext mit einer Liste und Beschreibung jeder gültigen\n          Option für die aktuelle Plattform an den Ausgabestream aus und beendet den Vorgang\n  --icon <Dateipfad>\n          Pfad des Symbols für das Anwendungspackage\n          (absoluter Pfad oder relativ zum aktuellen Verzeichnis)\n  --name -n <Name>\n          Name der Anwendung und/oder des Packages\n  --dest -d <Zielpfad>\n          Pfad, in den die generierte Ausgabedatei abgelegt wird\n          (absoluter Pfad oder relativ zum aktuellen Verzeichnis)\n          Standardmäßig wird das aktuelle Arbeitsverzeichnis verwendet.\n  --temp <Verzeichnispfad>\n          Pfad eines neuen oder leeren Verzeichnisses zum Erstellen temporärer Dateien\n          (absoluter Pfad oder relativ zum aktuellen Verzeichnis)\n          Falls angegeben, wird das temporäre Verzeichnis beim Abschließen der Aufgabe\n          nicht entfernt und muss manuell entfernt werden.\n          Bei fehlender Angabe wird ein temporäres Verzeichnis erstellt und\n          beim Abschließen der Aufgabe entfernt.\n  --vendor <Zeichenfolge für Anbieter>\n          Anbieter der Anwendung\n  --verbose\n          Aktiviert Ausgabe im Verbose-Modus\n  --version\n          Gibt die Produktversion an den Outputstream aus und beendet den Vorgang.\n\nOptionen für das Erstellen des Laufzeitimages:\n  --add-modules <Modulname>[,<Modulname>...]\n          Eine per Komma (",") getrennte Liste hinzuzufügender Module\n          Diese Modulliste wird zusammen mit dem Hauptmodul (sofern angegeben)\n          als Argument --add-module an jlink übergeben.\n          Bei fehlender Angabe wird entweder nur das Hauptmodul (sofern --module\n          angegeben ist) oder das Standardset an Modulen (sofern --main-jar \n          angegeben ist) verwendet.\n          Diese Option kann mehrmals verwendet werden.\n  --module-path -p <Modulpfad>...\n          \
-Eine per {0} getrennte Pfadliste\n          Jeder Pfad ist entweder ein Verzeichnis mit Modulen oder der Pfad zu einer\n          JAR-Datei eines Moduls.\n          (Jeder Pfad ist absolut oder relativ zum aktuellen Verzeichnis.)\n          Diese Option kann mehrmals verwendet werden.\n  --jlink-options <jlink-Optionen> \n          Eine per Leerzeichen getrennte Liste mit an jlink zu übergebenden Optionen \n          Bei fehlender Angabe wird standardmäßig "--strip-native-commands \n          --strip-debug --no-man-pages --no-header-files" verwendet. \n          Diese Option kann mehrmals verwendet werden.\n  --runtime-image <Verzeichnispfad>\n          Pfad des vordefinierten Laufzeitimages, das in\n          das Anwendungsimage kopiert wird\n          (absoluter Pfad oder relativ zum aktuellen Verzeichnis)\n          Wenn --runtime-image nicht angegeben wird, führt jpackage jlink aus, um\n          das Laufzeitimage mit folgenden Optionen zu erstellen:\n          --strip-debug, --no-header-files, --no-man-pages und\n          --strip-native-commands.\n\nOptionen für das Erstellen des Anwendungsimages:\n  --input -i <Verzeichnispfad>\n          Pfad des Eingabeverzeichnisses mit den in das Package zu integrierenden Dateien\n          (absoluter Pfad oder relativ zum aktuellen Verzeichnis)\n          Alle Dateien im Eingabeverzeichnis werden in das Package für das\n          Anwendungsimage integriert.\n  --app-content <zusätzlicher Inhalt>[,<zusätzlicher Inhalt>...]\n          Eine per Komma getrennte Liste mit Pfaden zu Dateien und/oder Verzeichnissen,\n          die zur Anwendungs-Payload hinzugefügt werden sollen.\n          Diese Option kann mehrmals verwendet werden.\n\nOptionen für das Erstellen des Anwendungs-Launchers:\n  --add-launcher <Launcher-Name>=<Dateipfad>\n          Name des Launchers sowie ein Pfad zu einer Eigenschaftendatei mit\n          einer Liste von Schlüssel/Wert-Paaren\n          (absoluter Pfad oder relativ zum aktuellen Verzeichnis)\n          Die Schlüssel "module", "main-jar", "main-class", "description",\n          "arguments", "java-options", "app-version", "icon",\n          "launcher-as-service",\n          "win-console", "win-shortcut", "win-menu",\n          "linux-app-category" und "linux-shortcut" können verwendet werden.\n          Diese Optionen werden den ursprünglichen Befehlszeilenoptionen hinzugefügt\n          (oder überschreiben diese), um einen zusätzlichen, alternativen Launcher zu erstellen.\n          Der Hauptanwendungs-Launcher wird aus den Befehlszeilenoptionen\n          erstellt. Mit dieser Option können zusätzliche alternative Launcher\n          erstellt werden. Außerdem kann diese Option mehrmals verwendet werden,\n          um mehrere zusätzliche Launcher zu erstellen. \n  --arguments <Hauptklassenargumente>\n          Befehlszeilenargumente, die an die Hauptklasse übergeben werden, falls\n          keine Befehlszeilenargumente an den Launcher übergeben werden\n          Diese Option kann mehrmals verwendet werden.\n  --java-options <Java-Optionen>\n          Optionen, die an Java Runtime übergeben werden\n          Diese Option kann mehrmals verwendet werden.\n  --main-class <Klassenname>\n          Qualifizierter Name der auszuführenden Anwendungshauptklasse\n          Diese Option kann nur bei Angabe von --main-jar verwendet werden.\n  --main-jar <Haupt-JAR-Datei>\n          Die Haupt-JAR-Datei der Anwendung, die die Hauptklasse enthält\n          (angegeben als Pfad relativ zum Eingabepfad)\n          Es kann entweder die Option --module oder die Option --main-jar angegeben werden, nicht jedoch\n          beides.\n  --module -m <Modulname>[/<Hauptklasse>]\n          Das Hauptmodul (und optional die Hauptklasse) der Anwendung\n          Dieses Modul muss unter dem Modulpfad gespeichert sein.\n          Bei Angabe dieser Option wird \
-das Hauptmodul\n          im Java Runtime-Image verknüpft. Es kann entweder die Option --module oder die Option --main-jar\n          angegeben werden, nicht jedoch beides.\n{2}\nOptionen für das Erstellen des Anwendungspackages:\n  --about-url <URL>\n          URL der Homepage der Anwendung\n  --app-image <Verzeichnispfad>\n          {5}          (absoluter Pfad oder relativ zum aktuellen Verzeichnis)\n  --file-associations <Dateipfad>\n          Pfad zu einer Eigenschaftendatei mit einer Liste von Schlüssel/Wert-Paaren\n          (absoluter Pfad oder relativ zum aktuellen Verzeichnis)\n          Mit den Schlüsseln "extension", "mime-type", "icon" und "description"\n          kann die Verknüpfung beschrieben werden.\n          Diese Option kann mehrmals verwendet werden.\n  --install-dir <Verzeichnispfad>\n          {4}  --license-file <Dateipfad>\n          Pfad zur Lizenzdatei\n          (absoluter Pfad oder relativ zum aktuellen Verzeichnis)\n  --resource-dir <Verzeichnispfad>\n          Pfad zum Überschreiben von jpackage-Ressourcen\n          Symbole, Vorlagendateien und weitere Ressourcen von jpackage können\n          durch Hinzufügen von Ersetzungsressourcen zu diesem Verzeichnis überschrieben werden.\n          (absoluter Pfad oder relativ zum aktuellen Verzeichnis)\n  --runtime-image <Verzeichnispfad>\n          Pfad des zu installierenden vordefinierten Laufzeitimages\n          (absoluter Pfad oder relativ zum aktuellen Verzeichnis)\n          Option muss beim Erstellen eines Laufzeitpackages angegeben werden.\n  --launcher-as-service\n          Anforderung zum Erstellen eines Installationsprogramms, das den\n          Hauptanwendungs-Launcher als Hintergrundserviceanwendung registriert.\n\nPlattformabhängige Optionen für das Erstellen des Anwendungspackages:\n{3}
+Eine per {0} getrennte Pfadliste\n          Jeder Pfad ist entweder ein Verzeichnis mit Modulen oder der Pfad zu einer\n          JAR-Datei eines Moduls.\n          (Jeder Pfad ist absolut oder relativ zum aktuellen Verzeichnis.)\n          Diese Option kann mehrmals verwendet werden.\n  --jlink-options <jlink-Optionen> \n          Eine per Leerzeichen getrennte Liste mit an jlink zu übergebenden Optionen \n          Bei fehlender Angabe wird standardmäßig "--strip-native-commands \n          --strip-debug --no-man-pages --no-header-files" verwendet. \n          Diese Option kann mehrmals verwendet werden.\n  --runtime-image <Verzeichnispfad>\n          Pfad des vordefinierten Laufzeitimages, das in\n          das Anwendungsimage kopiert wird\n          (absoluter Pfad oder relativ zum aktuellen Verzeichnis)\n          Wenn --runtime-image nicht angegeben wird, führt jpackage jlink aus, um\n          das Laufzeitimage mit folgenden Optionen zu erstellen:\n          --strip-debug, --no-header-files, --no-man-pages und\n          --strip-native-commands.\n\nOptionen für das Erstellen des Anwendungsimages:\n  --input -i <Verzeichnispfad>\n          Pfad des Eingabeverzeichnisses mit den zu verpackenden Dateien\n          (absoluter Pfad oder relativ zum aktuellen Verzeichnis)\n          Alle Dateien im Eingabeverzeichnis werden verpackt für das\n          Anwendungsimage integriert.\n  --app-content <zusätzlicher Inhalt>[,<zusätzlicher Inhalt>...]\n          Eine per Komma getrennte Liste mit Pfaden zu Dateien und/oder Verzeichnissen,\n          die zur Anwendungs-Payload hinzugefügt werden sollen.\n          Diese Option kann mehrmals verwendet werden.\n\nOptionen für das Erstellen des Anwendungs-Launchers:\n  --add-launcher <Launcher-Name>=<Dateipfad>\n          Name des Launchers sowie ein Pfad zu einer Eigenschaftendatei mit\n          einer Liste von Schlüssel/Wert-Paaren\n          (absoluter Pfad oder relativ zum aktuellen Verzeichnis)\n          Die Schlüssel "module", "main-jar", "main-class", "description",\n          "arguments", "java-options", "app-version", "icon",\n          "launcher-as-service",\n          "win-console", "win-shortcut", "win-menu",\n          "linux-app-category" und "linux-shortcut" können verwendet werden.\n          Diese Optionen werden den ursprünglichen Befehlszeilenoptionen hinzugefügt\n          (oder überschreiben diese), um einen zusätzlichen, alternativen Launcher zu erstellen.\n          Der Hauptanwendungs-Launcher wird aus den Befehlszeilenoptionen\n          erstellt. Mit dieser Option können zusätzliche alternative Launcher\n          erstellt werden. Außerdem kann diese Option mehrmals verwendet werden,\n          um mehrere zusätzliche Launcher zu erstellen. \n  --arguments <Hauptklassenargumente>\n          Befehlszeilenargumente, die an die Hauptklasse übergeben werden, falls\n          keine Befehlszeilenargumente an den Launcher übergeben werden\n          Diese Option kann mehrmals verwendet werden.\n  --java-options <Java-Optionen>\n          Optionen, die an Java Runtime übergeben werden\n          Diese Option kann mehrmals verwendet werden.\n  --main-class <Klassenname>\n          Qualifizierter Name der auszuführenden Anwendungshauptklasse\n          Diese Option kann nur bei Angabe von --main-jar verwendet werden.\n  --main-jar <Haupt-JAR-Datei>\n          Die Haupt-JAR-Datei der Anwendung, die die Hauptklasse enthält\n          (angegeben als Pfad relativ zum Eingabepfad)\n          Es kann entweder die Option --module oder die Option --main-jar angegeben werden, nicht jedoch\n          beides.\n  --module -m <Modulname>[/<Hauptklasse>]\n          Das Hauptmodul (und optional die Hauptklasse) der Anwendung\n          Dieses Modul muss unter dem Modulpfad gespeichert sein.\n          Bei Angabe dieser Option wird das Hauptmodul\n          \
+im Java Runtime-Image verknüpft. Es kann entweder die Option --module oder die Option --main-jar\n          angegeben werden, nicht jedoch beides.\n{2}\nOptionen für das Erstellen des Anwendungspackages:\n  --about-url <URL>\n          URL der Homepage der Anwendung\n  --app-image <Verzeichnispfad>\n          {5}          (absoluter Pfad oder relativ zum aktuellen Verzeichnis)\n  --file-associations <Dateipfad>\n          Pfad zu einer Eigenschaftendatei mit einer Liste von Schlüssel/Wert-Paaren\n          (absoluter Pfad oder relativ zum aktuellen Verzeichnis)\n          Mit den Schlüsseln "extension", "mime-type", "icon" und "description"\n          kann die Verknüpfung beschrieben werden.\n          Diese Option kann mehrmals verwendet werden.\n  --install-dir <Verzeichnispfad>\n          {4}  --license-file <Dateipfad>\n          Pfad zur Lizenzdatei\n          (absoluter Pfad oder relativ zum aktuellen Verzeichnis)\n  --resource-dir <Verzeichnispfad>\n          Pfad zum Überschreiben von jpackage-Ressourcen\n          Symbole, Vorlagendateien und weitere Ressourcen von jpackage können\n          durch Hinzufügen von Ersetzungsressourcen zu diesem Verzeichnis überschrieben werden.\n          (absoluter Pfad oder relativ zum aktuellen Verzeichnis)\n  --runtime-image <Verzeichnispfad>\n          Pfad des zu installierenden vordefinierten Laufzeitimages\n          (absoluter Pfad oder relativ zum aktuellen Verzeichnis)\n          Option muss beim Erstellen eines Laufzeitpackages angegeben werden.\n  --launcher-as-service\n          Anforderung zum Erstellen eines Installationsprogramms, das den\n          Hauptanwendungs-Launcher als Hintergrundserviceanwendung registriert.\n\nPlattformabhängige Optionen für das Erstellen des Anwendungspackages:\n{3}
 
 MSG_Help_win_launcher=\nPlattformabhängige Option für das Erstellen des Anwendungs-Launchers:\n  --win-console\n          Erstellt einen Konsolen-Launcher für die Anwendung. Sollte für\n          Anwendungen angegeben werden, die Konsoleninteraktionen erfordern\n
 MSG_Help_win_install=\  --win-dir-chooser\n          Fügt ein Dialogfeld hinzu, in dem der Benutzer das Verzeichnis auswählen kann, in dem\n          das Produkt installiert wird.\n  --win-help-url <URL>\n          URL, unter der der Benutzer weitere Informationen oder technische Unterstützung erhält\n  --win-menu\n          Anforderung zum Hinzufügen einer Startmenüverknüpfung für diese Anwendung\n  --win-menu-group <Menügruppenname>\n          Startmenügruppe, in der diese Anwendung abgelegt wird\n  --win-per-user-install\n          Anforderung zum Ausführen einer Installation pro Benutzer\n  --win-shortcut\n          Anforderung zum Hinzufügen einer Desktopverknüpfung für diese Anwendung\n  --win-shortcut-prompt\n          Fügt ein Dialogfeld hinzu, in dem der Benutzer auswählen kann, ob Verknüpfungen\n          vom Installationsprogramm erstellt werden sollen.\n  --win-update-url <URL>\n          URL verfügbarer Anwendungsupdateinformationen\n  --win-upgrade-uuid <ID-Zeichenfolge>\n          UUID, die mit Upgrades für dieses Package verknüpft ist\n
diff --git a/src/jdk.jpackage/windows/classes/jdk/jpackage/internal/resources/WinResources_de.properties b/src/jdk.jpackage/windows/classes/jdk/jpackage/internal/resources/WinResources_de.properties
index 31a0ebeab24..b6561747ce0 100644
--- a/src/jdk.jpackage/windows/classes/jdk/jpackage/internal/resources/WinResources_de.properties
+++ b/src/jdk.jpackage/windows/classes/jdk/jpackage/internal/resources/WinResources_de.properties
@@ -57,6 +57,8 @@ error.unlock-resource=Aufheben der Sperre nicht erfolgreich: {0}
 error.read-wix-l10n-file=Datei {0} konnte nicht geparst werden
 error.extract-culture-from-wix-l10n-file=Kulturwert konnte nicht aus Datei {0} gelesen werden
 error.short-path-conv-fail=Kurze Version des Pfades "{0}" konnte nicht abgerufen werden
+error.missing-service-installer=Serviceinstallationsprogramm "service-installer.exe" nicht im Ressourcenverzeichnis gefunden
+error.missing-service-installer.advice=Fügen Sie das Serviceinstallationsprogramm "service-installer.exe" zum Ressourcenverzeichnis hinzu
 
 message.icon-not-ico=Das angegebene Symbol "{0}" ist keine ICO-Datei und wird nicht verwendet. Stattdessen wird das Standardsymbol verwendet.
 message.potential.windows.defender.issue=Warnung: Windows Defender verhindert eventuell die korrekte Ausführung von jpackage. Wenn ein Problem auftritt, deaktivieren Sie das Echtzeitmonitoring, oder fügen Sie einen Ausschluss für das Verzeichnis "{0}" hinzu.
diff --git a/src/jdk.jpackage/windows/classes/jdk/jpackage/internal/resources/WinResources_ja.properties b/src/jdk.jpackage/windows/classes/jdk/jpackage/internal/resources/WinResources_ja.properties
index 57391db9087..5dbf0eaa058 100644
--- a/src/jdk.jpackage/windows/classes/jdk/jpackage/internal/resources/WinResources_ja.properties
+++ b/src/jdk.jpackage/windows/classes/jdk/jpackage/internal/resources/WinResources_ja.properties
@@ -57,6 +57,8 @@ error.unlock-resource=ロック解除に失敗しました: {0}
 error.read-wix-l10n-file={0}ファイルの解析に失敗しました
 error.extract-culture-from-wix-l10n-file={0}ファイルからのカルチャの値の読取りに失敗しました
 error.short-path-conv-fail="{0}"パスの短縮バージョンの取得に失敗しました
+error.missing-service-installer=リソース・ディレクトリに'service-installer.exe'サービス・インストーラが見つかりません
+error.missing-service-installer.advice=リソース・ディレクトリに'service-installer.exe'サービス・インストーラを追加します
 
 message.icon-not-ico=指定したアイコン"{0}"はICOファイルではなく、使用されません。デフォルト・アイコンがその位置に使用されます。
 message.potential.windows.defender.issue=警告: Windows Defenderが原因でjpackageが機能しないことがあります。問題が発生した場合は、リアルタイム・モニタリングを無効にするか、ディレクトリ"{0}"の除外を追加することにより、問題に対処できます。
diff --git a/src/jdk.jpackage/windows/classes/jdk/jpackage/internal/resources/WinResources_zh_CN.properties b/src/jdk.jpackage/windows/classes/jdk/jpackage/internal/resources/WinResources_zh_CN.properties
index bd93fc5951e..2fb4e8e40e7 100644
--- a/src/jdk.jpackage/windows/classes/jdk/jpackage/internal/resources/WinResources_zh_CN.properties
+++ b/src/jdk.jpackage/windows/classes/jdk/jpackage/internal/resources/WinResources_zh_CN.properties
@@ -57,6 +57,8 @@ error.unlock-resource=无法解锁：{0}
 error.read-wix-l10n-file=无法解析 {0} 文件
 error.extract-culture-from-wix-l10n-file=无法从 {0} 文件读取文化值
 error.short-path-conv-fail=无法获取简短形式的 "{0}" 路径
+error.missing-service-installer=在资源目录中找不到 'service-installer.exe' 服务安装程序
+error.missing-service-installer.advice=将 'service-installer.exe' 服务安装程序添加到资源目录
 
 message.icon-not-ico=指定的图标 "{0}" 不是 ICO 文件, 不会使用。将使用默认图标代替。
 message.potential.windows.defender.issue=警告：Windows Defender 可能会阻止 jpackage 正常工作。如果存在问题，可以通过禁用实时监视或者为目录 "{0}" 添加排除项来解决。
diff --git a/src/jdk.jshell/share/classes/jdk/internal/jshell/tool/resources/l10n_de.properties b/src/jdk.jshell/share/classes/jdk/internal/jshell/tool/resources/l10n_de.properties
index b102638815c..243b873a596 100644
--- a/src/jdk.jshell/share/classes/jdk/internal/jshell/tool/resources/l10n_de.properties
+++ b/src/jdk.jshell/share/classes/jdk/internal/jshell/tool/resources/l10n_de.properties
@@ -306,7 +306,7 @@ help.set.mode = Erstellt einen benutzerdefinierten Feedbackmodus (optional durch
 
 help.set.prompt.summary = Legt die Prompts fest
 
-help.set.prompt = Legt die Prompts fest. Es müssen sowohl der normale als auch der Fortsetzungs-Prompt festgelegt werden:\n\n\t/set prompt <Modus> "<Prompt>" "<Fortsetzungs-Prompt>"\n\nZeigt den normalen und den Fortsetzungs-Prompt an:\n\n\t/set prompt [<Modus>]\n\nDabei gilt: <Modus> ist der Name eines zuvor definierten Feedbackmodus.\n<Prompt> und <Fortsetzungs-Prompt> sind in Anführungszeichen gesetzte Zeichenfolgen, die als Eingabe-Prompts ausgegeben werden.\nOptional können beide "%%s" enthalten. Dies wird durch die nächste Snippet-ID ersetzt.\nDer Eingabe wird unter Umständen keine ID zugewiesen, wenn es sich z.B. um einen Fehler oder Befehl handelt.\nDer Fortsetzungs-Prompt wird in einem mehrzeiligen Snippet in der zweiten und allen nachfolgenden Zeilen verwendet.\n\nBei fehlender Angabe von <Prompt> werden die aktuell festgelegten Prompts angezeigt.\nBei Angabe des <Modus> werden nur die Prompts für diesen Modus angezeigt.\nBeispiel:\n\t/set prompt mymode\nZeigt die für den Modus "mymode" festgelegten Prompts an\n
+help.set.prompt = Legt die Prompts fest. Es müssen sowohl der normale als auch der Fortsetzungs-Prompt festgelegt werden:\n\n\t/set prompt <Modus> "<Prompt>" "<Fortsetzungs-Prompt>"\n\nZeigt den normalen und den Fortsetzungs-Prompt an:\n\n\t/set prompt [<Modus>]\n\nDabei gilt: <Modus> ist der Name eines zuvor definierten Feedbackmodus.\n<Prompt> und <Fortsetzungs-Prompt> sind in Anführungszeichen gesetzte Zeichenfolgen, die als Eingabe-Prompts ausgegeben werden.\nOptional können beide "%s" enthalten. Dieses Element wird durch die nächste Snippet-ID ersetzt.\nDer Eingabe wird unter Umständen keine ID zugewiesen, wenn es sich z.B. um einen Fehler oder Befehl handelt.\nDer Fortsetzungs-Prompt wird in einem mehrzeiligen Snippet in der zweiten und allen nachfolgenden Zeilen verwendet.\n\nBei fehlender Angabe von <Prompt> werden die aktuell festgelegten Prompts angezeigt.\nBei Angabe des <Modus> werden nur die Prompts für diesen Modus angezeigt.\nBeispiel:\n\t/set prompt mymode\nZeigt die für den Modus "mymode" festgelegten Prompts an\n
 
 help.set.editor.summary =Legt den mit dem /edit-Befehl zu startenden Befehl fest
 
diff --git a/src/jdk.jshell/share/classes/jdk/internal/jshell/tool/resources/l10n_ja.properties b/src/jdk.jshell/share/classes/jdk/internal/jshell/tool/resources/l10n_ja.properties
index 87533d28371..02b92caefd9 100644
--- a/src/jdk.jshell/share/classes/jdk/internal/jshell/tool/resources/l10n_ja.properties
+++ b/src/jdk.jshell/share/classes/jdk/internal/jshell/tool/resources/l10n_ja.properties
@@ -313,7 +313,7 @@ feedback'を使用します。\n\n'-retain'オプションが使用されてい
 
 help.set.prompt.summary = プロンプトを設定します
 
-help.set.prompt = プロンプトを設定します。標準プロンプトと続行プロンプトの両方を設定する必要があります:\n\n\t/set prompt <mode> "<prompt>" "<continuation-prompt>"\n\n標準プロンプトと続行プロンプトを表示します:\n\n\t/set prompt [<mode>]\n\n<mode>は事前に定義されたフィードバック・モードの名前です。\n<prompt>および<continuation-prompt>は入力プロンプトとして出力される引用符で囲まれた文字列です。\nオプションで、両方とも、次のスニペットIDで置き換えられる'%%s'を含むことができます --\n入力した内容がそのIDに割り当てられない場合があります。たとえば、エラーまたはコマンドである場合などです。\n続行プロンプトは複数行スニペットの2行目以降で使用されます。\n\n<prompt>のない形式は、現在設定されているプロンプトを表示します。\n<mode>が指定されている場合、そのモードのプロンプトのみが表示されます。\n例:\n\t/set prompt mymode\nモードmymodeに設定されているプロンプトを表示します\n
+help.set.prompt = プロンプトを設定します。標準プロンプトと続行プロンプトの両方を設定する必要があります:\n\n\t/set prompt <mode> "<prompt>" "<continuation-prompt>"\n\n標準プロンプトと続行プロンプトを表示します:\n\n\t/set prompt [<mode>]\n\n<mode>は事前に定義されたフィードバック・モードの名前です。\n<prompt>および<continuation-prompt>は入力プロンプトとして出力される引用符で囲まれた文字列です。\nオプションで、両方とも、次のスニペットIDで置き換えられる'%s'を含むことができます --\n入力した内容がそのIDに割り当てられない場合があります。たとえば、エラーまたはコマンドである場合などです。\n続行プロンプトは複数行スニペットの2行目以降で使用されます。\n\n<prompt>のない形式は、現在設定されているプロンプトを表示します。\n<mode>が指定されている場合、そのモードのプロンプトのみが表示されます。\n例:\n\t/set prompt mymode\nモードmymodeに設定されているプロンプトを表示します\n
 
 help.set.editor.summary =/editコマンドで起動するコマンドを指定します
 
diff --git a/src/jdk.jshell/share/classes/jdk/internal/jshell/tool/resources/l10n_zh_CN.properties b/src/jdk.jshell/share/classes/jdk/internal/jshell/tool/resources/l10n_zh_CN.properties
index ee5244c75c4..ceb32d3547c 100644
--- a/src/jdk.jshell/share/classes/jdk/internal/jshell/tool/resources/l10n_zh_CN.properties
+++ b/src/jdk.jshell/share/classes/jdk/internal/jshell/tool/resources/l10n_zh_CN.properties
@@ -308,7 +308,7 @@ help.set.mode = 创建用户定义的反馈模式, 也可以选择从现有模
 
 help.set.prompt.summary = 设置提示
 
-help.set.prompt = 设置提示。必须同时设置正常提示和更多提示：\n\n\t/set prompt <模式> "<提示>" "<更多提示>"\n\n显示正常提示和更多提示：\n\n\t/set prompt [<模式>]\n\n其中 <模式> 是以前定义的反馈模式名称。\n而 <提示> 和 <更多提示> 是作为输入提示输出的带引号的字符串；\n它们均可选择性地包含 '%%s'，该变量将被替换为下一个片段 ID --\n请注意，可能无法向所输入内容分配该 ID，例如这可能是一个错误或命令。\n更多提示在多行片段的第二行以及后续行上使用。\n\n不带 <提示> 的格式显示当前设置的提示。\n指定 <模式> 时，将仅显示该模式的提示。\n示例：\n\t/set prompt mymode\n显示为模式 mymode 设置的提示\n
+help.set.prompt = 设置提示。必须同时设置正常提示和更多提示：\n\n\t/set prompt <模式> "<提示>" "<更多提示>"\n\n显示正常提示和更多提示：\n\n\t/set prompt [<模式>]\n\n其中 <模式> 是以前定义的反馈模式名称。\n而 <提示> 和 <更多提示> 是作为输入提示输出的带引号的字符串。\n它们均可包含 '%s'（可选），该变量将被替换为下一个片段 ID --\n请注意，可能无法向所输入内容分配该 ID，例如这可能是一个错误或命令。\n更多提示在多行片段的第二行以及后续行中使用。\n\n不带 <提示> 的格式显示当前设置的提示。\n指定 <模式> 时，将仅显示该模式的提示。\n示例：\n\t/set prompt mymode\n显示为模式 mymode 设置的提示\n
 
 help.set.editor.summary =指定要为 /edit 命令启动的命令