Document how to register annotated classes in a GenericWebApplicationContext

Closes gh-27778

spring-web/src/main/java/org/springframework/web/context/support/AnnotationConfigWebApplicationContext.java

@@ -46,7 +46,17 @@ import org.springframework.web.context.ContextLoader;
  *
  * <p>This is essentially the equivalent of
  * {@link org.springframework.context.annotation.AnnotationConfigApplicationContext
- * AnnotationConfigApplicationContext} for a web environment.
+ * AnnotationConfigApplicationContext} for a web environment. However, in contrast to
+ * {@code AnnotationConfigApplicationContext}, this class does not extend
+ * {@link org.springframework.context.support.GenericApplicationContext
+ * GenericApplicationContext} and therefore does not provide some of the convenient
+ * {@code registerBean(...)} methods available in a {@code GenericApplicationContext}.
+ * If you wish to register annotated <em>component classes</em> with a
+ * {@code GenericApplicationContext} in a web environment, you may use a
+ * {@code GenericWebApplicationContext} with an
+ * {@link org.springframework.context.annotation.AnnotatedBeanDefinitionReader
+ * AnnotatedBeanDefinitionReader}. See the Javadoc for {@link GenericWebApplicationContext}
+ * for details and an example.
  *
  * <p>To make use of this application context, the
  * {@linkplain ContextLoader#CONTEXT_CLASS_PARAM "contextClass"} context-param for
@@ -81,8 +91,10 @@ import org.springframework.web.context.ContextLoader;
  *
  * @author Chris Beams
  * @author Juergen Hoeller
+ * @author Sam Brannen
  * @since 3.0
  * @see org.springframework.context.annotation.AnnotationConfigApplicationContext
+ * @see org.springframework.web.context.support.GenericWebApplicationContext
  */
 public class AnnotationConfigWebApplicationContext extends AbstractRefreshableWebApplicationContext
 		implements AnnotationConfigRegistry {

spring-web/src/main/java/org/springframework/web/context/support/GenericWebApplicationContext.java

@@ -53,6 +53,20 @@ import org.springframework.web.context.ServletContextAware;
  * {@link org.springframework.context.support.AbstractApplicationContext AbstractApplicationContext},
  * this class detects a {@link ThemeSource} bean in the context, with the name "themeSource".
  *
+ * <p>If you wish to register annotated <em>component classes</em> with a
+ * {@code GenericWebApplicationContext}, you can use an
+ * {@link org.springframework.context.annotation.AnnotatedBeanDefinitionReader
+ * AnnotatedBeanDefinitionReader}, as demonstrated in the following example.
+ * Component classes include in particular
+ * {@link org.springframework.context.annotation.Configuration @Configuration}
+ * classes but also plain {@link org.springframework.stereotype.Component @Component}
+ * classes as well as JSR-330 compliant classes using {@code javax.inject} annotations.
+ *
+ * <pre class="code">
+ * GenericWebApplicationContext context = new GenericWebApplicationContext();
+ * AnnotatedBeanDefinitionReader reader = new AnnotatedBeanDefinitionReader(context);
+ * reader.register(AppConfig.class, UserController.class, UserRepository.class);</pre>
+ *
  * <p>If you intend to implement a {@code WebApplicationContext} that reads bean definitions
  * from configuration files, consider deriving from {@link AbstractRefreshableWebApplicationContext},
  * reading the bean definitions in an implementation of the {@code loadBeanDefinitions}
@@ -60,6 +74,7 @@ import org.springframework.web.context.ServletContextAware;
  *
  * @author Juergen Hoeller
  * @author Chris Beams
+ * @author Sam Brannen
  * @since 1.2
  */
 public class GenericWebApplicationContext extends GenericApplicationContext

src/docs/asciidoc/core/core-beans.adoc

@@ -7900,6 +7900,10 @@ init-param):
 	</web-app>
 ----
 
+NOTE: For programmatic use cases, a `GenericWebApplicationContext` can be used as an
+alternative to `AnnotationConfigWebApplicationContext`. See the
+{api-spring-framework}/web/context/support/GenericWebApplicationContext.html[`GenericWebApplicationContext`]
+javadoc for details.
 
 
 [[beans-java-bean-annotation]]

src/docs/asciidoc/web/webmvc.adoc

@@ -84,6 +84,11 @@ NOTE: In addition to using the ServletContext API directly, you can also extend
 `AbstractAnnotationConfigDispatcherServletInitializer` and override specific methods
 (see the example under <<mvc-servlet-context-hierarchy>>).
 
+NOTE: For programmatic use cases, a `GenericWebApplicationContext` can be used as an
+alternative to `AnnotationConfigWebApplicationContext`. See the
+{api-spring-framework}/web/context/support/GenericWebApplicationContext.html[`GenericWebApplicationContext`]
+javadoc for details.
+
 The following example of `web.xml` configuration registers and initializes the `DispatcherServlet`:
 
 [source,xml,indent=0,subs="verbatim,quotes"]