8336754: Remodel TypeAnnotation to "has" instead of "be" an Annotation

Co-authored-by: Alex Buckley <[email protected]>
Reviewed-by: asotona

Author: liach

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

@@ -37,43 +37,60 @@
 import jdk.internal.javac.PreviewFeature;
 
 /**
- * Models an annotation on a declaration.
+ * Models an {@code annotation} structure (JVMS {@jvms 4.7.16}) or part of a {@code
+ * 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.
+ * <p>
+ * Two {@code Annotation} objects should be compared using the {@link
+ * Object#equals(Object) equals} method.
+ *
+ * @apiNote
+ * For Java programs, the location of the modeled structure indicates the source code
+ * element or type (JLS {@jls 9.7.4}) on which the reconstructed annotation appears,
+ * and the annotation interface definition determines whether the reconstructed annotation has
+ * 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 TypeAnnotation
  * @see RuntimeVisibleAnnotationsAttribute
  * @see RuntimeInvisibleAnnotationsAttribute
  * @see RuntimeVisibleParameterAnnotationsAttribute
  * @see RuntimeInvisibleParameterAnnotationsAttribute
  *
- * @sealedGraph
  * @since 22
  */
 @PreviewFeature(feature = PreviewFeature.Feature.CLASSFILE_API)
 public sealed interface Annotation
