small improvements and clarifications in Build Compatible Extensions and Language Model

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

@@ -49,9 +49,10 @@
  * Build compatible extensions may be annotated {@link SkipIfPortableExtensionPresent @SkipIfPortableExtensionPresent}
  * when they are supposed to be ignored in presence of a given portable extension.
  * <p>
- * CDI implementations are not required to accept custom implementations of any {@code jakarta.enterprise.lang.model}
- * or {@code jakarta.enterprise.inject.build.compatible.spi} interface. In other words, users may only use instances
- * of these interfaces that they previously obtained from the corresponding API. If not, non-portable behavior results.
+ * CDI implementations are not required to accept custom implementations of any {@code jakarta.enterprise.lang.model},
+ * {@code jakarta.enterprise.invoke} or {@code jakarta.enterprise.inject.build.compatible.spi} interface
+ * on the API boundary of build compatible extensions. In other words, users may only use instances of these
+ * interfaces that they previously obtained from the corresponding API. If not, non-portable behavior results.
  * <p>
  * In build compatible extensions, implementations of {@link jakarta.enterprise.lang.model.AnnotationTarget}
  * only return annotations with the {@linkplain java.lang.annotation.RetentionPolicy#RUNTIME runtime} retention policy.

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

@@ -41,8 +41,8 @@
  * If the {@code @Registration} method has a parameter of type {@code ObserverInfo}, the method is called once
  * for each observer whose observed event type is assignable to at least one <em>expected type</em>.
  * <p>
- * Note that interceptors are beans, and {@code InterceptorInfo} is a subtype of {@code BeanInfo}, so if the method
- * has a parameter of type {@code BeanInfo}, it will be called for interceptors as well.
+ * Note that {@code InterceptorInfo} is a subtype of {@code BeanInfo}, so if the method has a parameter
+ * of type {@code BeanInfo}, it will be called for interceptors as well.
  * <p>
  * If the {@code @Registration} method doesn't declare any parameter of one of these types,
  * or if it declares more than one, the container treats it as a definition error.

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

@@ -100,7 +100,8 @@ public interface SyntheticBeanBuilder<T> {
     /**
      * Sets the scope of this synthetic bean to given scope type.
      * <p>
-     * If not called, this synthetic bean will be {@code @Dependent}.
+     * If not called, and if no stereotype is added that defines a scope,
+     * this synthetic bean will be {@code @Dependent}.
      *
      * @param scopeAnnotation the scope type, must not be {@code null}
      * @return this {@code SyntheticBeanBuilder}
@@ -131,7 +132,6 @@ public interface SyntheticBeanBuilder<T> {
      * that it is not enabled, which is equivalent to not registering it at all.
      * <p>
      * If not called, this synthetic bean will not have a priority.
-     * If this synthetic bean is not an alternative, the priority is ignored.
      *
      * @param priority the priority of this synthetic bean
      * @return this {@code SyntheticBeanBuilder}

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

@@ -20,14 +20,14 @@
 public interface SyntheticComponents {
     /**
      * Creates a {@link SyntheticBeanBuilder} that allows configuring a new synthetic bean
-     * of given {@code beanClass}. The synthetic bean will be registered at the end of
+     * of given {@code implementationClass}. The synthetic bean will be registered at the end of
      * the {@link Synthesis @Synthesis} method.
      *
-     * @param beanClass the bean class of the new synthetic bean, must not be {@code null}
-     * @param <T> the bean class of the new synthetic bean
+     * @param implementationClass the implementation class of the new synthetic bean, must not be {@code null}
+     * @param <T> the implementation class of the new synthetic bean
      * @return a new {@link SyntheticBeanBuilder}, never {@code null}
      */
-    <T> SyntheticBeanBuilder<T> addBean(Class<T> beanClass);
+    <T> SyntheticBeanBuilder<T> addBean(Class<T> implementationClass);
 
     /**
      * Creates a {@link SyntheticObserverBuilder} that allows configuring a new synthetic observer

lang-model/src/main/java/jakarta/enterprise/lang/model/declarations/ClassInfo.java

@@ -61,34 +61,34 @@ public interface ClassInfo extends DeclarationInfo {
     List<TypeVariable> typeParameters();
 
     /**
-     * Returns the {@linkplain Type type} of this class's superclass. Returns {@code null} if this class
+     * Returns the direct superclass {@linkplain Type type} of this class. Returns {@code null} if this class
      * does not have a superclass; that is, if this class is {@code java.lang.Object} or an interface.
      *
-     * @return the type of this class's superclass, or {@code null} if there's no superclass
+     * @return the direct superclass type of this class, or {@code null} if there's no superclass
      */
     Type superClass();
 
     /**
-     * Returns the {@linkplain ClassInfo declaration} of this class's superclass. Returns {@code null} if this class
+     * Returns the direct superclass of this class. Returns {@code null} if this class
      * does not have a superclass; that is, if this class is {@code java.lang.Object} or an interface.
      *
-     * @return the declaration of this class's superclass, or {@code null} if there's no superclass
+     * @return the direct superclass of this class, or {@code null} if there's no superclass
      */
     ClassInfo superClassDeclaration();
 
     /**
-     * Returns a list of {@linkplain Type types} of this class's direct superinterfaces.
+     * Returns a list of direct superinterface {@linkplain Type types} of this class.
      * Returns an empty list if this class has no direct superinterface.
      *
-     * @return immutable list of types of this class's direct superinterfaces, never {@code null}
+     * @return immutable list of direct superinterface types of this class, never {@code null}
      */
     List<Type> superInterfaces();
 
     /**
-     * Returns a list of {@linkplain ClassInfo declarations} of this class's direct superinterfaces.
+     * Returns a list of direct superinterfaces of this class.
      * Returns an empty list if this class has no direct superinterface.
      *
-     * @return immutable list of declarations of this class's direct superinterfaces, never {@code null}
+     * @return immutable list of direct superinterfaces of this class, never {@code null}
      */
     List<ClassInfo> superInterfacesDeclarations();
 
@@ -169,8 +169,10 @@ public interface ClassInfo extends DeclarationInfo {
     /**
      * Returns a collection of {@linkplain MethodInfo methods} declared or implicitly declared
      * in this class and all its superclasses up to and excluding {@code java.lang.Object},
-     * as well as all direct and indirect superinterfaces. If this class is an interface,
-     * only superinterfaces are considered. Methods implicitly declared in interfaces are omitted.
+     * as well as all direct and indirect superinterfaces. If this class is {@code java.lang.Object},
+     * its methods are not excluded. If this class is an interface, only superinterfaces
+     * are considered. Implicitly declared methods corresponding to {@code java.lang.Object}
+     * methods in interfaces are omitted.
      * <p>
      * If the collection of methods described above contains multiple methods with the same signature,
      * all such methods are returned. {@link MethodInfo#declaringClass() MethodInfo.declaringClass}
@@ -186,8 +188,9 @@ public interface ClassInfo extends DeclarationInfo {
     /**
      * Returns a collection of {@linkplain FieldInfo fields} declared or implicitly declared
      * in this class and all its superclasses up to and excluding {@code java.lang.Object},
-     * as well as all direct and indirect superinterfaces. If this class is an interface,
-     * only superinterfaces are considered.
+     * as well as all direct and indirect superinterfaces. If this class is {@code java.lang.Object},
+     * its fields are not excluded. If this class is an interface, only superinterfaces
+     * are considered.
      * <p>
      * If the collection of fields described above contains multiple fields with the same name,
      * all such fields are returned. {@link FieldInfo#declaringClass() FieldInfo.declaringClass}