revised javadoc (SPR-5720)

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

@@ -39,19 +39,27 @@ import java.lang.annotation.Target;
 @Target(ElementType.TYPE)
 public @interface ContextConfiguration {
 
-	/**
-	 * The resource locations to use for loading an
-	 * {@link org.springframework.context.ApplicationContext ApplicationContext}.
-	 */
-	String[] locations() default {};
-
 	/**
 	 * Alias for {@link #locations() locations}.
-	 * 
 	 * @since 3.0
 	 */
 	String[] value() default {};
 
+	/**
+	 * The resource locations to use for loading an
+	 * {@link org.springframework.context.ApplicationContext ApplicationContext}.
+	 * <p>Check out {@link org.springframework.test.context.support.AbstractContextLoader#modifyLocations)}'s
+	 * javadoc for details on how a location String will be interpreted at runtime,
+	 * in particular in case of a relative path. Also, check out the documentation on
+	 * {@link org.springframework.test.context.support.AbstractContextLoader#generateDefaultLocations}
+	 * for details on the default locations that are going to be used if none are specified.
+	 * <p>Note that the above-mentioned default rules only apply for a standard
+	 * {@link org.springframework.test.context.support.AbstractContextLoader} subclass
+	 * such as {@link org.springframework.test.context.support.GenericXmlContextLoader}
+	 * which is the effective default implementation used at runtime.
+	 */
+	String[] locations() default {};
+
 	/**
 	 * Whether or not {@link #locations() resource locations} from superclasses
 	 * should be <em>inherited</em>.
@@ -91,6 +99,10 @@ public @interface ContextConfiguration {
 	 * which is annotated with <code>&#064;ContextConfiguration</code> and specifies
      * an 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
+	 * {@link org.springframework.test.context.support.GenericXmlContextLoader}.
+	 * Also check out {@link org.springframework.test.context.support.AbstractContextLoader}'s
+	 * javadoc for details on the default behavior there.
 	 */
 	Class<? extends ContextLoader> loader() default ContextLoader.class;
 

org.springframework.test/src/main/java/org/springframework/test/context/support/AbstractContextLoader.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2008 the original author or authors.
+ * Copyright 2002-2009 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.
@@ -28,8 +28,8 @@ import org.springframework.util.StringUtils;
 /**
  * Abstract application context loader, which provides a basis for all concrete
  * implementations of the {@link ContextLoader} strategy. Provides a
- * <em>Template Method</em> based approach for
+ * <em>Template Method</em> based approach for {@link #processLocations processing}
- * {@link #processLocations(Class,String...) processing} locations.
+ * locations.
  *
  * @author Sam Brannen
  * @author Juergen Hoeller
@@ -46,9 +46,8 @@ public abstract class AbstractContextLoader implements ContextLoader {
 	 * {@link #generateDefaultLocations(Class) generated} for the specified
 	 * {@link Class class} and the configured
 	 * {@link #getResourceSuffix() resource suffix}; otherwise, the supplied
-	 * <code>locations</code> will be
+	 * <code>locations</code> will be {@link #modifyLocations modified} if
-	 * {@link #modifyLocations(Class,String...) modified} if necessary and
+	 * necessary and returned.
-	 * returned.
 	 * @param clazz the class with which the locations are associated: to be
 	 * used when generating default locations
 	 * @param locations the unmodified locations to use for loading the

org.springframework.test/src/main/java/org/springframework/test/context/support/GenericXmlContextLoader.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2007 the original author or authors.
+ * Copyright 2002-2009 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,10 +21,8 @@ import org.springframework.beans.factory.xml.XmlBeanDefinitionReader;
 import org.springframework.context.support.GenericApplicationContext;
 
 /**
- * <p>
  * Concrete implementation of {@link AbstractGenericContextLoader} which reads
  * bean definitions from XML resources.
- * </p>
  *
  * @author Sam Brannen
  * @since 2.5
@@ -32,12 +30,8 @@ import org.springframework.context.support.GenericApplicationContext;
 public class GenericXmlContextLoader extends AbstractGenericContextLoader {
 
 	/**
-	 * <p>
+	 * Create a new {@link XmlBeanDefinitionReader}.
-	 * Creates a new {@link XmlBeanDefinitionReader}.
-	 * </p>
-	 *
 	 * @return a new XmlBeanDefinitionReader.
-	 * @see AbstractGenericContextLoader#createBeanDefinitionReader(GenericApplicationContext)
 	 * @see XmlBeanDefinitionReader
 	 */
 	@Override
@@ -47,8 +41,6 @@ public class GenericXmlContextLoader extends AbstractGenericContextLoader {
 
 	/**
 	 * Returns &quot;<code>-context.xml</code>&quot;.
-	 *
-	 * @see org.springframework.test.context.support.AbstractContextLoader#getResourceSuffix()
 	 */
 	@Override
 	public String getResourceSuffix() {