Javadoc format and related polishing

(cherry picked from commit 9d0e62e)

spring-context/src/main/java/org/springframework/cache/annotation/CachingConfigurer.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2014 the original author or authors.
+ * Copyright 2002-2018 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.
@@ -33,6 +33,7 @@ import org.springframework.cache.interceptor.KeyGenerator;
  * for detailed instructions.
  *
  * @author Chris Beams
+ * @author Stephane Nicoll
  * @since 3.1
  * @see EnableCaching
  * @see CachingConfigurerSupport
@@ -67,8 +68,8 @@ public interface CachingConfigurer {
 	 * Return the {@link CacheResolver} bean to use to resolve regular caches for
 	 * annotation-driven cache management. This is an alternative and more powerful
 	 * option of specifying the {@link CacheManager} to use.
-	 * <p>If both a {@link #cacheManager()} and {@link #cacheResolver()} are set, the
-	 * cache manager is ignored.
+	 * <p>If both a {@link #cacheManager()} and {@code #cacheResolver()} are set,
+	 * the cache manager is ignored.
 	 * <p>Implementations must explicitly declare
 	 * {@link org.springframework.context.annotation.Bean @Bean}, e.g.
 	 * <pre class="code">

spring-context/src/main/java/org/springframework/context/support/PropertySourcesPlaceholderConfigurer.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2016 the original author or authors.
+ * Copyright 2002-2018 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.
@@ -183,7 +183,7 @@ public class PropertySourcesPlaceholderConfigurer extends PlaceholderConfigurerS
 	/**
 	 * Implemented for compatibility with {@link org.springframework.beans.factory.config.PlaceholderConfigurerSupport}.
 	 * @deprecated in favor of {@link #processProperties(ConfigurableListableBeanFactory, ConfigurablePropertyResolver)}
-	 * @throws UnsupportedOperationException
+	 * @throws UnsupportedOperationException in this implementation
 	 */
 	@Override
 	@Deprecated

spring-jdbc/src/main/java/org/springframework/jdbc/core/ArgumentPreparedStatementSetter.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2013 the original author or authors.
+ * Copyright 2002-2018 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.
@@ -55,7 +55,7 @@ public class ArgumentPreparedStatementSetter implements PreparedStatementSetter,
 	 * @param ps the PreparedStatement
 	 * @param parameterPosition index of the parameter position
 	 * @param argValue the value to set
-	 * @throws SQLException
+	 * @throws SQLException if thrown by PreparedStatement methods
 	 */
 	protected void doSetValue(PreparedStatement ps, int parameterPosition, Object argValue) throws SQLException {
 		if (argValue instanceof SqlParameterValue) {

spring-jdbc/src/main/java/org/springframework/jdbc/core/ArgumentTypePreparedStatementSetter.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2013 the original author or authors.
+ * Copyright 2002-2018 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.
@@ -89,7 +89,7 @@ public class ArgumentTypePreparedStatementSetter implements PreparedStatementSet
 	 * @param parameterPosition index of the parameter position
 	 * @param argType the argument type
 	 * @param argValue the argument value
-	 * @throws SQLException
+	 * @throws SQLException if thrown by PreparedStatement methods
 	 */
 	protected void doSetValue(PreparedStatement ps, int parameterPosition, int argType, Object argValue)
 			throws SQLException {

spring-orm-hibernate5/src/main/java/org/springframework/orm/hibernate5/SessionFactoryUtils.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2017 the original author or authors.
+ * Copyright 2002-2018 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.
@@ -130,7 +130,7 @@ public abstract class SessionFactoryUtils {
 	 * {@link PersistenceException} wrappers accordingly.
 	 * @param session the Hibernate Session to flush
 	 * @param synch whether this flush is triggered by transaction synchronization
-	 * @throws DataAccessException
+	 * @throws DataAccessException in case of flush failures
 	 * @since 4.3.2
 	 */
 	static void flush(Session session, boolean synch) throws DataAccessException {

spring-test/src/main/java/org/springframework/test/annotation/IfProfileValue.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2016 the original author or authors.
+ * Copyright 2002-2018 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.
@@ -109,7 +109,7 @@ public @interface IfProfileValue {
 	/**
 	 * A single, permissible {@code value} of the <em>profile value</em>
 	 * for the given {@link #name}.
-	 * <p>Note: Assigning values to both {@link #value} and {@link #values}
+	 * <p>Note: Assigning values to both {@code #value} and {@link #values}
 	 * will lead to a configuration conflict.
 	 */
 	String value() default "";
@@ -117,7 +117,7 @@ public @interface IfProfileValue {
 	/**
 	 * A list of all permissible {@code values} of the <em>profile value</em>
 	 * for the given {@link #name}.
-	 * <p>Note: Assigning values to both {@link #value} and {@link #values}
+	 * <p>Note: Assigning values to both {@link #value} and {@code #values}
 	 * will lead to a configuration conflict.
 	 */
 	String[] values() default {};

spring-test/src/main/java/org/springframework/test/context/cache/ContextCache.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2016 the original author or authors.
+ * Copyright 2002-2018 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.
@@ -53,7 +53,7 @@ public interface ContextCache {
 	String CONTEXT_CACHE_LOGGING_CATEGORY = "org.springframework.test.context.cache";
 
 	/**
-	 * The default maximum size of the context cache: {@value #DEFAULT_MAX_CONTEXT_CACHE_SIZE}.
+	 * The default maximum size of the context cache: {@value}.
 	 * @since 4.3
 	 * @see #MAX_CONTEXT_CACHE_SIZE_PROPERTY_NAME
 	 */

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

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2016 the original author or authors.
+ * Copyright 2002-2018 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.
@@ -72,7 +72,7 @@ public abstract class AbstractContextLoader implements SmartContextLoader {
 	private static final Log logger = LogFactory.getLog(AbstractContextLoader.class);
 
 
-	// --- SmartContextLoader -----------------------------------------------
+	// SmartContextLoader
 
 	/**
 	 * For backwards compatibility with the {@link ContextLoader} SPI, the
@@ -189,7 +189,7 @@ public abstract class AbstractContextLoader implements SmartContextLoader {
 	}
 
 
-	// --- ContextLoader -------------------------------------------------------
+	// ContextLoader
 
 	/**
 	 * If the supplied {@code locations} are {@code null} or <em>empty</em>

spring-test/src/main/java/org/springframework/test/context/support/AbstractDelegatingSmartContextLoader.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2016 the original author or authors.
+ * Copyright 2002-2018 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.
@@ -66,6 +66,7 @@ import org.springframework.util.Assert;
  * not result in an exception.
  *
  * @author Sam Brannen
+ * @author Phillip Webb
  * @since 3.2
  * @see SmartContextLoader
  */
@@ -85,16 +86,13 @@ public abstract class AbstractDelegatingSmartContextLoader implements SmartConte
 	 */
 	protected abstract SmartContextLoader getAnnotationConfigLoader();
 
-	// --- SmartContextLoader --------------------------------------------------
 
-	private static String name(SmartContextLoader loader) {
-		return loader.getClass().getSimpleName();
-	}
+	// SmartContextLoader
 
 	private static void delegateProcessing(SmartContextLoader loader, ContextConfigurationAttributes configAttributes) {
 		if (logger.isDebugEnabled()) {
-			logger.debug(String.format("Delegating to %s to process context configuration %s.", name(loader),
-				configAttributes));
+			logger.debug(String.format("Delegating to %s to process context configuration %s.",
+					name(loader), configAttributes));
 		}
 		loader.processContextConfiguration(configAttributes);
 	}
@@ -110,10 +108,10 @@ public abstract class AbstractDelegatingSmartContextLoader implements SmartConte
 
 	private boolean supports(SmartContextLoader loader, MergedContextConfiguration mergedConfig) {
 		if (loader == getAnnotationConfigLoader()) {
-			return mergedConfig.hasClasses() && !mergedConfig.hasLocations();
+			return (mergedConfig.hasClasses() && !mergedConfig.hasLocations());
 		}
 		else {
-			return mergedConfig.hasLocations() && !mergedConfig.hasClasses();
+			return (mergedConfig.hasLocations() && !mergedConfig.hasClasses());
 		}
 	}
 
@@ -152,8 +150,8 @@ public abstract class AbstractDelegatingSmartContextLoader implements SmartConte
 	public void processContextConfiguration(final ContextConfigurationAttributes configAttributes) {
 		Assert.notNull(configAttributes, "configAttributes must not be null");
 		Assert.isTrue(!(configAttributes.hasLocations() && configAttributes.hasClasses()), String.format(
-			"Cannot process locations AND classes for context configuration %s: "
-					+ "configure one or the other, but not both.", configAttributes));
+				"Cannot process locations AND classes for context configuration %s: " +
+				"configure one or the other, but not both.", configAttributes));
 
 		// If the original locations or classes were not empty, there's no
 		// need to bother with default detection checks; just let the
@@ -174,14 +172,14 @@ public abstract class AbstractDelegatingSmartContextLoader implements SmartConte
 			if (xmlLoaderDetectedDefaults) {
 				if (logger.isInfoEnabled()) {
 					logger.info(String.format("%s detected default locations for context configuration %s.",
-						name(getXmlLoader()), configAttributes));
+							name(getXmlLoader()), configAttributes));
 				}
 			}
 
 			if (configAttributes.hasClasses()) {
 				throw new IllegalStateException(String.format(
-					"%s should NOT have detected default configuration classes for context configuration %s.",
-					name(getXmlLoader()), configAttributes));
+						"%s should NOT have detected default configuration classes for context configuration %s.",
+						name(getXmlLoader()), configAttributes));
 			}
 
 			// Now let the annotation config loader process the configuration.
@@ -190,24 +188,24 @@ public abstract class AbstractDelegatingSmartContextLoader implements SmartConte
 			if (configAttributes.hasClasses()) {
 				if (logger.isInfoEnabled()) {
 					logger.info(String.format(
-						"%s detected default configuration classes for context configuration %s.",
-						name(getAnnotationConfigLoader()), configAttributes));
+							"%s detected default configuration classes for context configuration %s.",
+							name(getAnnotationConfigLoader()), configAttributes));
 				}
 			}
 
 			if (!xmlLoaderDetectedDefaults && configAttributes.hasLocations()) {
 				throw new IllegalStateException(String.format(
-					"%s should NOT have detected default locations for context configuration %s.",
-					name(getAnnotationConfigLoader()), configAttributes));
+						"%s should NOT have detected default locations for context configuration %s.",
+						name(getAnnotationConfigLoader()), configAttributes));
 			}
 
 			if (configAttributes.hasLocations() && configAttributes.hasClasses()) {
-				String message = String.format(
-					"Configuration error: both default locations AND default configuration classes "
-							+ "were detected for context configuration %s; configure one or the other, but not both.",
-					configAttributes);
-				logger.error(message);
-				throw new IllegalStateException(message);
+				String msg = String.format(
+						"Configuration error: both default locations AND default configuration classes " +
+						"were detected for context configuration %s; configure one or the other, but not both.",
+						configAttributes);
+				logger.error(msg);
+				throw new IllegalStateException(msg);
 			}
 		}
 	}
@@ -239,9 +237,9 @@ public abstract class AbstractDelegatingSmartContextLoader implements SmartConte
 
 		if (mergedConfig.hasLocations() && mergedConfig.hasClasses()) {
 			throw new IllegalStateException(String.format(
-				"Neither %s nor %s supports loading an ApplicationContext from %s: "
-						+ "declare either 'locations' or 'classes' but not both.", name(getXmlLoader()),
-				name(getAnnotationConfigLoader()), mergedConfig));
+					"Neither %s nor %s supports loading an ApplicationContext from %s: " +
+					"declare either 'locations' or 'classes' but not both.", name(getXmlLoader()),
+					name(getAnnotationConfigLoader()), mergedConfig));
 		}
 
 		for (SmartContextLoader loader : candidates) {
@@ -261,22 +259,28 @@ public abstract class AbstractDelegatingSmartContextLoader implements SmartConte
 
 		// else...
 		throw new IllegalStateException(String.format(
-			"Neither %s nor %s was able to load an ApplicationContext from %s.", name(getXmlLoader()),
-			name(getAnnotationConfigLoader()), mergedConfig));
+				"Neither %s nor %s was able to load an ApplicationContext from %s.", name(getXmlLoader()),
+				name(getAnnotationConfigLoader()), mergedConfig));
 	}
 
