Polish @EnableWebMvc javadoc

Author: rstoyanchev

org.springframework.web.servlet/src/main/java/org/springframework/web/servlet/config/annotation/DelegatingWebMvcConfiguration.java

@@ -28,19 +28,15 @@
 import org.springframework.web.servlet.HandlerExceptionResolver;
 
 /**
- * A variant of {@link WebMvcConfigurationSupport} that delegates to one or more registered 
- * {@link WebMvcConfigurer}s allowing each of them to customize the default Spring MVC 
- * code-based configuration.
+ * A sub-class of {@link WebMvcConfigurationSupport} that detects beans of 
+ * type {@link WebMvcConfigurer}. Each {@link WebMvcConfigurer} is given a 
+ * chance to customize the Spring MVC configuration provided through
+ * {@link WebMvcConfigurationSupport}.
  * 
- * <p>This class is automatically imported when @{@link EnableWebMvc} is used to annotate
- * an @{@link Configuration} class. In turn it detects implementations of {@link WebMvcConfigurer}
- * via autowiring and delegates to them.  
- * 
- * @see EnableWebMvc
- * @see WebMvcConfigurer
- *
  * @author Rossen Stoyanchev
  * @since 3.1
+ * 
+ * @see EnableWebMvc
  */
 @Configuration
 public class DelegatingWebMvcConfiguration extends WebMvcConfigurationSupport {

org.springframework.web.servlet/src/main/java/org/springframework/web/servlet/config/annotation/EnableWebMvc.java

@@ -18,29 +18,27 @@
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
-import org.springframework.context.annotation.Configuration;
 import org.springframework.context.annotation.Import;
-import org.springframework.web.servlet.DispatcherServlet;
 
 /**
- * Enables default Spring MVC configuration and registers Spring MVC infrastructure components expected by the
- * {@link DispatcherServlet}. Use this annotation on an @{@link Configuration} class. In turn that will
- * import {@link DelegatingWebMvcConfiguration}, which provides default Spring MVC configuration.
+ * Add this annotation to an {@code @Configuration} class to have the Spring MVC
+ * configuration defined in {@link WebMvcConfigurationSupport} imported:
+ * 
  * <pre class="code">
  * &#064;Configuration
  * &#064;EnableWebMvc
  * &#064;ComponentScan(
  * 	basePackageClasses = { MyConfiguration.class },
  * 	excludeFilters = { @Filter(type = FilterType.ANNOTATION, value = Configuration.class) }
  * )
- * public class MyConfiguration {
+ * public class MyWebConfiguration {
  *
  * }
  * </pre>
- * <p>To customize the imported configuration implement {@link WebMvcConfigurer}, or more conveniently extend
- * {@link WebMvcConfigurerAdapter} overriding specific methods only. Any @{@link Configuration} class that
- * implements {@link WebMvcConfigurer} will be detected by {@link DelegatingWebMvcConfiguration} and given 
- * an opportunity to customize the default Spring MVC code-based configuration.
+ * <p>Customize the imported configuration by implementing the
+ * {@link WebMvcConfigurer} interface or more likely by extending the 
+ * {@link WebMvcConfigurerAdapter} base class and overriding individual methods: 
+ * 
  * <pre class="code">
  * &#064;Configuration
  * &#064;EnableWebMvc
@@ -60,7 +58,34 @@
  * 		converters.add(new MyHttpMessageConverter());
  * 	}
  *
- * 	// &#064;Override methods ...
+ * 	// More overridden methods ...
+ *
+ * }
+ * </pre>
+ *
+ * <p>If the customization options of {@link WebMvcConfigurer} do not expose 
+ * something you need to configure, consider removing the {@code @EnableWebMvc} 
+ * annotation and extending directly from {@link WebMvcConfigurationSupport} 
+ * overriding selected {@code @Bean} methods:
+ * 
+ * <pre class="code">
+ * &#064;Configuration
+ * &#064;ComponentScan(
+ * 	basePackageClasses = { MyConfiguration.class },
+ * 	excludeFilters = { @Filter(type = FilterType.ANNOTATION, value = Configuration.class) }
+ * )
+ * public class MyConfiguration extends WebMvcConfigurationSupport {
+ *
+ * 	&#064;Override
+ *	public void addFormatters(FormatterRegistry formatterRegistry) {
+ *		formatterRegistry.addConverter(new MyConverter());
+ *	}
+ *
+ *	&#064;Bean
+ *	public RequestMappingHandlerAdapter requestMappingHandlerAdapter() {
+ *		// Create or delegate to "super" to create and
+ *		// customize properties of RequestMapingHandlerAdapter
+ *	}
  *
  * }
  * </pre>

org.springframework.web.servlet/src/main/java/org/springframework/web/servlet/config/annotation/WebMvcConfigurationSupport.java

@@ -73,8 +73,8 @@
 import org.springframework.web.servlet.mvc.support.DefaultHandlerExceptionResolver;
 
 /**
- * A base class that provides default configuration for Spring MVC applications 
- * by registering Spring MVC infrastructure components to be detected by the 
+ * A base class that provides configuration for Spring MVC applications 
+ * by registering Spring MVC infrastructure components detected by the 
  * {@link DispatcherServlet}. An application configuration class is not required
  * to extend this class. A more likely place to start is to annotate 
  * an @{@link Configuration} class with @{@link EnableWebMvc}