Review comments, also simplify Attribute

Author: liach

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

@@ -35,28 +35,19 @@
  * Attributes exist on certain {@code class} file structures modeled by {@link
  * AttributedElement}, which provides basic read access to the attributes.
  * <p>
- * 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}.
+ * 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>
- * Many attributes implement {@link ClassElement}, {@link FieldElement}, {@link
- * MethodElement}, or {@link CodeElement} interfaces.  They can be written to
- * the {@code class} file as part of those enclosing structures via {@link
- * ClassBuilder#with}, {@link FieldBuilder#with}, {@link MethodBuilder#with}, or
- * {@link CodeBuilder#with}.  If an attribute does not {@linkplain
- * AttributeMapper#allowMultiple allow multiple instances} in one structure,
- * the last supplied instance appears on the built structure.  These interfaces
- * also allow such attributes to be delivered in the traversal of corresponding
- * {@link CompoundElement}; the exact rules are specified in the modeling
- * subinterfaces.
- * <p>
- * Some attributes, like {@link BootstrapMethodsAttribute BootstrapMethods} and
- * {@link LocalVariableTableAttribute LocalVariableTable}, are present in
- * structures like {@link ClassModel} or {@link CodeModel}, but they do not
- * implement {@link ClassElement} or {@link CodeElement}.  Such attributes are
- * usually modeled as an integral part to the declaring structure, specified
- * in the modeling subinterfaces.
+ * 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

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

@@ -79,7 +79,7 @@ public sealed interface InnerClassInfo
      * {@return a set of flag enums denoting access permissions and properties
      * of the nested class}
      *
-     * @throws IllegalArgumentException if the flags mask has any unused bit set
+     * @throws IllegalArgumentException if the flags mask has any undefined bit set
      * @see Class#accessFlags()
      * @see AccessFlag.Location#INNER_CLASS
      */

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

@@ -63,7 +63,7 @@ public sealed interface MethodParameterInfo
     /**
      * {@return the access flags, as a set of flag enums}
      *
-     * @throws IllegalArgumentException if the flags mask has any unused bit set
+     * @throws IllegalArgumentException if the flags mask has any undefined bit set
      * @see Parameter#accessFlags()
      * @see AccessFlag.Location#METHOD_PARAMETER
      */

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

@@ -91,7 +91,7 @@ public sealed interface ModuleAttribute
     /**
      * {@return the module flags of the module, as a set of enum constants}
      *
-     * @throws IllegalArgumentException if the flags mask has any unused bit set
+     * @throws IllegalArgumentException if the flags mask has any undefined bit set
      * @see ModuleDescriptor#accessFlags()
      * @see AccessFlag.Location#MODULE
      */

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

@@ -68,7 +68,7 @@ public sealed interface ModuleExportInfo
      * {@return the flags associated with this export declaration, as a set of
      * flag enums}
      *
-     * @throws IllegalArgumentException if the flags mask has any unused bit set
+     * @throws IllegalArgumentException if the flags mask has any undefined bit set
      * @see ModuleDescriptor.Exports#accessFlags()
      * @see AccessFlag.Location#MODULE_EXPORTS
      */

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

@@ -74,7 +74,7 @@ public sealed interface ModuleOpenInfo
      * {@return the flags associated with this open declaration, as a set of
      * flag enums}
      *
-     * @throws IllegalArgumentException if the flags mask has any unused bit set
+     * @throws IllegalArgumentException if the flags mask has any undefined bit set
      * @see ModuleDescriptor.Opens#accessFlags()
      * @see AccessFlag.Location#MODULE_OPENS
      */

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

@@ -65,7 +65,7 @@ public sealed interface ModuleRequireInfo
      * {@return the flags associated with this require declaration, as a set of
      * flag enums}
      *
-     * @throws IllegalArgumentException if the flags mask has any unused bit set
+     * @throws IllegalArgumentException if the flags mask has any undefined bit set
      * @see ModuleDescriptor.Requires#accessFlags()
      * @see AccessFlag.Location#MODULE_REQUIRES
      */

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

@@ -26,15 +26,17 @@
 /**
  * <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 specific {@code class} file attributes.
- * General and user-defined attributes reside in {@link java.lang.classfile}, including {@link Attributes}, {@link
- * AttributeMapper}, and {@link CustomAttribute}.
+ * 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>
+ * <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
@@ -57,7 +59,7 @@
  * 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>
+ * <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