-	// --- ContextLoader -------------------------------------------------------
+	private static String name(SmartContextLoader loader) {
+		return loader.getClass().getSimpleName();
+	}
+
+
+	// ContextLoader
 
 	/**
 	 * {@code AbstractDelegatingSmartContextLoader} does not support the
 	 * {@link ContextLoader#processLocations(Class, String...)} method. Call
 	 * {@link #processContextConfiguration(ContextConfigurationAttributes)} instead.
-	 * @throws UnsupportedOperationException
+	 * @throws UnsupportedOperationException in this implementation
 	 */
 	@Override
 	public final String[] processLocations(Class<?> clazz, String... locations) {
-		throw new UnsupportedOperationException("DelegatingSmartContextLoaders do not support the ContextLoader SPI. "
-				+ "Call processContextConfiguration(ContextConfigurationAttributes) instead.");
+		throw new UnsupportedOperationException(
+				"DelegatingSmartContextLoaders do not support the ContextLoader SPI. " +
+				"Call processContextConfiguration(ContextConfigurationAttributes) instead.");
 	}
 
 	/**
@@ -287,8 +291,9 @@ public abstract class AbstractDelegatingSmartContextLoader implements SmartConte
 	 */
 	@Override
 	public final ApplicationContext loadContext(String... locations) throws Exception {
-		throw new UnsupportedOperationException("DelegatingSmartContextLoaders do not support the ContextLoader SPI. "
-				+ "Call loadContext(MergedContextConfiguration) instead.");
+		throw new UnsupportedOperationException(
+				"DelegatingSmartContextLoaders do not support the ContextLoader SPI. " +
+				"Call loadContext(MergedContextConfiguration) instead.");
 	}
 
 }

