extension API improvements

That is specifically:

- change the `*Config` types to no longer inherit from the corresponding
  `*Info` types; instead, they provide an `info()` method
- rename `AnnotationConfig` to `DeclarationConfig` for symmetry
  between `*Info` and `*Config` types
- change the annotation transformation methods on `DeclarationConfig`
  to return `this` to allow fluent usage
- allow additional parameter types for `@Enhancement` methods:
  `DeclarationConfig`, `DeclarationInfo`, `ClassInfo`, `MethodInfo`,
  and `FieldInfo` (`*Info` types are useful when only collecting
  information during `@Enhancement`, not modifying anything)
- remove useless type parameters from `AnnotationInfo`, `ClassInfo`,
  `MethodInfo`, `FieldInfo`, `ClassConfig`, `MethodConfig`, `FieldConfig`,
  `BeanInfo`, and `ObserverInfo`; the `SyntheticBeanBuilder` type
  still has a type parameter, which remains an open question
- add a lot of documentation

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

@@ -35,7 +35,7 @@ static AnnotationBuilder of(Class<? extends Annotation> annotationType) {
      * @param annotationType the annotation type, must not be {@code null}
      * @return a new {@code AnnotationBuilder}
      */
-    static AnnotationBuilder of(ClassInfo<?> annotationType) {
+    static AnnotationBuilder of(ClassInfo annotationType) {
         return AnnotationBuilderFactoryResolver.get().create(annotationType);
     }
 
@@ -278,7 +278,7 @@ default AnnotationBuilder value(Class<? extends Enum<?>> enumType, String... enu
      * @param enumValue name of the enum constant, must not be {@code null}
      * @return this {@code AnnotationBuilder}
      */
-    default AnnotationBuilder value(ClassInfo<?> enumType, String enumValue) {
+    default AnnotationBuilder value(ClassInfo enumType, String enumValue) {
         return member(AnnotationInfo.MEMBER_VALUE, enumType, enumValue);
     }
 
@@ -289,7 +289,7 @@ default AnnotationBuilder value(ClassInfo<?> enumType, String enumValue) {
      * @param enumValues names of the enum constants, must not be {@code null} or contain {@code null}
      * @return this {@code AnnotationBuilder}
      */
-    default AnnotationBuilder value(ClassInfo<?> enumType, String... enumValues) {
+    default AnnotationBuilder value(ClassInfo enumType, String... enumValues) {
         return member(AnnotationInfo.MEMBER_VALUE, enumType, enumValues);
     }
 
@@ -319,7 +319,7 @@ default AnnotationBuilder value(Class<?>... values) {
      * @param value the class value, must not be {@code null}
      * @return this {@code AnnotationBuilder}
      */
-    default AnnotationBuilder value(ClassInfo<?> value) {
+    default AnnotationBuilder value(ClassInfo value) {
         return member(AnnotationInfo.MEMBER_VALUE, value);
     }
 
@@ -329,7 +329,7 @@ default AnnotationBuilder value(ClassInfo<?> value) {
      * @param values the class array, must not be {@code null} or contain {@code null}
      * @return this {@code AnnotationBuilder}
      */
-    default AnnotationBuilder value(ClassInfo<?>... values) {
+    default AnnotationBuilder value(ClassInfo... values) {
         return member(AnnotationInfo.MEMBER_VALUE, values);
     }
 
@@ -379,7 +379,7 @@ default AnnotationBuilder value(Type... values) {
      * @param value the annotation value, must not be {@code null}
      * @return this {@code AnnotationBuilder}
      */
-    default AnnotationBuilder value(AnnotationInfo<?> value) {
+    default AnnotationBuilder value(AnnotationInfo value) {
         return member(AnnotationInfo.MEMBER_VALUE, value);
     }
 
@@ -389,7 +389,7 @@ default AnnotationBuilder value(AnnotationInfo<?> value) {
      * @param values the annotation array, must not be {@code null} or contain {@code null}
      * @return this {@code AnnotationBuilder}
      */
-    default AnnotationBuilder value(AnnotationInfo<?>... values) {
+    default AnnotationBuilder value(AnnotationInfo... values) {
         return member(AnnotationInfo.MEMBER_VALUE, values);
     }
 
@@ -630,7 +630,7 @@ default AnnotationBuilder value(Annotation... values) {
      * @param enumValue name of the enum constant, must not be {@code null}
      * @return this {@code AnnotationBuilder}
      */
-    AnnotationBuilder member(String name, ClassInfo<?> enumType, String enumValue);
+    AnnotationBuilder member(String name, ClassInfo enumType, String enumValue);
 
     /**
      * Adds an enum array-valued annotation member with given {@code name}.
@@ -640,7 +640,7 @@ default AnnotationBuilder value(Annotation... values) {
      * @param enumValues names of the enum constants, must not be {@code null} or contain {@code null}
      * @return this {@code AnnotationBuilder}
      */
-    AnnotationBuilder member(String name, ClassInfo<?> enumType, String... enumValues);
+    AnnotationBuilder member(String name, ClassInfo enumType, String... enumValues);
 
     /**
      * Adds a class-valued annotation member with given {@code name}.
@@ -667,7 +667,7 @@ default AnnotationBuilder value(Annotation... values) {
      * @param value the class value, must not be {@code null}
      * @return this {@code AnnotationBuilder}
      */
-    AnnotationBuilder member(String name, ClassInfo<?> value);
+    AnnotationBuilder member(String name, ClassInfo value);
 
     /**
      * Adds a class array-valued annotation member with given {@code name}.
@@ -676,7 +676,7 @@ default AnnotationBuilder value(Annotation... values) {
      * @param values the class array, must not be {@code null} or contain {@code null}
      * @return this {@code AnnotationBuilder}
      */
-    AnnotationBuilder member(String name, ClassInfo<?>... values);
+    AnnotationBuilder member(String name, ClassInfo... values);
 
     /**
      * Adds a class-valued annotation member with given {@code name}.
@@ -724,7 +724,7 @@ default AnnotationBuilder value(Annotation... values) {
      * @param value the annotation value, must not be {@code null}
      * @return this {@code AnnotationBuilder}
      */
-    AnnotationBuilder member(String name, AnnotationInfo<?> value);
+    AnnotationBuilder member(String name, AnnotationInfo value);
 
     /**
      * Adds an annotation array-valued annotation member with given {@code name}.
@@ -733,7 +733,7 @@ default AnnotationBuilder value(Annotation... values) {
      * @param values the annotation array, must not be {@code null} or contain {@code null}
      * @return this {@code AnnotationBuilder}
      */
-    AnnotationBuilder member(String name, AnnotationInfo<?>... values);
+    AnnotationBuilder member(String name, AnnotationInfo... values);
 
     /**
      * Adds an annotation-valued annotation member with given {@code name}.
@@ -759,5 +759,5 @@ default AnnotationBuilder value(Annotation... values) {
      *
      * @return the built {@link AnnotationInfo}, never {@code null}
      */
-    AnnotationInfo<?> build();
+    AnnotationInfo build();
 }

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

@@ -24,5 +24,5 @@ public interface AnnotationBuilderFactory extends Prioritized {
      * @param annotationType the annotation type
      * @return a new {@link AnnotationBuilder}
      */
-    AnnotationBuilder create(ClassInfo<?> annotationType);
+    AnnotationBuilder create(ClassInfo annotationType);
 }

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

@@ -8,52 +8,134 @@
 import java.util.Collection;
 
 /**
- * @param <T> type of the inspected bean (that is, not the declaring class, but one of the types the bean has)
+ * Provides read-only information about a bean.
  */
-public interface BeanInfo<T> {
-    // TODO remove the type parameter?
-
+public interface BeanInfo {
+    /**
+     * Returns the {@link ScopeInfo scope} of this bean.
+     *
+     * @return the {@link ScopeInfo scope} of this bean, never {@code null}
+     */
     ScopeInfo scope();
 
+    /**
+     * Returns a collection of all {@link Type type}s of this bean.
+     *
+     * @return immutable collection of bean types, never {@code null}
+     */
     Collection<Type> types();
 
+    /**
+     * Returns a collection of this bean's qualifiers, represented as {@link AnnotationInfo}.
+     *
+     * @return immutable collection of qualifiers, never {@code null}
+     */
     // TODO method(s) for getting AnnotationInfo for given qualifier class?
     Collection<AnnotationInfo> qualifiers();
 
     /**
-     * Returns the class that declares the bean.
-     * In case of a bean defined by a class, that is the bean class directly.
+     * Returns the class that declares this bean.
+     * In case of a managed bean, also known as class-based bean, that is the bean class directly.
      * In case of a producer method or field, that is the class that declares the producer method or field.
-     * TODO null for synthetic beans, or return Optional?
+     * Returns {@code null} if this bean is synthetic.
      *
-     * @return {@link ClassInfo} for the class that declares the bean
+     * @return {@link ClassInfo} for the class that declares this bean, or {@code null} if this bean is synthetic
      */
-    ClassInfo<?> declaringClass();
+    ClassInfo declaringClass();
 
+    /**
+     * Returns whether this bean is a managed bean, sometimes also called class-based bean.
+     *
+     * @return whether this bean is a managed bean
+     */
     boolean isClassBean();
 
+    /**
+     * Returns whether this bean is defined by a producer method.
+     *
+     * @return whether this bean is defined by a producer method
+     */
     boolean isProducerMethod();
 
+    /**
+     * Returns whether this bean is defined by a producer field.
+     *
+     * @return whether this bean is defined by a producer field
+     */
     boolean isProducerField();
 
+    /**
+     * 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
+     * through other means (e.g. using an extension).
+     *
+     * @return whether this bean is synthetic
+     */
     boolean isSynthetic();
 
-    MethodInfo<?> producerMethod(); // TODO null if not producer method, or return Optional?
+    /**
+     * Returns the producer {@link 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();
 
-    FieldInfo<?> producerField(); // TODO null if not producer field, or return Optional?
+    /**
+     * Returns the producer {@link 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}.
+     *
+     * @return whether this bean is an {@link jakarta.enterprise.inject.Alternative alternative}
+     */
     boolean isAlternative();
 
+    /**
+     * Returns the {@link 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()
+     */
     int priority();
 
-    // EL name (from @Named), IIUC
+    /**
+     * Returns the bean name of this bean. A bean name is usually defined
+     * using the {@link jakarta.inject.Named @Named} annotation.
+     * Returns {@code null} if the bean doesn't have a name.
+     *
+     * @return the bean name, or {@code null} if the bean doesn't have a name
+     */
     String getName();
 
-    DisposerInfo disposer(); // TODO null if not producer method/field, or return Optional?
+    /**
+     * Returns the {@link 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
+     */
+    DisposerInfo disposer();
 
+    /**
+     * Returns a collection of this bean's {@link StereotypeInfo stereotype}s.
+     *
+     * @return immutable collection of stereotypes, never {@code null}
+     */
     Collection<StereotypeInfo> stereotypes();
 
     // TODO interceptors?
 
+    /**
+     * Returns a collection of this bean's {@link InjectionPointInfo injection point}s.
+     *
+     * @return immutable collection of injection points, never {@code null}
+     */
     Collection<InjectionPointInfo> injectionPoints();
 }

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

@@ -5,23 +5,42 @@
 import java.util.Collection;
 
 /**
- * @param <T> the configured class
+ * Allows adding annotations to and removing annotations from a class.
+ * Note that the class is not physically altered, the modifications
+ * are only seen by the CDI container.
+ *
+ * @see Enhancement
  */
-public interface ClassConfig<T> extends ClassInfo<T>, AnnotationConfig {
-    // TODO remove the type parameter?
-    // TODO even if ClassInfo has equals/hashCode, ClassConfig probably shouldn't
-
-    // only constructors declared by this class, not inherited ones
-    // no [static] initializers
+public interface ClassConfig extends DeclarationConfig<ClassConfig> {
+    /**
+     * Returns the {@link ClassInfo read-only information} about this transformed class.
+     *
+     * @return the {@link ClassInfo} corresponding to this transformed class, never {@code null}
+     */
     @Override
-    Collection<? extends MethodConfig<T>> constructors();
+    ClassInfo info();
 
-    // only methods declared by this class, not inherited ones
-    // no constructors nor [static] initializers
-    @Override
-    Collection<? extends MethodConfig<T>> methods();
+    /**
+     * Returns a collection of {@link MethodConfig} objects for each constructor of this class.
+     *
+     * @return immutable collection of {@link MethodConfig} objects, never {@code null}
+     */
+    // TODO specify whether inherited constructors are also included
+    Collection<MethodConfig> constructors();
 
-    // only fields declared by this class, not inherited ones
-    @Override
-    Collection<? extends FieldConfig<T>> fields();
+    /**
+     * 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
+    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
+    Collection<FieldConfig> fields();
 }