8342465: Improve API documentation for java.lang.classfile

Reviewed-by: asotona
Backport-of: 1d8ccb8

Author: liach

src/java.base/share/classes/java/lang/classfile/AccessFlags.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,37 +30,70 @@
 import jdk.internal.classfile.impl.AccessFlagsImpl;
 
 /**
- * Models the access flags for a class, method, or field.  Delivered as a
- * {@link ClassElement}, {@link FieldElement}, or {@link MethodElement}
- * when traversing the corresponding model type.
+ * Models the access flags for a class, method, or field.  The access flags
+ * appears exactly once in each class, method, or field; a {@link
+ * ClassBuilder} and a {@link FieldBuilder} chooses an unspecified default value
+ * if access flags are not provided, and a {@link MethodBuilder} is always
+ * created with access flags.
+ * <p>
+ * {@code AccessFlags} cannot be created via a factory method directly; it can
+ * be created with {@code withFlags} methods on the respective builders.
+ * <p>
+ * A {@link MethodBuilder} throws an {@link IllegalArgumentException} if it is
+ * supplied an {@code AccessFlags} object that changes the preexisting
+ * {@link ClassFile#ACC_STATIC ACC_STATIC} flag of the builder, because the
+ * access flag change may invalidate previously supplied data to the builder.
  *
+ * @apiNote
+ * The access flags of classes, methods, and fields are modeled as a standalone
+ * object to support streaming as elements for {@link ClassFileTransform}.
+ * Other access flags are not elements of a {@link CompoundElement} and thus not
+ * modeled by {@code AccessFlags}; they provide their own {@code flagsMask},
+ * {@code flags}, and {@code has} methods.
+ *
+ * @see ClassModel#flags()
+ * @see FieldModel#flags()
+ * @see MethodModel#flags()
+ * @see ClassBuilder#withFlags
+ * @see FieldBuilder#withFlags
+ * @see MethodBuilder#withFlags
  * @since 24
  */
 public sealed interface AccessFlags
         extends ClassElement, MethodElement, FieldElement
         permits AccessFlagsImpl {
 
     /**
-     * {@return the access flags, as a bit mask}
+     * {@return the access flags, as a bit mask}  It is in the range of unsigned
+     * short, {@code [0, 0xFFFF]}.
      */
     int flagsMask();
 
     /**
-     * {@return the access flags}
+     * {@return the access flags, as a set of flag enums}
+     *
+     * @throws IllegalArgumentException if the flags mask has any undefined bit set
+     * @see #location()
      */
     Set<AccessFlag> flags();
 
     /**
-     * {@return whether the specified flag is present}  The specified flag
-     * should be a valid flag for the classfile location associated with this
-     * element otherwise false is returned.
+     * {@return whether the specified flag is set}  If the specified flag
+     * is not available to this {@linkplain #location() location}, returns
+     * {@code false}.
+     *
      * @param flag the flag to test
+     * @see #location()
      */
     boolean has(AccessFlag flag);
 
     /**
-     * {@return the classfile location for this element, which is either class,
-     * method, or field}
+     * {@return the {@code class} file location for this element, which is
+     * either class, method, or field}
+     *
+     * @see AccessFlag.Location#CLASS
+     * @see AccessFlag.Location#FIELD
+     * @see AccessFlag.Location#METHOD
      */
     AccessFlag.Location location();
 }

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

