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

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,40 @@
 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>
+ * 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.
  *
+ * @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 +87,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();