improve extension API documentation and resolve some open questions

api/src/main/java/jakarta/enterprise/inject/build/compatible/spi/AnnotationBuilderFactory.java

@@ -5,8 +5,10 @@
 import java.lang.annotation.Annotation;
 
 /**
- * Service provider interface that supports creating {@link AnnotationBuilder}.
+ * Supports instantiating {@link AnnotationBuilder}.
  * Should not be called directly by users; the static methods on {@link AnnotationBuilder} are preferred.
+ *
+ * @since 4.0
  */
 public interface AnnotationBuilderFactory {
     /**

api/src/main/java/jakarta/enterprise/inject/build/compatible/spi/BeanInfo.java

@@ -8,18 +8,34 @@
 import java.util.Collection;
 
 /**
- * Provides read-only information about a bean.
+ * Beans are:
+ *
+ * <ul>
+ * <li>managed beans</li>
+ * <li>beans defined by producer methods</li>
+ * <li>beans defined by producer fields</li>
+ * <li>synthetic beans</li>
+ * </ul>
+ *
+ * Managed beans are also known as class-based beans, while beans defined by producer methods
+ * and producer fields are together also known as producer-based beans.
+ * <p>
+ * Class-based and producer-based beans directly correspond to a declaration in program source code.
+ * Synthetic beans don't and are instead defined through other mechanisms, such as
+ * {@linkplain BuildCompatibleExtension extensions}.
+ *
+ * @since 4.0
  */
 public interface BeanInfo {
     /**
-     * Returns the {@link ScopeInfo scope} of this bean.
+     * Returns the {@linkplain ScopeInfo scope} of this bean.
      *
-     * @return the {@link ScopeInfo scope} of this bean, never {@code null}
+     * @return the {@linkplain ScopeInfo scope} of this bean, never {@code null}
      */
     ScopeInfo scope();
 
     /**
-     * Returns a collection of all {@link Type type}s of this bean.
+     * Returns a collection of all {@linkplain Type types} of this bean.
      *
      * @return immutable collection of bean types, never {@code null}
      */
@@ -44,7 +60,7 @@ public interface BeanInfo {
     ClassInfo declaringClass();
 
     /**
-     * Returns whether this bean is a managed bean, sometimes also called class-based bean.
+     * Returns whether this bean is a managed bean, also known as class-based bean.
      *
      * @return whether this bean is a managed bean
      */
@@ -66,43 +82,44 @@ public interface BeanInfo {
 
     /**
      * Returns whether this bean is synthetic. In other words, whether this bean
-     * doesn't correspond to a declaration in some source code and was created
+     * doesn't correspond to a declaration in program source code and was created
      * through other means (e.g. using an extension).
      *
      * @return whether this bean is synthetic
      */
     boolean isSynthetic();
 
     /**
-     * Returns the producer {@link MethodInfo method} that defines this bean.
+     * Returns the producer {@linkplain MethodInfo method} that defines this bean.
      * Returns {@code null} if this bean isn't defined by a producer method.
      *
      * @return producer method that defines this bean, or {@code null} if this bean isn't defined by a producer method
      */
     MethodInfo producerMethod();
 
     /**
-     * Returns the producer {@link FieldInfo field} that defines this bean.
+     * Returns the producer {@linkplain FieldInfo field} that defines this bean.
      * Returns {@code null} if this bean isn't defined by a producer field.
      *
      * @return producer field that defines this bean, or {@code null} if this bean isn't defined by a producer field
      */
     FieldInfo producerField();
 
     /**
-     * Returns whether this bean is an {@link jakarta.enterprise.inject.Alternative alternative}.
+     * Returns whether this bean is an {@linkplain jakarta.enterprise.inject.Alternative alternative}.
      *
-     * @return whether this bean is an {@link jakarta.enterprise.inject.Alternative alternative}
+     * @return whether this bean is an {@linkplain jakarta.enterprise.inject.Alternative alternative}
      */
     boolean isAlternative();
 
     /**
-     * Returns the {@link jakarta.annotation.Priority priority} of this alternative bean.
+     * Returns the {@linkplain jakarta.annotation.Priority priority} of this alternative bean.
      * If this bean is not an alternative, the return value is undefined.
      *
      * @return the priority of this alternative bean
      * @see #isAlternative()
      */
+    // TODO maybe specify that if this bean is not an alternative, this returns 0?
     int priority();
 
     /**
@@ -115,16 +132,16 @@ public interface BeanInfo {
     String getName();
 
     /**
-     * Returns the {@link DisposerInfo disposer method} of this producer-based bean.
+     * Returns the {@linkplain DisposerInfo disposer} method of this producer-based bean.
      * Returns {@code null} if this bean is not a defined by a producer method or a producer field,
      * or if this producer-based bean doesn't have a corresponding disposer method.
      *
-     * @return the {@link DisposerInfo disposer}, or {@code null} if this bean doesn't have a disposer
+     * @return the {@linkplain DisposerInfo disposer}, or {@code null} if this bean doesn't have a disposer
      */
     DisposerInfo disposer();
 
     /**
-     * Returns a collection of this bean's {@link StereotypeInfo stereotype}s.
+     * Returns a collection of this bean's {@linkplain StereotypeInfo stereotypes}.
      *
      * @return immutable collection of stereotypes, never {@code null}
      */
@@ -133,7 +150,7 @@ public interface BeanInfo {
     // TODO interceptors?
 
     /**
-     * Returns a collection of this bean's {@link InjectionPointInfo injection point}s.
+     * Returns a collection of this bean's {@linkplain InjectionPointInfo injection points}.
      *
      * @return immutable collection of injection points, never {@code null}
      */

api/src/main/java/jakarta/enterprise/inject/build/compatible/spi/BuildCompatibleExtension.java

@@ -29,6 +29,8 @@
  * <p>
  * Extension classes can be annotated {@link SkipIfPortableExtensionPresent @SkipIfPortablExtensionPresent}
  * when they are supposed to be ignored in presence of a given portable extension.
+ *
+ * @since 4.0
  */
 public interface BuildCompatibleExtension {
     // TODO rename? "build compatible" is too long; ideally, we'd have a single word that describes

api/src/main/java/jakarta/enterprise/inject/build/compatible/spi/BuildServices.java

@@ -3,11 +3,13 @@
 import jakarta.enterprise.inject.spi.Prioritized;
 
 /**
- * Service facade for various services needed by {@link BuildCompatibleExtension} implementations.
+ * Service provider interface for various services needed by {@link BuildCompatibleExtension} implementations.
+ *
+ * @since 4.0
  */
 public interface BuildServices extends Prioritized {
     /**
-     * @return The {@link AnnotationBuilderFactory} instance, never {@code null}
+     * @return the {@link AnnotationBuilderFactory} instance, never {@code null}
      */
     AnnotationBuilderFactory annotationBuilderFactory();
 }

api/src/main/java/jakarta/enterprise/inject/build/compatible/spi/ClassConfig.java

@@ -10,10 +10,14 @@
  * are only seen by the CDI container.
  *
  * @see Enhancement
+ * @since 4.0
  */
 public interface ClassConfig extends DeclarationConfig<ClassConfig> {
+    // TODO now that ClassInfo also returns inherited annotations, need to think about what happens
+    //  when we add an annotation that collides with an inherited one, or when we remove an inherited annotation
+
     /**
-     * Returns the {@link ClassInfo read-only information} about this transformed class.
+     * Returns the {@link ClassInfo} corresponding to this transformed class.
      *
      * @return the {@link ClassInfo} corresponding to this transformed class, never {@code null}
      */
@@ -25,22 +29,22 @@ public interface ClassConfig extends DeclarationConfig<ClassConfig> {
      *
      * @return immutable collection of {@link MethodConfig} objects, never {@code null}
      */
-    // TODO specify whether inherited constructors are also included
+    // TODO specify whether inherited constructors are also included; probably mirror what ClassInfo does
     Collection<MethodConfig> constructors();
 
     /**
      * Returns a collection of {@link MethodConfig} objects for each method of this class.
      *
      * @return immutable collection of {@link MethodConfig} objects, never {@code null}
      */
-    // TODO specify whether inherited methods are also included
+    // TODO specify whether inherited methods are also included; probably mirror what ClassInfo does
     Collection<MethodConfig> methods();
 
     /**
      * Returns a collection of {@link FieldConfig} objects for each field of this class.
      *
      * @return immutable collection of {@link FieldConfig} objects, never {@code null}
      */
-    // TODO specify whether inherited fields are also included
+    // TODO specify whether inherited fields are also included; probably mirror what ClassInfo does
     Collection<FieldConfig> fields();
 }

api/src/main/java/jakarta/enterprise/inject/build/compatible/spi/DeclarationConfig.java

@@ -12,10 +12,11 @@
  * are only seen by the CDI container.
  *
  * @see Enhancement
+ * @since 4.0
  */
 public interface DeclarationConfig<THIS extends DeclarationConfig<THIS>> {
     /**
-     * Returns the {@link DeclarationInfo read-only information} about this transformed declaration.
+     * Returns the {@link DeclarationInfo} corresponding to this transformed declaration.
      *
      * @return the {@link DeclarationInfo} corresponding to this transformed declaration, never {@code null}
      */

api/src/main/java/jakarta/enterprise/inject/build/compatible/spi/Discovery.java

@@ -14,9 +14,11 @@
  * <ul>
  * <li>{@link ScannedClasses}: to register classes to be scanned during bean discovery</li>
  * <li>{@link MetaAnnotations}: to register custom meta-annotations:
- *   qualifiers, interceptor bindings, stereotypes and scopes</li>
+ * qualifiers, interceptor bindings, stereotypes and scopes</li>
  * <li>{@link Messages}: to produce log messages and validation errors</li>
  * </ul>
+ *
+ * @since 4.0
  */
 @Target(ElementType.METHOD)
 @Retention(RetentionPolicy.RUNTIME)

api/src/main/java/jakarta/enterprise/inject/build/compatible/spi/DisposerInfo.java

@@ -4,20 +4,23 @@
 import jakarta.enterprise.lang.model.declarations.ParameterInfo;
 
 /**
- * Provides read-only information about a disposer method.
+ * Disposer methods may exist for producer-based beans. Each disposer method
+ * has a {@linkplain #disposedParameter() disposed parameter}.
+ *
+ * @since 4.0
  */
 public interface DisposerInfo {
     /**
-     * Returns this disposer method represented as {@link MethodInfo}.
+     * Returns the {@linkplain MethodInfo declaration} of this disposer method.
      *
-     * @return the {@link MethodInfo}, never {@code null}
+     * @return the {@linkplain MethodInfo declaration} of this disposer method, never {@code null}
      */
     MethodInfo disposerMethod();
 
     /**
-     * Returns the disposed parameter of this disposer method.
+     * Returns the {@linkplain ParameterInfo declaration} of the disposed parameter of this disposer method.
      *
-     * @return the disposed parameter, never {@code null}
+     * @return the {@linkplain ParameterInfo declaration} of the disposed parameter of this disposer method, never {@code null}
      */
     ParameterInfo disposedParameter();
 }

api/src/main/java/jakarta/enterprise/inject/build/compatible/spi/Enhancement.java

@@ -21,11 +21,13 @@
  * You can also declare a parameter of type {@link Messages Messages} to produce log messages and validation errors.
  * <p>
  * If you need to create instances of {@link jakarta.enterprise.lang.model.types.Type Type}, you can also declare
- * a parameter of type {@link Types}. It provides factory methods for the void type, primitive types,
+ * a parameter of type {@link Types}. It provides factory methods for the void pseudo-type, primitive types,
  * class types, array types, parameterized types and wildcard types.
  * <p>
  * If you need to create instances of {@link jakarta.enterprise.lang.model.AnnotationInfo AnnotationInfo},
  * use {@link AnnotationBuilder}.
+ *
+ * @since 4.0
  */
 @Target(ElementType.METHOD)
 @Retention(RetentionPolicy.RUNTIME)

api/src/main/java/jakarta/enterprise/inject/build/compatible/spi/ExactType.java

@@ -23,6 +23,8 @@
  * If the {@code annotatedWith} attribute is set, only types that use given annotations are considered.
  * The annotations can appear on the type, or on any member of the type, or any parameter of any member of the type.
  * This is ignored for {@code @Processing}.
+ *
+ * @since 4.0
  */
 @Target(ElementType.METHOD)
 @Retention(RetentionPolicy.RUNTIME)

api/src/main/java/jakarta/enterprise/inject/build/compatible/spi/FieldConfig.java

@@ -8,10 +8,11 @@
  * are only seen by the CDI container.
  *
  * @see Enhancement
+ * @since 4.0
  */
 public interface FieldConfig extends DeclarationConfig<FieldConfig> {
     /**
-     * Returns the {@link FieldInfo read-only information} about this transformed field.
+     * Returns the {@link FieldInfo} corresponding to this transformed field.
      *
      * @return the {@link FieldInfo} corresponding to this transformed field, never {@code null}
      */

api/src/main/java/jakarta/enterprise/inject/build/compatible/spi/InjectionPointInfo.java

@@ -6,7 +6,10 @@
 import java.util.Collection;
 
 /**
- * Provides read-only information about an injection point.
+ * An injection point defined on some bean. Injection points may be fields
+ * or method parameters.
+ *
+ * @since 4.0
  */
 public interface InjectionPointInfo {
     /**

api/src/main/java/jakarta/enterprise/inject/build/compatible/spi/Messages.java

@@ -5,6 +5,8 @@
 /**
  * Allows logging and producing errors during {@link BuildCompatibleExtension} execution.
  * If an error is produced, application deployment will fail.
+ *
+ * @since 4.0
  */
 public interface Messages {
     /**