spring-test/src/main/java/org/springframework/test/context/support/AnnotationConfigContextLoader.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2014 the original author or authors.
+ * Copyright 2002-2018 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.
@@ -58,11 +58,10 @@ public class AnnotationConfigContextLoader extends AbstractGenericContextLoader
 	private static final Log logger = LogFactory.getLog(AnnotationConfigContextLoader.class);
 
 
-	// --- SmartContextLoader -----------------------------------------------
+	// SmartContextLoader
 
 	/**
 	 * Process <em>annotated classes</em> in the supplied {@link ContextConfigurationAttributes}.
-	 *
 	 * <p>If the <em>annotated classes</em> are {@code null} or empty and
 	 * {@link #isGenerateDefaultLocations()} returns {@code true}, this
 	 * {@code SmartContextLoader} will attempt to {@link
@@ -71,7 +70,6 @@ public class AnnotationConfigContextLoader extends AbstractGenericContextLoader
 	 * {@link ContextConfigurationAttributes#setClasses(Class[]) set} in the
 	 * supplied configuration attributes. Otherwise, properties in the supplied
 	 * configuration attributes will not be modified.
-	 *
 	 * @param configAttributes the context configuration attributes to process
 	 * @see org.springframework.test.context.SmartContextLoader#processContextConfiguration(ContextConfigurationAttributes)
 	 * @see #isGenerateDefaultLocations()
@@ -84,14 +82,13 @@ public class AnnotationConfigContextLoader extends AbstractGenericContextLoader
 		}
 	}
 
-	// --- AnnotationConfigContextLoader ---------------------------------------
+
+	// AnnotationConfigContextLoader
 
 	/**
 	 * Detect the default configuration classes for the supplied test class.
-	 *
 	 * <p>The default implementation simply delegates to
 	 * {@link AnnotationConfigContextLoaderUtils#detectDefaultConfigurationClasses(Class)}.
-	 *
 	 * @param declaringClass the test class that declared {@code @ContextConfiguration}
 	 * @return an array of default configuration classes, potentially empty but
 	 * never {@code null}
@@ -101,21 +98,21 @@ public class AnnotationConfigContextLoader extends AbstractGenericContextLoader
 		return AnnotationConfigContextLoaderUtils.detectDefaultConfigurationClasses(declaringClass);
 	}
 
-	// --- AbstractContextLoader -----------------------------------------------
+
+	// AbstractContextLoader
 
 	/**
 	 * {@code AnnotationConfigContextLoader} should be used as a
 	 * {@link org.springframework.test.context.SmartContextLoader SmartContextLoader},
 	 * not as a legacy {@link org.springframework.test.context.ContextLoader ContextLoader}.
 	 * Consequently, this method is not supported.
-	 *
+	 * @throws UnsupportedOperationException in this implementation
 	 * @see AbstractContextLoader#modifyLocations
-	 * @throws UnsupportedOperationException
 	 */
 	@Override
 	protected String[] modifyLocations(Class<?> clazz, String... locations) {
 		throw new UnsupportedOperationException(
-			"AnnotationConfigContextLoader does not support the modifyLocations(Class, String...) method");
+				"AnnotationConfigContextLoader does not support the modifyLocations(Class, String...) method");
 	}
 
 	/**
@@ -123,14 +120,13 @@ public class AnnotationConfigContextLoader extends AbstractGenericContextLoader
 	 * {@link org.springframework.test.context.SmartContextLoader SmartContextLoader},
 	 * not as a legacy {@link org.springframework.test.context.ContextLoader ContextLoader}.
 	 * Consequently, this method is not supported.
-	 *
+	 * @throws UnsupportedOperationException in this implementation
 	 * @see AbstractContextLoader#generateDefaultLocations
-	 * @throws UnsupportedOperationException
 	 */
 	@Override
 	protected String[] generateDefaultLocations(Class<?> clazz) {
 		throw new UnsupportedOperationException(
-			"AnnotationConfigContextLoader does not support the generateDefaultLocations(Class) method");
+				"AnnotationConfigContextLoader does not support the generateDefaultLocations(Class) method");
 	}
 
 	/**
@@ -138,17 +134,17 @@ public class AnnotationConfigContextLoader extends AbstractGenericContextLoader
 	 * {@link org.springframework.test.context.SmartContextLoader SmartContextLoader},
 	 * not as a legacy {@link org.springframework.test.context.ContextLoader ContextLoader}.
 	 * Consequently, this method is not supported.
-	 *
+	 * @throws UnsupportedOperationException in this implementation
 	 * @see AbstractContextLoader#getResourceSuffix
-	 * @throws UnsupportedOperationException
 	 */
 	@Override
 	protected String getResourceSuffix() {
 		throw new UnsupportedOperationException(
-			"AnnotationConfigContextLoader does not support the getResourceSuffix() method");
+				"AnnotationConfigContextLoader does not support the getResourceSuffix() method");
 	}
 
-	// --- AbstractGenericContextLoader ----------------------------------------
+
+	// AbstractGenericContextLoader
 
 	/**
 	 * Ensure that the supplied {@link MergedContextConfiguration} does not
@@ -159,10 +155,10 @@ public class AnnotationConfigContextLoader extends AbstractGenericContextLoader
 	@Override
 	protected void validateMergedContextConfiguration(MergedContextConfiguration mergedConfig) {
 		if (mergedConfig.hasLocations()) {
-			String msg = String.format(
-				"Test class [%s] has been configured with @ContextConfiguration's 'locations' (or 'value') attribute %s, "
-						+ "but %s does not support resource locations.", mergedConfig.getTestClass().getName(),
-				ObjectUtils.nullSafeToString(mergedConfig.getLocations()), getClass().getSimpleName());
+			String msg = String.format("Test class [%s] has been configured with @ContextConfiguration's 'locations' " +
+							"(or 'value') attribute %s, but %s does not support resource locations.",
+					mergedConfig.getTestClass().getName(), ObjectUtils.nullSafeToString(mergedConfig.getLocations()),
+					getClass().getSimpleName());
 			logger.error(msg);
 			throw new IllegalStateException(msg);
 		}
@@ -171,18 +167,14 @@ public class AnnotationConfigContextLoader extends AbstractGenericContextLoader
 	/**
 	 * Register classes in the supplied {@link GenericApplicationContext context}
 	 * from the classes in the supplied {@link MergedContextConfiguration}.
-	 *
 	 * <p>Each class must represent an <em>annotated class</em>. An
 	 * {@link AnnotatedBeanDefinitionReader} is used to register the appropriate
 	 * bean definitions.
-	 *
 	 * <p>Note that this method does not call {@link #createBeanDefinitionReader}
 	 * since {@code AnnotatedBeanDefinitionReader} is not an instance of
 	 * {@link BeanDefinitionReader}.
-	 *
 	 * @param context the context in which the annotated classes should be registered
 	 * @param mergedConfig the merged configuration from which the classes should be retrieved
-	 *
 	 * @see AbstractGenericContextLoader#loadBeanDefinitions
 	 */
 	@Override
