8342466: Improve API documentation for java.lang.classfile.attribute

8347762: ClassFile attribute specification refers to non-SE modules

Reviewed-by: asotona
Backport-of: 973c630

Author: liach

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());

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

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

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();