-        permits TypeAnnotation, AnnotationImpl {
+        permits AnnotationImpl {
 
     /**
-     * {@return the class of the annotation}
+     * {@return the constant pool entry holding the {@linkplain Class#descriptorString
+     * descriptor string} of the annotation interface}
      */
     Utf8Entry className();
 
     /**
-     * {@return the class of the annotation, as a symbolic descriptor}
+     * {@return the annotation interface, as a symbolic descriptor}
      */
     default ClassDesc classSymbol() {
         return ClassDesc.ofDescriptor(className().stringValue());
     }
 
     /**
-     * {@return the elements of the annotation}
+     * {@return the element-value pairs of the annotation}
      */
     List<AnnotationElement> elements();
 
     /**
      * {@return an annotation}
-     * @param annotationClass the class of the annotation
-     * @param elements the elements of the annotation
+     * @param annotationClass the constant pool entry holding the descriptor string
+     *                        of the annotation interface
+     * @param elements the element-value pairs of the annotation
      */
     static Annotation of(Utf8Entry annotationClass,
                          List<AnnotationElement> elements) {
@@ -82,8 +99,9 @@ static Annotation of(Utf8Entry annotationClass,
 
     /**
      * {@return an annotation}
-     * @param annotationClass the class of the annotation
-     * @param elements the elements of the annotation
+     * @param annotationClass the constant pool entry holding the descriptor string
+     *                        of the annotation interface
+     * @param elements the element-value pairs of the annotation
      */
     static Annotation of(Utf8Entry annotationClass,
                          AnnotationElement... elements) {
@@ -92,8 +110,8 @@ static Annotation of(Utf8Entry annotationClass,
 
     /**
      * {@return an annotation}
-     * @param annotationClass the class of the annotation
-     * @param elements the elements of the annotation
+     * @param annotationClass the descriptor of the annotation interface
+     * @param elements the element-value pairs of the annotation
      */
     static Annotation of(ClassDesc annotationClass,
                          List<AnnotationElement> elements) {
@@ -102,8 +120,8 @@ static Annotation of(ClassDesc annotationClass,
 
     /**
      * {@return an annotation}
-     * @param annotationClass the class of the annotation
-     * @param elements the elements of the annotation
+     * @param annotationClass the descriptor of the annotation interface
+     * @param elements the element-value pairs of the annotation
      */
     static Annotation of(ClassDesc annotationClass,
                          AnnotationElement... elements) {

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

@@ -32,7 +32,13 @@
 import jdk.internal.javac.PreviewFeature;
 
 /**
- * Models a key-value pair of an annotation.
+ * Models an element-value pair in the {@code element_value_pairs}
+ * table in the {@code annotation} structure defined in JVMS
+ * {@jvms 4.7.16} or the {@code type_annotation} structure defined
+ * in JVMS {@jvms 4.7.20}.
+ * <p>
+ * Two {@code AnnotationElement} objects should be compared using the
+ * {@link Object#equals(Object) equals} method.
  *
  * @see Annotation
  * @see AnnotationValue
@@ -45,6 +51,12 @@ public sealed interface AnnotationElement
 
     /**
      * {@return the element name}
+     *
+     * @apiNote
+     * In Java source code, by convention, the name of the sole element in a
+     * single-element annotation interface is {@code value}. (JLS {@jls 9.6.1})
+     * This is the case for single-element annotations (JLS {@jls 9.7.3}) and
+     * container annotations for multiple annotations (JLS {@jls 9.6.3}).
      */
     Utf8Entry name();
 
@@ -54,7 +66,7 @@ public sealed interface AnnotationElement
     AnnotationValue value();
 
     /**
-     * {@return an annotation key-value pair}
+     * {@return an element-value pair}
      * @param name the name of the key
      * @param value the associated value
      */
@@ -64,7 +76,7 @@ static AnnotationElement of(Utf8Entry name,
     }
 
     /**
-     * {@return an annotation key-value pair}
+     * {@return an element-value pair}
      * @param name the name of the key
      * @param value the associated value
      */
@@ -74,119 +86,131 @@ static AnnotationElement of(String name,
     }
 
     /**
-     * {@return an annotation key-value pair for a class-valued annotation}
+     * {@return an element-value pair for a class-valued element}
      * @param name the name of the key
      * @param value the associated value
+     * @see AnnotationValue#ofClass(ClassDesc) AnnotationValue::ofClass
      */
     static AnnotationElement ofClass(String name,
                                      ClassDesc value) {
         return of(name, AnnotationValue.ofClass(value));
     }
 
     /**
-     * {@return an annotation key-value pair for a string-valued annotation}
+     * {@return an element-value pair for a string-valued element}
      * @param name the name of the key
      * @param value the associated value
+     * @see AnnotationValue#ofString(String) AnnotationValue::ofString
      */
     static AnnotationElement ofString(String name,
                                       String value) {
         return of(name, AnnotationValue.ofString(value));
     }
 
     /**
-     * {@return an annotation key-value pair for a long-valued annotation}
+     * {@return an element-value pair for a long-valued element}
      * @param name the name of the key
      * @param value the associated value
+     * @see AnnotationValue#ofLong(long) AnnotationValue::ofLong
      */
     static AnnotationElement ofLong(String name,
                                     long value) {
         return of(name, AnnotationValue.ofLong(value));
     }
 
     /**
-     * {@return an annotation key-value pair for an int-valued annotation}
+     * {@return an element-value pair for an int-valued element}
      * @param name the name of the key
      * @param value the associated value
+     * @see AnnotationValue#ofInt(int) AnnotationValue::ofInt
      */
     static AnnotationElement ofInt(String name,
                                    int value) {
         return of(name, AnnotationValue.ofInt(value));
     }
 
     /**
-     * {@return an annotation key-value pair for a char-valued annotation}
+     * {@return an element-value pair for a char-valued element}
      * @param name the name of the key
      * @param value the associated value
+     * @see AnnotationValue#ofChar(char) AnnotationValue::ofChar
      */
     static AnnotationElement ofChar(String name,
                                     char value) {
         return of(name, AnnotationValue.ofChar(value));
     }
 
     /**
-     * {@return an annotation key-value pair for a short-valued annotation}
+     * {@return an element-value pair for a short-valued element}
      * @param name the name of the key
      * @param value the associated value
+     * @see AnnotationValue#ofShort(short) AnnotationValue::ofShort
      */
     static AnnotationElement ofShort(String name,
                                      short value) {
         return of(name, AnnotationValue.ofShort(value));
     }
 
     /**
-     * {@return an annotation key-value pair for a byte-valued annotation}
+     * {@return an element-value pair for a byte-valued element}
      * @param name the name of the key
      * @param value the associated value
+     * @see AnnotationValue#ofByte(byte) AnnotationValue::ofByte
      */
     static AnnotationElement ofByte(String name,
-                                      byte value) {
+                                    byte value) {
         return of(name, AnnotationValue.ofByte(value));
     }
 
     /**
-     * {@return an annotation key-value pair for a boolean-valued annotation}
+     * {@return an element-value pair for a boolean-valued element}
      * @param name the name of the key
      * @param value the associated value
+     * @see AnnotationValue#ofBoolean(boolean) AnnotationValue::ofBoolean
      */
     static AnnotationElement ofBoolean(String name,
-                                      boolean value) {
+                                       boolean value) {
         return of(name, AnnotationValue.ofBoolean(value));
     }
 
     /**
-     * {@return an annotation key-value pair for a double-valued annotation}
+     * {@return an element-value pair for a double-valued element}
      * @param name the name of the key
      * @param value the associated value
+     * @see AnnotationValue#ofDouble(double) AnnotationValue::ofDouble
      */
     static AnnotationElement ofDouble(String name,
                                       double value) {
         return of(name, AnnotationValue.ofDouble(value));
     }
 
     /**
-     * {@return an annotation key-value pair for a float-valued annotation}
+     * {@return an element-value pair for a float-valued element}
      * @param name the name of the key
      * @param value the associated value
+     * @see AnnotationValue#ofFloat(float) AnnotationValue::ofFloat
      */
     static AnnotationElement ofFloat(String name,
                                      float value) {
         return of(name, AnnotationValue.ofFloat(value));
     }
 
     /**
-     * {@return an annotation key-value pair for an annotation-valued annotation}
+     * {@return an element-value pair for an annotation-valued element}
      * @param name the name of the key
      * @param value the associated value
+     * @see AnnotationValue#ofAnnotation AnnotationValue::ofAnnotation
      */
     static AnnotationElement ofAnnotation(String name,
                                           Annotation value) {
         return of(name, AnnotationValue.ofAnnotation(value));
     }
 
     /**
-     * {@return an annotation key-value pair for an array-valued annotation}
+     * {@return an element-value pair for an array-valued element}
      * @param name the name of the key
      * @param values the associated values
+     * @see AnnotationValue#ofArray(AnnotationValue...) AnnotationValue::ofArray
      */
     static AnnotationElement ofArray(String name,
                                      AnnotationValue... values) {