@@ -199,15 +191,14 @@ public class AnnotationConfigContextLoader extends AbstractGenericContextLoader
 	 * {@link org.springframework.test.context.SmartContextLoader SmartContextLoader},
 	 * not as a legacy {@link org.springframework.test.context.ContextLoader ContextLoader}.
 	 * Consequently, this method is not supported.
-	 *
+	 * @throws UnsupportedOperationException in this implementation
 	 * @see #loadBeanDefinitions
 	 * @see AbstractGenericContextLoader#createBeanDefinitionReader
-	 * @throws UnsupportedOperationException
 	 */
 	@Override
 	protected BeanDefinitionReader createBeanDefinitionReader(GenericApplicationContext context) {
 		throw new UnsupportedOperationException(
-			"AnnotationConfigContextLoader does not support the createBeanDefinitionReader(GenericApplicationContext) method");
+				"AnnotationConfigContextLoader does not support the createBeanDefinitionReader(GenericApplicationContext) method");
 	}
 
 }

spring-test/src/main/java/org/springframework/test/context/support/GenericGroovyXmlContextLoader.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2015 the original author or authors.
+ * Copyright 2002-2018 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.
@@ -39,7 +39,6 @@ public class GenericGroovyXmlContextLoader extends GenericXmlContextLoader {
 	 * Load bean definitions into the supplied {@link GenericApplicationContext context}
 	 * from the locations in the supplied {@code MergedContextConfiguration} using a
 	 * {@link GroovyBeanDefinitionReader}.
-	 *
 	 * @param context the context into which the bean definitions should be loaded
 	 * @param mergedConfig the merged context configuration
 	 * @see org.springframework.test.context.support.AbstractGenericContextLoader#loadBeanDefinitions
@@ -63,12 +62,12 @@ public class GenericGroovyXmlContextLoader extends GenericXmlContextLoader {
 	 * resource types for detection of defaults. Consequently, this method
 	 * is not supported.
 	 * @see #getResourceSuffixes()
-	 * @throws UnsupportedOperationException
+	 * @throws UnsupportedOperationException in this implementation
 	 */
 	@Override
 	protected String getResourceSuffix() {
 		throw new UnsupportedOperationException(
-			"GenericGroovyXmlContextLoader does not support the getResourceSuffix() method");
+				"GenericGroovyXmlContextLoader does not support the getResourceSuffix() method");
 	}
 
 }

spring-test/src/main/java/org/springframework/test/context/web/AbstractGenericWebContextLoader.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2016 the original author or authors.
+ * Copyright 2002-2018 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.
@@ -63,14 +63,12 @@ public abstract class AbstractGenericWebContextLoader extends AbstractContextLoa
 	protected static final Log logger = LogFactory.getLog(AbstractGenericWebContextLoader.class);
 
 
-	// --- SmartContextLoader -----------------------------------------------
+	// SmartContextLoader
 
 	/**
 	 * Load a Spring {@link WebApplicationContext} from the supplied
 	 * {@link MergedContextConfiguration}.
-	 *
 	 * <p>Implementation details:
-	 *
 	 * <ul>
 	 * <li>Calls {@link #validateMergedContextConfiguration(WebMergedContextConfiguration)}
 	 * to allow subclasses to validate the supplied configuration before proceeding.</li>
@@ -97,18 +95,16 @@ public abstract class AbstractGenericWebContextLoader extends AbstractContextLoa
 	 * <li>{@link ConfigurableApplicationContext#refresh Refreshes} the
 	 * context and registers a JVM shutdown hook for it.</li>
 	 * </ul>
-	 *
 	 * @return a new web application context
 	 * @see org.springframework.test.context.SmartContextLoader#loadContext(MergedContextConfiguration)
 	 * @see GenericWebApplicationContext
 	 */
 	@Override
 	public final ConfigurableApplicationContext loadContext(MergedContextConfiguration mergedConfig) throws Exception {
-
 		if (!(mergedConfig instanceof WebMergedContextConfiguration)) {
 			throw new IllegalArgumentException(String.format(
-				"Cannot load WebApplicationContext from non-web merged context configuration %s. "
-						+ "Consider annotating your test class with @WebAppConfiguration.", mergedConfig));
+					"Cannot load WebApplicationContext from non-web merged context configuration %s. " +
+					"Consider annotating your test class with @WebAppConfiguration.", mergedConfig));
 		}
 		WebMergedContextConfiguration webMergedConfig = (WebMergedContextConfiguration) mergedConfig;
 
@@ -152,20 +148,15 @@ public abstract class AbstractGenericWebContextLoader extends AbstractContextLoa
 
 	/**
 	 * Configures web resources for the supplied web application context (WAC).
-	 *
 	 * <h4>Implementation Details</h4>
-	 *
 	 * <p>If the supplied WAC has no parent or its parent is not a WAC, the
 	 * supplied WAC will be configured as the Root WAC (see "<em>Root WAC
 	 * Configuration</em>" below).
-	 *
 	 * <p>Otherwise the context hierarchy of the supplied WAC will be traversed
 	 * to find the top-most WAC (i.e., the root); and the {@link ServletContext}
 	 * of the Root WAC will be set as the {@code ServletContext} for the supplied
 	 * WAC.
-	 *
 	 * <h4>Root WAC Configuration</h4>
-	 *
 	 * <ul>
 	 * <li>The resource base path is retrieved from the supplied
 	 * {@code WebMergedContextConfiguration}.</li>
@@ -180,32 +171,27 @@ public abstract class AbstractGenericWebContextLoader extends AbstractContextLoa
 	 * {@link WebApplicationContext#ROOT_WEB_APPLICATION_CONTEXT_ATTRIBUTE} key.</li>
 	 * <li>Finally, the {@code MockServletContext} is set in the
 	 * {@code WebApplicationContext}.</li>
-	 *
-	 * @param context the web application context for which to configure the web
-	 * resources
-	 * @param webMergedConfig the merged context configuration to use to load the
-	 * web application context
+	 * @param context the web application context for which to configure the web resources
+	 * @param webMergedConfig the merged context configuration to use to load the web application context
 	 */
 	protected void configureWebResources(GenericWebApplicationContext context,
 			WebMergedContextConfiguration webMergedConfig) {
 
 		ApplicationContext parent = context.getParent();
 
-		// if the WAC has no parent or the parent is not a WAC, set the WAC as
-		// the Root WAC:
+		// If the WebApplicationContext has no parent or the parent is not a WebApplicationContext,
+		// set the current context as the root WebApplicationContext:
 		if (parent == null || (!(parent instanceof WebApplicationContext))) {
 			String resourceBasePath = webMergedConfig.getResourceBasePath();
-			ResourceLoader resourceLoader = resourceBasePath.startsWith(ResourceLoader.CLASSPATH_URL_PREFIX) ? new DefaultResourceLoader()
-					: new FileSystemResourceLoader();
-
+			ResourceLoader resourceLoader = (resourceBasePath.startsWith(ResourceLoader.CLASSPATH_URL_PREFIX) ?
+					new DefaultResourceLoader() : new FileSystemResourceLoader());
 			ServletContext servletContext = new MockServletContext(resourceBasePath, resourceLoader);
 			servletContext.setAttribute(WebApplicationContext.ROOT_WEB_APPLICATION_CONTEXT_ATTRIBUTE, context);
 			context.setServletContext(servletContext);
 		}
 		else {
 			ServletContext servletContext = null;
-
-			// find the Root WAC
+			// Find the root WebApplicationContext
 			while (parent != null) {
 				if (parent instanceof WebApplicationContext && !(parent.getParent() instanceof WebApplicationContext)) {
 					servletContext = ((WebApplicationContext) parent).getServletContext();
@@ -213,7 +199,7 @@ public abstract class AbstractGenericWebContextLoader extends AbstractContextLoa
 				}
 				parent = parent.getParent();
 			}
-			Assert.state(servletContext != null, "Failed to find Root WebApplicationContext in the context hierarchy");
+			Assert.state(servletContext != null, "Failed to find root WebApplicationContext in the context hierarchy");
 			context.setServletContext(servletContext);
 		}
 	}
