From 6a59d005769008b8c9a02bc87cc1123a8c73cb7f Mon Sep 17 00:00:00 2001
From: Sam Brannen <sam@sambrannen.com>
Date: Tue, 28 Jul 2015 19:44:47 +0200
Subject: [PATCH] Fix references and typos in Spring MVC Test Javadoc

This commit fixes numerous references to 'legacy' packages within the
Javadoc for the Spring MVC Test framework.

In addition, this commit improves examples in Javadoc, adds links to
related classes where appropriate, and removes unnecessary imports for
types that are only referenced within documentation.

Issue: SPR-13284
---
 .../test/web/servlet/MockMvc.java             |  9 ++-
 .../test/web/servlet/MockMvcBuilder.java      |  8 +--
 .../test/web/servlet/RequestBuilder.java      |  7 ++-
 .../test/web/servlet/ResultActions.java       | 14 +++--
 .../test/web/servlet/ResultHandler.java       | 24 +++++---
 .../test/web/servlet/ResultMatcher.java       | 23 ++++++--
 .../request/MockMvcRequestBuilders.java       | 17 +-----
 .../web/servlet/setup/MockMvcBuilders.java    | 58 ++++++++++---------
 8 files changed, 89 insertions(+), 71 deletions(-)

diff --git a/spring-test/src/main/java/org/springframework/test/web/servlet/MockMvc.java b/spring-test/src/main/java/org/springframework/test/web/servlet/MockMvc.java
index 8ebabae219..236971b09d 100644
--- a/spring-test/src/main/java/org/springframework/test/web/servlet/MockMvc.java
+++ b/spring-test/src/main/java/org/springframework/test/web/servlet/MockMvc.java
@@ -33,11 +33,14 @@ import org.springframework.web.context.request.ServletRequestAttributes;
 /**
  * <strong>Main entry point for server-side Spring MVC test support.</strong>
  *
- * <p>Below is an example:
+ * <h3>Example</h3>
  *
  * <pre class="code">
- * static imports:
- * MockMvcBuilders.*, MockMvcRequestBuilders.*, MockMvcResultMatchers.*
+ * import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.*;
+ * import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.*;
+ * import static org.springframework.test.web.servlet.setup.MockMvcBuilders.*;
+ *
+ * // ...
  *
  * WebApplicationContext wac = ...;
  *
diff --git a/spring-test/src/main/java/org/springframework/test/web/servlet/MockMvcBuilder.java b/spring-test/src/main/java/org/springframework/test/web/servlet/MockMvcBuilder.java
index 2e120b9a94..d1edb021bf 100644
--- a/spring-test/src/main/java/org/springframework/test/web/servlet/MockMvcBuilder.java
+++ b/spring-test/src/main/java/org/springframework/test/web/servlet/MockMvcBuilder.java
@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2012 the original author or authors.
+ * Copyright 2002-2015 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -17,10 +17,10 @@
 package org.springframework.test.web.servlet;
 
 /**
- * Builds a {@link MockMvc}.
+ * Builds a {@link MockMvc} instance.
  *
- * <p>See static, factory methods in
- * {@code org.springframework.test.web.server.setup.MockMvcBuilders}.
+ * <p>See static factory methods in
+ * {@link org.springframework.test.web.servlet.setup.MockMvcBuilders MockMvcBuilders}.
  *
  * @author Rossen Stoyanchev
  * @since 3.2
diff --git a/spring-test/src/main/java/org/springframework/test/web/servlet/RequestBuilder.java b/spring-test/src/main/java/org/springframework/test/web/servlet/RequestBuilder.java
index 9754a96c6b..c3f02ee2f3 100644
--- a/spring-test/src/main/java/org/springframework/test/web/servlet/RequestBuilder.java
+++ b/spring-test/src/main/java/org/springframework/test/web/servlet/RequestBuilder.java
@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2012 the original author or authors.
+ * Copyright 2002-2015 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -13,6 +13,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+
 package org.springframework.test.web.servlet;
 
 import javax.servlet.ServletContext;
@@ -22,8 +23,8 @@ import org.springframework.mock.web.MockHttpServletRequest;
 /**
  * Builds a {@link MockHttpServletRequest}.
  *
- * <p>See static, factory methods in
- * {@code org.springframework.test.web.server.request.MockMvcRequestBuilders}.
+ * <p>See static factory methods in
+ * {@link org.springframework.test.web.servlet.request.MockMvcRequestBuilders MockMvcRequestBuilders}.
  *
  * @author Arjen Poutsma
  * @author Rossen Stoyanchev
diff --git a/spring-test/src/main/java/org/springframework/test/web/servlet/ResultActions.java b/spring-test/src/main/java/org/springframework/test/web/servlet/ResultActions.java
index 90cbcb5041..083611f611 100644
--- a/spring-test/src/main/java/org/springframework/test/web/servlet/ResultActions.java
+++ b/spring-test/src/main/java/org/springframework/test/web/servlet/ResultActions.java
@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2012 the original author or authors.
+ * Copyright 2002-2015 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -21,8 +21,8 @@ package org.springframework.test.web.servlet;
  * request.
  *
  * <p>See static factory methods in
- * {@code org.springframework.test.web.servlet.result.MockMvcResultMatchers}
- * {@code org.springframework.test.web.servlet.result.MockMvcResultHandlers}
+ * {@link org.springframework.test.web.servlet.result.MockMvcResultMatchers} and
+ * {@link org.springframework.test.web.servlet.result.MockMvcResultHandlers}.
  *
  * @author Rossen Stoyanchev
  * @since 3.2
@@ -30,7 +30,9 @@ package org.springframework.test.web.servlet;
 public interface ResultActions {
 
 	/**
-	 * Provide an expectation. For example:
+	 * Perform an expectation.
+	 *
+	 * <h4>Example</h4>
 	 * <pre class="code">
 	 * static imports: MockMvcRequestBuilders.*, MockMvcResultMatchers.*
 	 *
@@ -51,7 +53,9 @@ public interface ResultActions {
 	ResultActions andExpect(ResultMatcher matcher) throws Exception;
 
 	/**
-	 * Provide a general action. For example:
+	 * Perform a general action.
+	 *
+	 * <h4>Example</h4>
 	 * <pre class="code">
 	 * static imports: MockMvcRequestBuilders.*, MockMvcResultMatchers.*
 	 *
diff --git a/spring-test/src/main/java/org/springframework/test/web/servlet/ResultHandler.java b/spring-test/src/main/java/org/springframework/test/web/servlet/ResultHandler.java
index 1f5ee35b6e..ea21c16c4b 100644
--- a/spring-test/src/main/java/org/springframework/test/web/servlet/ResultHandler.java
+++ b/spring-test/src/main/java/org/springframework/test/web/servlet/ResultHandler.java
@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2012 the original author or authors.
+ * Copyright 2002-2015 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -17,27 +17,37 @@
 package org.springframework.test.web.servlet;
 
 /**
- * Executes a generic action (e.g. printing debug information) on the result of
- * an executed request.
+ * A {@code ResultHandler} performs a generic action on the result of an
+ * executed request &mdash; for example, printing debug information.
  *
  * <p>See static factory methods in
- * {@code org.springframework.test.web.server.result.MockMvcResultHandlers}.
+ * {@link org.springframework.test.web.servlet.result.MockMvcResultHandlers
+ * MockMvcResultHandlers}.
  *
- * <p>Example:
+ * <h3>Example</h3>
  *
  * <pre class="code">
- * static imports: MockMvcRequestBuilders.*, MockMvcResultHandlers.*
+ * import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.*;
+ * import static org.springframework.test.web.servlet.result.MockMvcResultHandlers.*;
+ * import static org.springframework.test.web.servlet.setup.MockMvcBuilders.*;
+ *
+ * // ...
+ *
+ * WebApplicationContext wac = ...;
+ *
+ * MockMvc mockMvc = webAppContextSetup(wac).build();
  *
  * mockMvc.perform(get("/form")).andDo(print());
  * </pre>
  *
  * @author Rossen Stoyanchev
+ * @author Sam Brannen
  * @since 3.2
  */
 public interface ResultHandler {
 
 	/**
-	 * Apply the action on the given result.
+	 * Perform an action on the given result.
 	 *
 	 * @param result the result of the executed request
 	 * @throws Exception if a failure occurs
diff --git a/spring-test/src/main/java/org/springframework/test/web/servlet/ResultMatcher.java b/spring-test/src/main/java/org/springframework/test/web/servlet/ResultMatcher.java
index cc73bcc395..f781ba19c0 100644
--- a/spring-test/src/main/java/org/springframework/test/web/servlet/ResultMatcher.java
+++ b/spring-test/src/main/java/org/springframework/test/web/servlet/ResultMatcher.java
@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2012 the original author or authors.
+ * Copyright 2002-2015 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -17,22 +17,33 @@
 package org.springframework.test.web.servlet;
 
 /**
- * Matches the result of an executed request against some expectation.
+ * A {@code ResultMatcher} matches the result of an executed request against
+ * some expectation.
  *
  * <p>See static factory methods in
- * {@code org.springframework.test.web.server.result.MockMvcResultMatchers}.
+ * {@link org.springframework.test.web.servlet.result.MockMvcResultMatchers
+ * MockMvcResultMatchers}.
  *
- * <p>Example:
+ * <h3>Example Using Status and Content Result Matchers</h3>
  *
  * <pre class="code">
- * static imports: MockMvcRequestBuilders.*, MockMvcResultMatchers.*
+ * import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.*;
+ * import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.*;
+ * import static org.springframework.test.web.servlet.setup.MockMvcBuilders.*;
+ *
+ * // ...
+ *
+ * WebApplicationContext wac = ...;
+ *
+ * MockMvc mockMvc = webAppContextSetup(wac).build();
  *
  * mockMvc.perform(get("/form"))
- *   .andExpect(status.isOk())
+ *   .andExpect(status().isOk())
  *   .andExpect(content().mimeType(MediaType.APPLICATION_JSON));
  * </pre>
  *
  * @author Rossen Stoyanchev
+ * @author Sam Brannen
  * @since 3.2
  */
 public interface ResultMatcher {
diff --git a/spring-test/src/main/java/org/springframework/test/web/servlet/request/MockMvcRequestBuilders.java b/spring-test/src/main/java/org/springframework/test/web/servlet/request/MockMvcRequestBuilders.java
index 85b2c98b84..37ffa16723 100644
--- a/spring-test/src/main/java/org/springframework/test/web/servlet/request/MockMvcRequestBuilders.java
+++ b/spring-test/src/main/java/org/springframework/test/web/servlet/request/MockMvcRequestBuilders.java
@@ -21,7 +21,6 @@ import javax.servlet.ServletContext;
 
 import org.springframework.http.HttpMethod;
 import org.springframework.mock.web.MockHttpServletRequest;
-import org.springframework.mock.web.MockMultipartHttpServletRequest;
 import org.springframework.test.web.servlet.MvcResult;
 import org.springframework.test.web.servlet.RequestBuilder;
 
@@ -33,10 +32,6 @@ import org.springframework.test.web.servlet.RequestBuilder;
  * {@link org.springframework.mock.web.MockServletContext MockServletContext}
  * that was created by the Spring TestContext Framework.
  *
- * <p>Methods in this class that return a {@link MockHttpServletRequestBuilder}
- * will reuse a {@link MockHttpServletRequest} that was created by the Spring
- * TestContext Framework.
- *
  * <h3>Eclipse Users</h3>
  * <p>Consider adding this class as a Java editor favorite. To navigate to
  * this setting, open the Preferences and type "favorites".
@@ -199,11 +194,6 @@ public abstract class MockMvcRequestBuilders {
 
 	/**
 	 * Create a {@link MockMultipartHttpServletRequestBuilder} for a multipart request.
-	 * <p>In contrast to methods in this class that return a
-	 * {@link MockHttpServletRequestBuilder}, the builder returned by this
-	 * method will always create a new {@link MockMultipartHttpServletRequest}
-	 * that is <em>not</em> associated with a mock request created by the
-	 * Spring TestContext Framework.
 	 * @param urlTemplate a URL template; the resulting URL will be encoded
 	 * @param urlVariables zero or more URL variables
 	 */
@@ -213,11 +203,6 @@ public abstract class MockMvcRequestBuilders {
 
 	/**
 	 * Create a {@link MockMultipartHttpServletRequestBuilder} for a multipart request.
-	 * <p>In contrast to methods in this class that return a
-	 * {@link MockHttpServletRequestBuilder}, the builder returned by this
-	 * method will always create a new {@link MockMultipartHttpServletRequest}
-	 * that is <em>not</em> associated with a mock request created by the
-	 * Spring TestContext Framework.
 	 * @param uri the URL
 	 * @since 4.0.3
 	 */
@@ -228,7 +213,7 @@ public abstract class MockMvcRequestBuilders {
 	/**
 	 * Create a {@link RequestBuilder} for an async dispatch from the
 	 * {@link MvcResult} of the request that started async processing.
-	 * <p>Usage involves performing one request first that starts async processing:
+	 * <p>Usage involves performing a request that starts async processing first:
 	 * <pre class="code">
 	 * MvcResult mvcResult = this.mockMvc.perform(get("/1"))
 	 *	.andExpect(request().asyncStarted())
diff --git a/spring-test/src/main/java/org/springframework/test/web/servlet/setup/MockMvcBuilders.java b/spring-test/src/main/java/org/springframework/test/web/servlet/setup/MockMvcBuilders.java
index 2a9ee4633b..6522ad1ddd 100644
--- a/spring-test/src/main/java/org/springframework/test/web/servlet/setup/MockMvcBuilders.java
+++ b/spring-test/src/main/java/org/springframework/test/web/servlet/setup/MockMvcBuilders.java
@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2012 the original author or authors.
+ * Copyright 2002-2015 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -16,56 +16,60 @@
 
 package org.springframework.test.web.servlet.setup;
 
-import javax.servlet.ServletContext;
-
-import org.springframework.stereotype.Controller;
 import org.springframework.test.web.servlet.MockMvc;
 import org.springframework.test.web.servlet.MockMvcBuilder;
 import org.springframework.web.context.WebApplicationContext;
-import org.springframework.web.servlet.DispatcherServlet;
 
 /**
- * The main class to import to access all available {@link MockMvcBuilder}s.
+ * The main class to import in order to access all available {@link MockMvcBuilder}s.
  *
- * <p><strong>Eclipse users:</strong> consider adding this class as a Java editor
- * favorite. To navigate, open the Preferences and type "favorites".
+ * <h3>Eclipse Users</h3>
+ * <p>Consider adding this class as a Java editor favorite. To navigate to
+ * this setting, open the Preferences and type "favorites".
  *
  * @author Rossen Stoyanchev
+ * @author Sam Brannen
  * @since 3.2
+ * @see #webAppContextSetup(WebApplicationContext)
+ * @see #standaloneSetup(Object...)
  */
 public class MockMvcBuilders {
 
 	/**
-	 * Build a {@link MockMvc} using the given, fully initialized, i.e.
-	 * refreshed, {@link WebApplicationContext}. The {@link DispatcherServlet}
-	 * will use the context to discover Spring MVC infrastructure and
-	 * application controllers in it. The context must have been configured with
-	 * a {@link ServletContext}.
+	 * Build a {@link MockMvc} instance using the given, fully initialized
+	 * (i.e., <em>refreshed</em>) {@link WebApplicationContext}.
+	 * <p>The {@link org.springframework.web.servlet.DispatcherServlet DispatcherServlet}
+	 * will use the context to discover Spring MVC infrastructure and application
+	 * controllers in it. The context must have been configured with a
+	 * {@link javax.servlet.ServletContext ServletContext}.
 	 */
 	public static DefaultMockMvcBuilder webAppContextSetup(WebApplicationContext context) {
 		return new DefaultMockMvcBuilder(context);
 	}
 
 	/**
-	 * Build a {@link MockMvc} by registering one or more {@code @Controller}'s
-	 * instances and configuring Spring MVC infrastructure programmatically.
-	 * This allows full control over the instantiation and initialization of
-	 * controllers, and their dependencies, similar to plain unit tests while
+	 * Build a {@link MockMvc} instance by registering one or more
+	 * {@code @Controller} instances and configuring Spring MVC infrastructure
+	 * programmatically.
+	 *
+	 * <p>This allows full control over the instantiation and initialization of
+	 * controllers and their dependencies, similar to plain unit tests while
 	 * also making it possible to test one controller at a time.
 	 *
-	 * <p>When this option is used, the minimum infrastructure required by the
-	 * {@link DispatcherServlet} to serve requests with annotated controllers is
-	 * automatically created, and can be customized, resulting in configuration
-	 * that is equivalent to what the MVC Java configuration provides except
-	 * using builder style methods.
+	 * <p>When this builder is used, the minimum infrastructure required by the
+	 * {@link org.springframework.web.servlet.DispatcherServlet DispatcherServlet}
+	 * to serve requests with annotated controllers is created automatically
+	 * and can be customized, resulting in configuration that is equivalent to
+	 * what MVC Java configuration provides except using builder-style methods.
 	 *
 	 * <p>If the Spring MVC configuration of an application is relatively
-	 * straight-forward, for example when using the MVC namespace or the MVC
-	 * Java config, then using this builder might be a good option for testing
-	 * a majority of controllers. A much smaller number of tests can be used
-	 * to focus on testing and verifying the actual Spring MVC configuration.
+	 * straight-forward &mdash; for example, when using the MVC namespace in
+	 * XML or MVC Java config &mdash; then using this builder might be a good
+	 * option for testing a majority of controllers. In such cases, a much
+	 * smaller number of tests can be used to focus on testing and verifying
+	 * the actual Spring MVC configuration.
 	 *
-	 * @param controllers one or more {@link Controller @Controller}'s to test
+	 * @param controllers one or more {@code @Controller} instances to test
 	 */
 	public static StandaloneMockMvcBuilder standaloneSetup(Object... controllers) {
 		return new StandaloneMockMvcBuilder(controllers);