Add support for ImportAware in BeanRegistrar

Closes gh-34627

spring-beans/src/main/java/org/springframework/beans/factory/BeanRegistrar.java

@@ -19,18 +19,20 @@ package org.springframework.beans.factory;
 import org.springframework.core.env.Environment;
 
 /**
- * Contract for registering beans programmatically.
- *
- * <p>Typically imported with an {@link org.springframework.context.annotation.Import @Import}
- * annotation on {@link org.springframework.context.annotation.Configuration @Configuration}
- * classes.
+ * Contract for registering beans programmatically, typically imported with an
+ * {@link org.springframework.context.annotation.Import @Import} annotation on
+ * a {@link org.springframework.context.annotation.Configuration @Configuration}
+ * class.
  * <pre class="code">
  * &#064;Configuration
  * &#064;Import(MyBeanRegistrar.class)
  * class MyConfiguration {
  * }</pre>
+ * Can also be applied to an application context via
+ * {@link org.springframework.context.support.GenericApplicationContext#register(BeanRegistrar...)}.
  *
- * <p>The bean registrar implementation uses {@link BeanRegistry} and {@link Environment}
+ *
+ * <p>Bean registrar implementations use {@link BeanRegistry} and {@link Environment}
  * APIs to register beans programmatically in a concise and flexible way.
  * <pre class="code">
  * class MyBeanRegistrar implements BeanRegistrar {
@@ -50,6 +52,10 @@ import org.springframework.core.env.Environment;
  *     }
  * }</pre>
  *
+ * <p>A {@code BeanRegistrar} implementing {@link org.springframework.context.annotation.ImportAware}
+ * can optionally introspect import metadata when used in an import scenario, otherwise the
+ * {@code setImportMetadata} method is simply not being called.
+ *
  * <p>In Kotlin, it is recommended to use {@code BeanRegistrarDsl} instead of
  * implementing {@code BeanRegistrar}.
  *