@@ -221,10 +207,8 @@ public abstract class AbstractGenericWebContextLoader extends AbstractContextLoa
 	/**
 	 * Customize the internal bean factory of the {@code WebApplicationContext}
 	 * created by this context loader.
-	 *
 	 * <p>The default implementation is empty but can be overridden in subclasses
 	 * to customize {@code DefaultListableBeanFactory}'s standard settings.
-	 *
 	 * @param beanFactory the bean factory created by this context loader
 	 * @param webMergedConfig the merged context configuration to use to load the
 	 * web application context
@@ -234,57 +218,55 @@ public abstract class AbstractGenericWebContextLoader extends AbstractContextLoa
 	 * @see DefaultListableBeanFactory#setAllowCircularReferences
 	 * @see DefaultListableBeanFactory#setAllowRawInjectionDespiteWrapping
 	 */
-	protected void customizeBeanFactory(DefaultListableBeanFactory beanFactory,
-			WebMergedContextConfiguration webMergedConfig) {
+	protected void customizeBeanFactory(
+			DefaultListableBeanFactory beanFactory, WebMergedContextConfiguration webMergedConfig) {
 	}
 
 	/**
 	 * Load bean definitions into the supplied {@link GenericWebApplicationContext context}
 	 * from the locations or classes in the supplied {@code WebMergedContextConfiguration}.
-	 *
 	 * <p>Concrete subclasses must provide an appropriate implementation.
-	 *
 	 * @param context the context into which the bean definitions should be loaded
 	 * @param webMergedConfig the merged context configuration to use to load the
 	 * web application context
 	 * @see #loadContext(MergedContextConfiguration)
 	 */
-	protected abstract void loadBeanDefinitions(GenericWebApplicationContext context,
-			WebMergedContextConfiguration webMergedConfig);
+	protected abstract void loadBeanDefinitions(
+			GenericWebApplicationContext context, WebMergedContextConfiguration webMergedConfig);
 
 	/**
 	 * Customize the {@link GenericWebApplicationContext} created by this context
 	 * loader <i>after</i> bean definitions have been loaded into the context but
 	 * <i>before</i> the context is refreshed.
-	 *
 	 * <p>The default implementation simply delegates to
 	 * {@link AbstractContextLoader#customizeContext(ConfigurableApplicationContext, MergedContextConfiguration)}.
-	 *
 	 * @param context the newly created web application context
 	 * @param webMergedConfig the merged context configuration to use to load the
 	 * web application context
 	 * @see #loadContext(MergedContextConfiguration)
 	 * @see #customizeContext(ConfigurableApplicationContext, MergedContextConfiguration)
 	 */
-	protected void customizeContext(GenericWebApplicationContext context, WebMergedContextConfiguration webMergedConfig) {
+	protected void customizeContext(
+			GenericWebApplicationContext context, WebMergedContextConfiguration webMergedConfig) {
+
 		super.customizeContext(context, webMergedConfig);
 	}
 
-	// --- ContextLoader -------------------------------------------------------
+
+	// ContextLoader
 
 	/**
 	 * {@code AbstractGenericWebContextLoader} should be used as a
 	 * {@link org.springframework.test.context.SmartContextLoader SmartContextLoader},
 	 * not as a legacy {@link org.springframework.test.context.ContextLoader ContextLoader}.
 	 * Consequently, this method is not supported.
-	 *
 	 * @see org.springframework.test.context.ContextLoader#loadContext(java.lang.String[])
-	 * @throws UnsupportedOperationException
+	 * @throws UnsupportedOperationException in this implementation
 	 */
 	@Override
 	public final ApplicationContext loadContext(String... locations) throws Exception {
 		throw new UnsupportedOperationException(
-			"AbstractGenericWebContextLoader does not support the loadContext(String... locations) method");
+				"AbstractGenericWebContextLoader does not support the loadContext(String... locations) method");
 	}
 
 }

spring-test/src/main/java/org/springframework/test/context/web/AnnotationConfigWebContextLoader.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2014 the original author or authors.
+ * Copyright 2002-2018 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.
@@ -59,11 +59,10 @@ public class AnnotationConfigWebContextLoader extends AbstractGenericWebContextL
 	private static final Log logger = LogFactory.getLog(AnnotationConfigWebContextLoader.class);
 
 
-	// --- SmartContextLoader -----------------------------------------------
+	// SmartContextLoader
 
 	/**
 	 * Process <em>annotated classes</em> in the supplied {@link ContextConfigurationAttributes}.
-	 *
 	 * <p>If the <em>annotated classes</em> are {@code null} or empty and
 	 * {@link #isGenerateDefaultLocations()} returns {@code true}, this
 	 * {@code SmartContextLoader} will attempt to {@linkplain
@@ -72,7 +71,6 @@ public class AnnotationConfigWebContextLoader extends AbstractGenericWebContextL
 	 * {@linkplain ContextConfigurationAttributes#setClasses(Class[]) set} in the
 	 * supplied configuration attributes. Otherwise, properties in the supplied
 	 * configuration attributes will not be modified.
-	 *
 	 * @param configAttributes the context configuration attributes to process
 	 * @see org.springframework.test.context.SmartContextLoader#processContextConfiguration(ContextConfigurationAttributes)
 	 * @see #isGenerateDefaultLocations()
@@ -87,34 +85,31 @@ public class AnnotationConfigWebContextLoader extends AbstractGenericWebContextL
 
 	/**
 	 * Detect the default configuration classes for the supplied test class.
-	 *
 	 * <p>The default implementation simply delegates to
 	 * {@link AnnotationConfigContextLoaderUtils#detectDefaultConfigurationClasses(Class)}.
-	 *
 	 * @param declaringClass the test class that declared {@code @ContextConfiguration}
-	 * @return an array of default configuration classes, potentially empty but
-	 * never {@code null}
+	 * @return an array of default configuration classes, potentially empty but never {@code null}
 	 * @see AnnotationConfigContextLoaderUtils
 	 */
 	protected Class<?>[] detectDefaultConfigurationClasses(Class<?> declaringClass) {
 		return AnnotationConfigContextLoaderUtils.detectDefaultConfigurationClasses(declaringClass);
 	}
 
