8342465: Improve API documentation for java.lang.classfile

Reviewed-by: asotona, darcy

src/java.base/share/classes/java/lang/classfile/ClassFileBuilder.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,17 +31,36 @@ import java.util.function.Consumer;
 import jdk.internal.classfile.impl.TransformImpl;
 
 /**
- * A builder for a classfile or portion of a classfile.  Builders are rarely
- * created directly; they are passed to handlers by methods such as
- * {@link ClassFile#build(ClassDesc, Consumer)} or to transforms.
- * Elements of the newly built entity can be specified
- * abstractly (by passing a {@link ClassFileElement} to {@link #with(ClassFileElement)}
- * or concretely by calling the various {@code withXxx} methods.
+ * A builder for a {@link CompoundElement}, which accepts the member elements
+ * to be integrated into the built structure.  Builders are usually passed as
+ * an argument to {@link Consumer} handlers, such as in {@link
+ * ClassFile#build(ClassDesc, Consumer)}.  The handlers should deliver elements
+ * to a builder similar to how a {@link CompoundElement} traverses its member
+ * elements.
+ * <p>
+ * The basic way a builder accepts elements is through {@link #with}, which
+ * supports call chaining.  Concrete subtypes of builders usually define extra
+ * methods to define elements directly to the builder, such as {@link
+ * ClassBuilder#withFlags(int)} or {@link CodeBuilder#aload(int)}.
+ * <p>
+ * Whether a member element can appear multiple times in a compound structure
+ * affects the behavior of the element in {@code ClassFileBuilder}s.  If an
+ * element can appear at most once but multiple instances are supplied to a
+ * {@code ClassFileBuilder}, the last supplied instance appears on the built
+ * structure.  If an element appears exactly once but no instance is supplied,
+ * an unspecified default value element may be used in that structure.
+ * <p>
+ * Due to restrictions of the {@code class} file format, certain member elements
+ * that can be modeled by the API cannot be represented in the built structure
+ * under specific circumstances.  Passing such elements to the builder causes
+ * {@link IllegalArgumentException}.  Some {@link ClassFile.Option}s control
+ * whether such elements should be altered or dropped to produce valid {@code
+ * class} files.
  *
- * @param <E> the element type
- * @param <B> the builder type
+ * @param <E> the member element type
+ * @param <B> the self type of this builder
+ * @see CompoundElement
  * @see ClassFileTransform
- *
  * @sealedGraph
  * @since 24
  */
@@ -49,8 +68,15 @@ public sealed interface ClassFileBuilder<E extends ClassFileElement, B extends C
         extends Consumer<E> permits ClassBuilder, FieldBuilder, MethodBuilder, CodeBuilder {
 
     /**
-     * Integrate the {@link ClassFileElement} into the entity being built.
-     * @param e the element
+     * Integrates the member element into the structure being built.
+     *
+     * @apiNote
+     * This method exists to implement {@link Consumer}; users can use {@link
+     * #with} for call chaining.
+     *
+     * @param e the member element
+     * @throws IllegalArgumentException if the member element cannot be
+     *         represented in the {@code class} file format
      */
     @Override
     default void accept(E e) {
@@ -58,9 +84,12 @@ public sealed interface ClassFileBuilder<E extends ClassFileElement, B extends C
     }
 
     /**
-     * Integrate the {@link ClassFileElement} into the entity being built.
-     * @param e the element
+     * Integrates the member element into the structure being built.
+     *
+     * @param e the member element
      * @return this builder
+     * @throws IllegalArgumentException if the member element cannot be
+     *         represented in the {@code class} file format
      */
     B with(E e);
 
@@ -70,10 +99,29 @@ public sealed interface ClassFileBuilder<E extends ClassFileElement, B extends C
     ConstantPoolBuilder constantPool();
 
     /**
-     * Apply a transform to a model, directing results to this builder.
-     * @param model the model to transform
+     * Applies a transform to a compound structure, directing results to this
+     * builder.
+     * <p>
+     * The transform will receive each element of the compound structure, as
+     * well as this builder for building the structure.  The transform is free
+     * to preserve, remove, or replace elements as it sees fit.
+     * <p>
+     * A builder can run multiple transforms against different compound
+     * structures, integrating member elements of different origins.
+     *
+     * @apiNote
+     * Many subinterfaces have methods like {@link ClassBuilder#transformMethod}
+     * or {@link MethodBuilder#transformCode}.  However, calling them is
+     * fundamentally different from calling this method: those methods call the
+     * {@code transform} on the child builders instead of on itself.  For
+     * example, {@code classBuilder.transformMethod} calls {@code
+     * methodBuilder.transform} with a new method builder instead of calling
+     * {@code classBuilder.transform} on itself.
+     *
+     * @param model the structure to transform
      * @param transform the transform to apply
      * @return this builder
+     * @see ClassFileTransform
      */
     default B transform(CompoundElement<E> model, ClassFileTransform<?, E, B> transform) {
         @SuppressWarnings("unchecked")