Document context hierarchy support in the TCF

This commit polishes the Javadoc for @ContextHierarchy and
@ContextConfiguration.

Issue: SPR-10357

spring-test/src/main/java/org/springframework/test/context/ContextConfiguration.java

@@ -58,7 +58,7 @@ import org.springframework.context.ConfigurableApplicationContext;
  * {@link org.springframework.context.annotation.Bean @Bean}-methods</li>
  * </ul>
  *
- * Consult the Javadoc for
+ * <p>Consult the Javadoc for
  * {@link org.springframework.context.annotation.Configuration @Configuration} and
  * {@link org.springframework.context.annotation.Bean @Bean}
  * for further information regarding the configuration and semantics of
@@ -270,16 +270,25 @@ public @interface ContextConfiguration {
 	 * explicit loader. If no class in the hierarchy specifies an explicit
 	 * loader, a default loader will be used instead.
 	 *
-	 * <p>The default concrete implementation chosen at runtime will be
+	 * <p>The default concrete implementation chosen at runtime will be either
 	 * {@link org.springframework.test.context.support.DelegatingSmartContextLoader
-	 * DelegatingSmartContextLoader}. For further details on the default behavior
-	 * of various concrete {@code ContextLoaders}, check out the Javadoc for
+	 * DelegatingSmartContextLoader} or
+	 * {@link org.springframework.test.context.web.WebDelegatingSmartContextLoader
+	 * WebDelegatingSmartContextLoader} depending on the absence or presence of
+	 * {@link org.springframework.test.context.web.WebAppConfiguration
+	 * &#064;WebAppConfiguration}. For further details on the default behavior
+	 * of various concrete {@code SmartContextLoaders}, check out the Javadoc for
 	 * {@link org.springframework.test.context.support.AbstractContextLoader
 	 * AbstractContextLoader},
 	 * {@link org.springframework.test.context.support.GenericXmlContextLoader
-	 * GenericXmlContextLoader}, and
+	 * GenericXmlContextLoader},
 	 * {@link org.springframework.test.context.support.AnnotationConfigContextLoader
-	 * AnnotationConfigContextLoader}.
+	 * AnnotationConfigContextLoader},
+	 * {@link org.springframework.test.context.web.GenericXmlWebContextLoader
+	 * GenericXmlWebContextLoader}, and
+	 * {@link org.springframework.test.context.web.AnnotationConfigWebContextLoader
+	 * AnnotationConfigWebContextLoader}.
+	 *
 	 * @since 2.5
 	 */
 	Class<? extends ContextLoader> loader() default ContextLoader.class;

spring-test/src/main/java/org/springframework/test/context/ContextHierarchy.java

@@ -28,11 +28,11 @@ import java.lang.annotation.Target;
  * a hierarchy of {@link org.springframework.context.ApplicationContext
  * ApplicationContexts} for integration tests.
  *
- * <h2>Examples</h2>
+ * <h3>Examples</h3>
  * <p>The following JUnit-based examples demonstrate common configuration
  * scenarios for integration tests that require the use of context hierarchies.
  *
- * <h3>Single Test Class with Context Hierarchy</h3>
+ * <h4>Single Test Class with Context Hierarchy</h4>
  * <p>{@code ControllerIntegrationTests} represents a typical integration testing
  * scenario for a Spring MVC web application by declaring a context hierarchy
  * consisting of two levels, one for the <em>root</em> {@code WebApplicationContext}
@@ -56,7 +56,7 @@ import java.lang.annotation.Target;
  *     // ...
  * }</pre>
  *
- * <h3>Class Hierarchy with Implicit Parent Context</h3>
+ * <h4>Class Hierarchy with Implicit Parent Context</h4>
  * <p>The following test classes define a context hierarchy within a test class
  * hierarchy. {@code AbstractWebTests} declares the configuration for a root
  * {@code WebApplicationContext} in a Spring-powered web application. Note,
@@ -82,7 +82,7 @@ import java.lang.annotation.Target;
  * &#064;ContextHierarchy(&#064;ContextConfiguration("/spring/rest-ws-config.xml")
  * public class RestWebServiceTests extends AbstractWebTests {}</pre>
  *
- * <h3>Class Hierarchy with Merged Context Hierarchy Configuration</h3>
+ * <h4>Class Hierarchy with Merged Context Hierarchy Configuration</h4>
  * <p>The following classes demonstrate the use of <em>named</em> hierarchy levels
  * in order to <em>merge</em> the configuration for specific levels in a context
  * hierarchy. {@code BaseTests} defines two levels in the hierarchy, {@code parent}
@@ -110,7 +110,7 @@ import java.lang.annotation.Target;
  * )
  * public class ExtendedTests extends BaseTests {}</pre>
  *
- * <h3>Class Hierarchy with Overridden Context Hierarchy Configuration</h3>
+ * <h4>Class Hierarchy with Overridden Context Hierarchy Configuration</h4>
  * <p>In contrast to the previous example, this example demonstrates how to
  * <em>override</em> the configuration for a given named level in a context hierarchy
  * by setting the {@link ContextConfiguration#inheritLocations} flag to {@code false}.