-	// --- AbstractContextLoader -----------------------------------------------
+
+	// AbstractContextLoader
 
 	/**
 	 * {@code AnnotationConfigWebContextLoader} should be used as a
 	 * {@link org.springframework.test.context.SmartContextLoader SmartContextLoader},
 	 * not as a legacy {@link org.springframework.test.context.ContextLoader ContextLoader}.
 	 * Consequently, this method is not supported.
-	 *
+	 * @throws UnsupportedOperationException in this implementation
 	 * @see org.springframework.test.context.support.AbstractContextLoader#modifyLocations
-	 * @throws UnsupportedOperationException
 	 */
 	@Override
 	protected String[] modifyLocations(Class<?> clazz, String... locations) {
 		throw new UnsupportedOperationException(
-			"AnnotationConfigWebContextLoader does not support the modifyLocations(Class, String...) method");
+				"AnnotationConfigWebContextLoader does not support the modifyLocations(Class, String...) method");
 	}
 
 	/**
@@ -122,14 +117,13 @@ public class AnnotationConfigWebContextLoader extends AbstractGenericWebContextL
 	 * {@link org.springframework.test.context.SmartContextLoader SmartContextLoader},
 	 * not as a legacy {@link org.springframework.test.context.ContextLoader ContextLoader}.
 	 * Consequently, this method is not supported.
-	 *
+	 * @throws UnsupportedOperationException in this implementation
 	 * @see org.springframework.test.context.support.AbstractContextLoader#generateDefaultLocations
-	 * @throws UnsupportedOperationException
 	 */
 	@Override
 	protected String[] generateDefaultLocations(Class<?> clazz) {
 		throw new UnsupportedOperationException(
-			"AnnotationConfigWebContextLoader does not support the generateDefaultLocations(Class) method");
+				"AnnotationConfigWebContextLoader does not support the generateDefaultLocations(Class) method");
 	}
 
 	/**
@@ -137,34 +131,32 @@ public class AnnotationConfigWebContextLoader extends AbstractGenericWebContextL
 	 * {@link org.springframework.test.context.SmartContextLoader SmartContextLoader},
 	 * not as a legacy {@link org.springframework.test.context.ContextLoader ContextLoader}.
 	 * Consequently, this method is not supported.
-	 *
+	 * @throws UnsupportedOperationException in this implementation
 	 * @see org.springframework.test.context.support.AbstractContextLoader#getResourceSuffix
-	 * @throws UnsupportedOperationException
 	 */
 	@Override
 	protected String getResourceSuffix() {
 		throw new UnsupportedOperationException(
-			"AnnotationConfigWebContextLoader does not support the getResourceSuffix() method");
+				"AnnotationConfigWebContextLoader does not support the getResourceSuffix() method");
 	}
 
-	// --- AbstractGenericWebContextLoader -------------------------------------
+
+	// AbstractGenericWebContextLoader
 
 	/**
 	 * Register classes in the supplied {@linkplain GenericWebApplicationContext context}
 	 * from the classes in the supplied {@link WebMergedContextConfiguration}.
-	 *
 	 * <p>Each class must represent an <em>annotated class</em>. An
 	 * {@link AnnotatedBeanDefinitionReader} is used to register the appropriate
 	 * bean definitions.
-	 *
 	 * @param context the context in which the annotated classes should be registered
 	 * @param webMergedConfig the merged configuration from which the classes should be retrieved
-	 *
 	 * @see AbstractGenericWebContextLoader#loadBeanDefinitions
 	 */
 	@Override
