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