@@ -54,7 +54,7 @@ public sealed interface AnnotationValue {
 
     /**
      * Models an annotation value of an element-value pair.
-     * The {@linkplain #tag tag} of this value is {@value TAG_ANNOTATION}.
+     * The {@linkplain #tag tag} of this value is {@value %c TAG_ANNOTATION}.
      *
      * @since 24
      */
@@ -66,7 +66,7 @@ sealed interface OfAnnotation extends AnnotationValue
 
     /**
      * Models an array value of an element-value pair.
-     * The {@linkplain #tag tag} of this value is {@value TAG_ARRAY}.
+     * The {@linkplain #tag tag} of this value is {@value %c TAG_ARRAY}.
      *
      * @since 24
      */
@@ -122,7 +122,7 @@ sealed interface OfConstant extends AnnotationValue {
 
     /**
      * Models a string value of an element-value pair.
-     * The {@linkplain #tag tag} of this value is {@value TAG_STRING}.
+     * The {@linkplain #tag tag} of this value is {@value %c TAG_STRING}.
      *
      * @since 24
      */
@@ -149,7 +149,7 @@ default String resolvedValue() {
 
     /**
      * Models a double value of an element-value pair.
-     * The {@linkplain #tag tag} of this value is {@value TAG_DOUBLE}.
+     * The {@linkplain #tag tag} of this value is {@value %c TAG_DOUBLE}.
      *
      * @since 24
      */
@@ -176,7 +176,7 @@ default Double resolvedValue() {
 
     /**
      * Models a float value of an element-value pair.
-     * The {@linkplain #tag tag} of this value is {@value TAG_FLOAT}.
+     * The {@linkplain #tag tag} of this value is {@value %c TAG_FLOAT}.
      *
      * @since 24
      */
@@ -203,7 +203,7 @@ default Float resolvedValue() {
 
     /**
      * Models a long value of an element-value pair.
-     * The {@linkplain #tag tag} of this value is {@value TAG_LONG}.
+     * The {@linkplain #tag tag} of this value is {@value %c TAG_LONG}.
      *
      * @since 24
      */
@@ -230,7 +230,7 @@ default Long resolvedValue() {
 
     /**
      * Models an int value of an element-value pair.
-     * The {@linkplain #tag tag} of this value is {@value TAG_INT}.
+     * The {@linkplain #tag tag} of this value is {@value %c TAG_INT}.
      *
      * @since 24
      */
@@ -257,7 +257,7 @@ default Integer resolvedValue() {
 
     /**
      * Models a short value of an element-value pair.
-     * The {@linkplain #tag tag} of this value is {@value TAG_SHORT}.
+     * The {@linkplain #tag tag} of this value is {@value %c TAG_SHORT}.
      *
      * @since 24
      */
@@ -287,7 +287,7 @@ default Short resolvedValue() {
 
     /**
      * Models a char value of an element-value pair.
-     * The {@linkplain #tag tag} of this value is {@value TAG_CHAR}.
+     * The {@linkplain #tag tag} of this value is {@value %c TAG_CHAR}.
      *
      * @since 24
      */
@@ -317,7 +317,7 @@ default Character resolvedValue() {
 
     /**
      * Models a byte value of an element-value pair.
-     * The {@linkplain #tag tag} of this value is {@value TAG_BYTE}.
+     * The {@linkplain #tag tag} of this value is {@value %c TAG_BYTE}.
      *
      * @since 24
      */
@@ -347,7 +347,7 @@ default Byte resolvedValue() {
 
     /**
      * Models a boolean value of an element-value pair.
-     * The {@linkplain #tag tag} of this value is {@value TAG_BOOLEAN}.
+     * The {@linkplain #tag tag} of this value is {@value %c TAG_BOOLEAN}.
      *
      * @since 24
      */
@@ -377,7 +377,7 @@ default Boolean resolvedValue() {
 
     /**
      * Models a class value of an element-value pair.
-     * The {@linkplain #tag tag} of this value is {@value TAG_CLASS}.
+     * The {@linkplain #tag tag} of this value is {@value %c TAG_CLASS}.
      *
      * @since 24
      */
@@ -394,7 +394,7 @@ default ClassDesc classSymbol() {
 
     /**
      * Models an enum value of an element-value pair.
-     * The {@linkplain #tag tag} of this value is {@value TAG_ENUM}.
+     * The {@linkplain #tag tag} of this value is {@value %c TAG_ENUM}.
      *
      * @since 24
      */

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

@@ -39,7 +39,14 @@
  * 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.
+ * <p>
+ * Unless otherwise specified, most attributes that can be discovered in a
+ * {@link CompoundElement} implements the corresponding {@linkplain
+ * ClassFileElement##membership membership subinterface} of {@code
+ * ClassFileElement}, and can be sent to a {@link ClassFileBuilder} to be
+ * integrated into the built structure.
  *
+ * @see java.lang.classfile.attribute
  * @jvms 4.7 Attributes
  * @sealedGraph
  * @since 24