-	protected void loadBeanDefinitions(GenericWebApplicationContext context,
-			WebMergedContextConfiguration webMergedConfig) {
+	protected void loadBeanDefinitions(
+			GenericWebApplicationContext context, WebMergedContextConfiguration webMergedConfig) {
+
 		Class<?>[] annotatedClasses = webMergedConfig.getClasses();
 		if (logger.isDebugEnabled()) {
 			logger.debug("Registering annotated classes: " + ObjectUtils.nullSafeToString(annotatedClasses));
@@ -181,10 +173,10 @@ public class AnnotationConfigWebContextLoader extends AbstractGenericWebContextL
 	@Override
 	protected void validateMergedContextConfiguration(WebMergedContextConfiguration webMergedConfig) {
 		if (webMergedConfig.hasLocations()) {
-			String msg = String.format(
-				"Test class [%s] has been configured with @ContextConfiguration's 'locations' (or 'value') attribute %s, "
-						+ "but %s does not support resource locations.", webMergedConfig.getTestClass().getName(),
-				ObjectUtils.nullSafeToString(webMergedConfig.getLocations()), getClass().getSimpleName());
+			String msg = String.format("Test class [%s] has been configured with @ContextConfiguration's 'locations' " +
+							"(or 'value') attribute %s, but %s does not support resource locations.",
+					webMergedConfig.getTestClass().getName(),
+					ObjectUtils.nullSafeToString(webMergedConfig.getLocations()), getClass().getSimpleName());
 			logger.error(msg);
 			throw new IllegalStateException(msg);
 		}

spring-test/src/main/java/org/springframework/test/context/web/GenericGroovyXmlWebContextLoader.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2015 the original author or authors.
+ * Copyright 2002-2018 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.
@@ -38,7 +38,6 @@ public class GenericGroovyXmlWebContextLoader extends GenericXmlWebContextLoader
 	 * Load bean definitions into the supplied {@link GenericWebApplicationContext context}
 	 * from the locations in the supplied {@code WebMergedContextConfiguration} using a
 	 * {@link GroovyBeanDefinitionReader}.
-	 *
 	 * @param context the context into which the bean definitions should be loaded
 	 * @param webMergedConfig the merged context configuration
 	 * @see AbstractGenericWebContextLoader#loadBeanDefinitions
@@ -63,12 +62,12 @@ public class GenericGroovyXmlWebContextLoader extends GenericXmlWebContextLoader
 	 * resource types for detection of defaults. Consequently, this method
 	 * is not supported.
 	 * @see #getResourceSuffixes()
-	 * @throws UnsupportedOperationException
+	 * @throws UnsupportedOperationException in this implementation
 	 */
 	@Override
 	protected String getResourceSuffix() {
 		throw new UnsupportedOperationException(
-			"GenericGroovyXmlWebContextLoader does not support the getResourceSuffix() method");
+				"GenericGroovyXmlWebContextLoader does not support the getResourceSuffix() method");
 	}
 
 }

spring-test/src/main/java/org/springframework/test/context/web/socket/MockServerContainer.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2016 the original author or authors.
+ * Copyright 2002-2018 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.
@@ -45,7 +45,7 @@ class MockServerContainer implements ServerContainer {
 	private int defaultMaxTextMessageBufferSize;
 
 
-	// --- WebSocketContainer --------------------------------------------------
+	// WebSocketContainer
 
 	@Override
 	public long getDefaultAsyncSendTimeout() {
@@ -119,7 +119,7 @@ class MockServerContainer implements ServerContainer {
 	}
 
 
-	// --- ServerContainer -----------------------------------------------------
+	// ServerContainer
 
 	@Override
 	public void addEndpoint(Class<?> endpointClass) throws DeploymentException {

spring-test/src/main/java/org/springframework/test/util/XpathExpectationsHelper.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2015 the original author or authors.
+ * Copyright 2002-2018 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.
@@ -62,7 +62,7 @@ public class XpathExpectationsHelper {
 	 * @param namespaces XML namespaces referenced in the XPath expression, or {@code null}
 	 * @param args arguments to parameterize the XPath expression with using the
 	 * formatting specifiers defined in {@link String#format(String, Object...)}
-	 * @throws XPathExpressionException
+	 * @throws XPathExpressionException if expression compilation failed
 	 */
 	public XpathExpectationsHelper(String expression, Map<String, String> namespaces, Object... args)
 			throws XPathExpressionException {
@@ -77,7 +77,7 @@ public class XpathExpectationsHelper {
 			throws XPathExpressionException {
 
 		SimpleNamespaceContext namespaceContext = new SimpleNamespaceContext();
-		namespaceContext.setBindings((namespaces != null) ? namespaces : Collections.<String, String> emptyMap());
+		namespaceContext.setBindings(namespaces != null ? namespaces : Collections.<String, String> emptyMap());
 		XPath xpath = XPathFactory.newInstance().newXPath();
 		xpath.setNamespaceContext(namespaceContext);
 		return xpath.compile(expression);
@@ -119,7 +119,7 @@ public class XpathExpectationsHelper {
 
 	/**
 	 * Apply the XPath expression to given document.
-	 * @throws XPathExpressionException
+	 * @throws XPathExpressionException if expression evaluation failed
 	 */
 	@SuppressWarnings("unchecked")
 	protected <T> T evaluateXpath(Document document, QName evaluationType, Class<T> expectedClass)

spring-test/src/main/java/org/springframework/test/web/client/match/XpathRequestMatchers.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2016 the original author or authors.
+ * Copyright 2002-2018 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.
@@ -51,7 +51,7 @@ public class XpathRequestMatchers {
 	 * @param namespaces XML namespaces referenced in the XPath expression, or {@code null}
 	 * @param args arguments to parameterize the XPath expression with using the
 	 * formatting specifiers defined in {@link String#format(String, Object...)}
-	 * @throws XPathExpressionException
+	 * @throws XPathExpressionException if expression compilation failed
 	 */
 	protected XpathRequestMatchers(String expression, Map<String, String> namespaces, Object ... args)
 			throws XPathExpressionException {

spring-tx/src/main/java/org/springframework/transaction/support/AbstractTransactionStatus.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2014 the original author or authors.
+ * Copyright 2002-2018 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.
@@ -179,7 +179,7 @@ public abstract class AbstractTransactionStatus implements TransactionStatus {
 	 * This implementation delegates to a SavepointManager for the
 	 * underlying transaction, if possible.
 	 * @see #getSavepointManager()
-	 * @see org.springframework.transaction.SavepointManager
+	 * @see SavepointManager#createSavepoint()
 	 */
 	@Override
 	public Object createSavepoint() throws TransactionException {
@@ -189,9 +189,8 @@ public abstract class AbstractTransactionStatus implements TransactionStatus {
 	/**
 	 * This implementation delegates to a SavepointManager for the
 	 * underlying transaction, if possible.
-	 * @throws org.springframework.transaction.NestedTransactionNotSupportedException
 	 * @see #getSavepointManager()
-	 * @see org.springframework.transaction.SavepointManager
+	 * @see SavepointManager#rollbackToSavepoint(Object)
 	 */
 	@Override
 	public void rollbackToSavepoint(Object savepoint) throws TransactionException {
@@ -202,7 +201,7 @@ public abstract class AbstractTransactionStatus implements TransactionStatus {
 	 * This implementation delegates to a SavepointManager for the
 	 * underlying transaction, if possible.
 	 * @see #getSavepointManager()
-	 * @see org.springframework.transaction.SavepointManager
+	 * @see SavepointManager#releaseSavepoint(Object)
 	 */
 	@Override
 	public void releaseSavepoint(Object savepoint) throws TransactionException {

spring-web/src/main/java/org/springframework/http/CacheControl.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2016 the original author or authors.
+ * Copyright 2002-2018 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.
@@ -82,7 +82,8 @@ public class CacheControl {
 
 	/**
 	 * Return an empty directive.
-	 * <p>This is well suited for using other optional directives without "max-age", "no-cache" or "no-store".
+	 * <p>This is well suited for using other optional directives without "max-age",
+	 * "no-cache" or "no-store".
 	 * @return {@code this}, to facilitate method chaining
 	 */
 	public static CacheControl empty() {
@@ -91,11 +92,13 @@ public class CacheControl {
 
 	/**
 	 * Add a "max-age=" directive.
-	 * <p>This directive is well suited for publicly caching resources, knowing that they won't change within
-	 * the configured amount of time. Additional directives can be also used, in case resources shouldn't be
-	 * cached ({@link #cachePrivate()}) or transformed ({@link #noTransform()}) by shared caches.
-	 * <p>In order to prevent caches to reuse the cached response even when it has become stale
-	 * (i.e. the "max-age" delay is passed), the "must-revalidate" directive should be set ({@link #mustRevalidate()}
+	 * <p>This directive is well suited for publicly caching resources, knowing that
+	 * they won't change within the configured amount of time. Additional directives
+	 * can be also used, in case resources shouldn't be cached ({@link #cachePrivate()})
+	 * or transformed ({@link #noTransform()}) by shared caches.
+	 * <p>In order to prevent caches to reuse the cached response even when it has
+	 * become stale (i.e. the "max-age" delay is passed), the "must-revalidate"
+	 * directive should be set ({@link #mustRevalidate()}
 	 * @param maxAge the maximum time the response should be cached
 	 * @param unit the time unit of the {@code maxAge} argument
 	 * @return {@code this}, to facilitate method chaining
@@ -109,12 +112,13 @@ public class CacheControl {
 
 	/**
 	 * Add a "no-cache" directive.
-	 * <p>This directive is well suited for telling caches that the response can be reused only if the client
-	 * revalidates it with the server. This directive won't disable cache altogether and may result with
-	 * clients sending conditional requests (with "ETag", "If-Modified-Since" headers) and the server responding
-	 * with "304 - Not Modified" status.
-	 * <p>In order to disable caching and minimize requests/responses exchanges, the {@link #noStore()} directive
-	 * should be used instead of {@link #noCache()}.
+	 * <p>This directive is well suited for telling caches that the response
+	 * can be reused only if the client revalidates it with the server.
+	 * This directive won't disable cache altogether and may result with clients
+	 * sending conditional requests (with "ETag", "If-Modified-Since" headers)
+	 * and the server responding with "304 - Not Modified" status.
+	 * <p>In order to disable caching and minimize requests/responses exchanges,
+	 * the {@link #noStore()} directive should be used instead of {@code #noCache()}.
 	 * @return {@code this}, to facilitate method chaining
 	 * @see <a href="https://tools.ietf.org/html/rfc7234#section-5.2.2.2">rfc7234 section 5.2.2.2</a>
 	 */
@@ -126,7 +130,8 @@ public class CacheControl {
 
 	/**
 	 * Add a "no-store" directive.
-	 * <p>This directive is well suited for preventing caches (browsers and proxies) to cache the content of responses.
+	 * <p>This directive is well suited for preventing caches (browsers and proxies)
+	 * to cache the content of responses.
 	 * @return {@code this}, to facilitate method chaining
 	 * @see <a href="https://tools.ietf.org/html/rfc7234#section-5.2.2.3">rfc7234 section 5.2.2.3</a>
 	 */
@@ -139,8 +144,9 @@ public class CacheControl {
 
 	/**
 	 * Add a "must-revalidate" directive.
-	 * <p>This directive indicates that once it has become stale, a cache MUST NOT use the response
-	 * to satisfy subsequent requests without successful validation on the origin server.
+	 * <p>This directive indicates that once it has become stale, a cache MUST NOT
+	 * use the response to satisfy subsequent requests without successful validation
+	 * on the origin server.
 	 * @return {@code this}, to facilitate method chaining
 	 * @see <a href="https://tools.ietf.org/html/rfc7234#section-5.2.2.1">rfc7234 section 5.2.2.1</a>
 	 */
@@ -151,8 +157,9 @@ public class CacheControl {
 
 	/**
 	 * Add a "no-transform" directive.
-	 * <p>This directive indicates that intermediaries (caches and others) should not transform the response content.
-	 * This can be useful to force caches and CDNs not to automatically gzip or optimize the response content.
+	 * <p>This directive indicates that intermediaries (caches and others) should
+	 * not transform the response content. This can be useful to force caches and
+	 * CDNs not to automatically gzip or optimize the response content.
 	 * @return {@code this}, to facilitate method chaining
 	 * @see <a href="https://tools.ietf.org/html/rfc7234#section-5.2.2.4">rfc7234 section 5.2.2.4</a>
 	 */
@@ -163,8 +170,9 @@ public class CacheControl {
 
 	/**
 	 * Add a "public" directive.
-	 * <p>This directive indicates that any cache MAY store the response, even if the response
-	 * would normally be non-cacheable or cacheable only within a private cache.
+	 * <p>This directive indicates that any cache MAY store the response,
+	 * even if the response would normally be non-cacheable or cacheable
+	 * only within a private cache.
 	 * @return {@code this}, to facilitate method chaining
 	 * @see <a href="https://tools.ietf.org/html/rfc7234#section-5.2.2.5">rfc7234 section 5.2.2.5</a>
 	 */
@@ -175,8 +183,8 @@ public class CacheControl {
 
 	/**
 	 * Add a "private" directive.
-	 * <p>This directive indicates that the response message is intended for a single user
-	 * and MUST NOT be stored by a shared cache.
+	 * <p>This directive indicates that the response message is intended
+	 * for a single user and MUST NOT be stored by a shared cache.
 	 * @return {@code this}, to facilitate method chaining
 	 * @see <a href="https://tools.ietf.org/html/rfc7234#section-5.2.2.6">rfc7234 section 5.2.2.6</a>
 	 */
@@ -199,8 +207,8 @@ public class CacheControl {
 
 	/**
 	 * Add an "s-maxage" directive.
-	 * <p>This directive indicates that, in shared caches, the maximum age specified by this directive
-	 * overrides the maximum age specified by other directives.
+	 * <p>This directive indicates that, in shared caches, the maximum age specified
+	 * by this directive overrides the maximum age specified by other directives.
 	 * @param sMaxAge the maximum time the response should be cached
 	 * @param unit the time unit of the {@code sMaxAge} argument
 	 * @return {@code this}, to facilitate method chaining
@@ -213,10 +221,11 @@ public class CacheControl {
 
 	/**
 	 * Add a "stale-while-revalidate" directive.
-	 * <p>This directive indicates that caches MAY serve the response in
-	 * which it appears after it becomes stale, up to the indicated number of seconds.
+	 * <p>This directive indicates that caches MAY serve the response in which it
+	 * appears after it becomes stale, up to the indicated number of seconds.
 	 * If a cached response is served stale due to the presence of this extension,
-	 * the cache SHOULD attempt to revalidate it while still serving stale responses (i.e., without blocking).
+	 * the cache SHOULD attempt to revalidate it while still serving stale responses
+	 * (i.e. without blocking).
 	 * @param staleWhileRevalidate the maximum time the response should be used while being revalidated
 	 * @param unit the time unit of the {@code staleWhileRevalidate} argument
 	 * @return {@code this}, to facilitate method chaining
@@ -229,8 +238,8 @@ public class CacheControl {
 
 	/**
 	 * Add a "stale-if-error" directive.
-	 * <p>This directive indicates that when an error is encountered, a cached stale response MAY be used to satisfy
-	 * the request, regardless of other freshness information.
+	 * <p>This directive indicates that when an error is encountered, a cached stale response
+	 * MAY be used to satisfy the request, regardless of other freshness information.
 	 * @param staleIfError the maximum time the response should be used when errors are encountered
 	 * @param unit the time unit of the {@code staleIfError} argument
 	 * @return {@code this}, to facilitate method chaining

spring-web/src/main/java/org/springframework/remoting/jaxws/LocalJaxWsServiceFactory.java

@@ -67,7 +67,6 @@ public class LocalJaxWsServiceFactory {
 
 	/**
 	 * Set the WSDL document URL as a {@link Resource}.
-	 * @throws IOException
 	 * @since 3.2
 	 */
 	public void setWsdlDocumentResource(Resource wsdlDocumentResource) throws IOException {

spring-webmvc/src/main/java/org/springframework/web/servlet/mvc/method/annotation/MatrixVariableMapMethodArgumentResolver.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2016 the original author or authors.
+ * Copyright 2002-2018 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.
@@ -36,10 +36,13 @@ import org.springframework.web.method.support.ModelAndViewContainer;
 import org.springframework.web.servlet.HandlerMapping;
 
 /**
- * Resolves method arguments of type Map annotated with
- * {@link MatrixVariable @MatrixVariable} where the annotation does not
- * specify a name. If a name is specified then the argument will by resolved by the
- * {@link MatrixVariableMethodArgumentResolver} instead.
+ * Resolves arguments of type {@link Map} annotated with {@link MatrixVariable @MatrixVariable}
+ * where the annotation does not specify a name. In other words the purpose of this resolver
+ * is to provide access to multiple matrix variables, either all or associted with a specific
+ * path variable.
+ *
+ * <p>When a name is specified, an argument of type Map is considered to be a single attribute
+ * with a Map value, and is resolved by {@link MatrixVariableMethodArgumentResolver} instead.
  *
  * @author Rossen Stoyanchev
  * @since 3.2

spring-webmvc/src/main/java/org/springframework/web/servlet/tags/form/LabelTag.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2016 the original author or authors.
+ * Copyright 2002-2018 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.
@@ -93,7 +93,7 @@ public class LabelTag extends AbstractHtmlElementTag {
 	}
 
 	/**
-	 * Overrides {@link #getName()} to always return {@code null},
+	 * Overrides {@code #getName()} to always return {@code null},
 	 * because the '{@code name}' attribute is not supported by the
 	 * '{@code label}' tag.
 	 * @return the value for the HTML '{@code name}' attribute