Javadoc format and related polishing

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.
@@ -34,6 +34,7 @@ import org.springframework.lang.Nullable;
  * for detailed instructions.
  *
  * @author Chris Beams
+ * @author Stephane Nicoll
  * @since 3.1
  * @see EnableCaching
  * @see CachingConfigurerSupport
@@ -69,8 +70,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-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.
@@ -185,7 +185,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-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.
@@ -58,7 +58,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-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.
@@ -92,7 +92,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-jdbc/src/main/java/org/springframework/jdbc/core/namedparam/SqlParameterSourceUtils.java

@@ -42,7 +42,7 @@ public abstract class SqlParameterSourceUtils {
 	 * @return an array of {@link SqlParameterSource}
 	 * @see MapSqlParameterSource
 	 * @see BeanPropertySqlParameterSource
-	 * @see NamedParameterJdbcTemplate#batchUpdate(String, SqlParameterSource[]))
+	 * @see NamedParameterJdbcTemplate#batchUpdate(String, SqlParameterSource[])
 	 */
 	@SuppressWarnings("unchecked")
 	public static SqlParameterSource[] createBatch(Object... candidates) {
@@ -58,7 +58,7 @@ public abstract class SqlParameterSourceUtils {
 	 * @since 5.0.2
 	 * @see MapSqlParameterSource
 	 * @see BeanPropertySqlParameterSource
-	 * @see NamedParameterJdbcTemplate#batchUpdate(String, SqlParameterSource[]))
+	 * @see NamedParameterJdbcTemplate#batchUpdate(String, SqlParameterSource[])
 	 */
 	@SuppressWarnings("unchecked")
 	public static SqlParameterSource[] createBatch(Collection<?> candidates) {

spring-orm/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.
@@ -133,7 +133,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.
@@ -54,7 +54,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-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.
@@ -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.
@@ -67,6 +67,7 @@ import org.springframework.util.Assert;
  * not result in an exception.
  *
  * @author Sam Brannen
+ * @author Phillip Webb
  * @since 3.2
  * @see SmartContextLoader
  */
@@ -86,16 +87,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);
 	}
@@ -111,10 +109,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,9 +150,9 @@ public abstract class AbstractDelegatingSmartContextLoader implements SmartConte
 	@Override
 	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));
+		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));
 
 		// If the original locations or classes were not empty, there's no
 		// need to bother with default detection checks; just let the
@@ -188,8 +186,7 @@ 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.",
+					logger.info(String.format("%s detected default configuration classes for context configuration %s.",
 							name(getAnnotationConfigLoader()), configAttributes));
 				}
 			}
@@ -199,12 +196,12 @@ public abstract class AbstractDelegatingSmartContextLoader implements SmartConte
 					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.",
+				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(message);
-				throw new IllegalStateException(message);
+				logger.error(msg);
+				throw new IllegalStateException(msg);
 			}
 		}
 	}
@@ -235,8 +232,8 @@ public abstract class AbstractDelegatingSmartContextLoader implements SmartConte
 		List<SmartContextLoader> candidates = Arrays.asList(getXmlLoader(), getAnnotationConfigLoader());
 
 		Assert.state(!(mergedConfig.hasLocations() && mergedConfig.hasClasses()), () -> String.format(
-				"Neither %s nor %s supports loading an ApplicationContext from %s: "
-						+ "declare either 'locations' or 'classes' but not both.", name(getXmlLoader()),
+				"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) {
@@ -260,30 +257,37 @@ public abstract class AbstractDelegatingSmartContextLoader implements SmartConte
 				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, @Nullable 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.");
 	}
 
 	/**
 	 * {@code AbstractDelegatingSmartContextLoader} does not support the
 	 * {@link ContextLoader#loadContext(String...) } method. Call
 	 * {@link #loadContext(MergedContextConfiguration)} instead.
-	 * @throws UnsupportedOperationException
+	 * @throws UnsupportedOperationException in this implementation
 	 */
 	@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-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.
@@ -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,16 +98,16 @@ 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) {
@@ -123,9 +120,8 @@ 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) {
@@ -138,9 +134,8 @@ 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() {
@@ -148,7 +143,8 @@ public class AnnotationConfigContextLoader extends AbstractGenericContextLoader
 				"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,10 +191,9 @@ 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) {

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,7 +62,7 @@ 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() {

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,16 +95,15 @@ 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 {
-		Assert.isTrue(mergedConfig instanceof WebMergedContextConfiguration, () -> String.format(
-				"Cannot load WebApplicationContext from non-web merged context configuration %s. "
-						+ "Consider annotating your test class with @WebAppConfiguration.", mergedConfig));
+		Assert.isTrue(mergedConfig instanceof WebMergedContextConfiguration,
+				() -> String.format("Cannot load WebApplicationContext from non-web merged context configuration %s. " +
+						"Consider annotating your test class with @WebAppConfiguration.", mergedConfig));
 
 		WebMergedContextConfiguration webMergedConfig = (WebMergedContextConfiguration) mergedConfig;
 
@@ -150,20 +147,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>
@@ -178,24 +170,20 @@ 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);
@@ -203,7 +191,7 @@ public abstract class AbstractGenericWebContextLoader extends AbstractContextLoa
 		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();
@@ -219,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
@@ -232,52 +218,50 @@ 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 {

spring-test/src/main/java/org/springframework/test/context/web/AnnotationConfigWebContextLoader.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.
@@ -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,29 +85,26 @@ 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) {
@@ -122,9 +117,8 @@ 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) {
@@ -137,9 +131,8 @@ 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() {
@@ -147,24 +140,23 @@ public class AnnotationConfigWebContextLoader extends AbstractGenericWebContextL
 				"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,9 +173,9 @@ 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(),
+			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,7 +62,7 @@ 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() {

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-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.
@@ -63,7 +63,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, @Nullable Map<String, String> namespaces, Object... args)
 			throws XPathExpressionException {
@@ -78,7 +78,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.emptyMap());
 		XPath xpath = XPathFactory.newInstance().newXPath();
 		xpath.setNamespaceContext(namespaceContext);
 		return xpath.compile(expression);
@@ -122,7 +122,7 @@ public class XpathExpectationsHelper {
 
 	/**
 	 * Apply the XPath expression to given document.
-	 * @throws XPathExpressionException
+	 * @throws XPathExpressionException if expression evaluation failed
 	 */
 	@SuppressWarnings("unchecked")
 	@Nullable

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.
@@ -18,7 +18,6 @@ package org.springframework.test.web.client.match;
 
 import java.io.IOException;
 import java.util.Map;
-
 import javax.xml.xpath.XPathExpressionException;
 
 import org.hamcrest.Matcher;
@@ -53,7 +52,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, @Nullable 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-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.
@@ -184,7 +184,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 {
@@ -194,9 +194,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 {
@@ -207,7 +206,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.
@@ -83,7 +83,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() {
@@ -92,11 +93,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
@@ -110,12 +113,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>
 	 */
@@ -127,7 +131,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>
 	 */
@@ -140,8 +145,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>
 	 */
@@ -152,8 +158,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>
 	 */
@@ -164,8 +171,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>
 	 */
@@ -176,8 +184,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>
 	 */
@@ -200,8 +208,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
@@ -214,10 +222,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
@@ -230,8 +239,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/http/codec/ClientCodecConfigurer.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.
@@ -48,7 +48,7 @@ public interface ClientCodecConfigurer extends CodecConfigurer {
 
 
 	/**
-	 * Extension of {@link DefaultCodecs} with extra client options.
+	 * Extension of {@link CodecConfigurer.DefaultCodecs} with extra client options.
 	 */
 	interface ClientDefaultCodecs extends DefaultCodecs {
 

spring-web/src/main/java/org/springframework/http/codec/ServerCodecConfigurer.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.
@@ -47,7 +47,7 @@ public interface ServerCodecConfigurer extends CodecConfigurer {
 
 
 	/**
-	 * Extension of {@link DefaultCodecs} with extra server options.
+	 * Extension of {@link CodecConfigurer.DefaultCodecs} with extra server options.
 	 */
 	interface ServerDefaultCodecs extends DefaultCodecs {
 

spring-web/src/main/java/org/springframework/remoting/jaxws/LocalJaxWsServiceFactory.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.
@@ -73,11 +73,10 @@ public class LocalJaxWsServiceFactory {
 
 	/**
 	 * Set the WSDL document URL as a {@link Resource}.
-	 * @throws IOException
 	 * @since 3.2
 	 */
 	public void setWsdlDocumentResource(Resource wsdlDocumentResource) throws IOException {
-		Assert.notNull(wsdlDocumentResource, "WSDL Resource must not be null.");
+		Assert.notNull(wsdlDocumentResource, "WSDL Resource must not be null");
 		this.wsdlDocumentUrl = wsdlDocumentResource.getURL();
 	}
 

spring-webflux/src/main/java/org/springframework/web/reactive/result/method/AbstractHandlerMethodMapping.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.
@@ -292,19 +292,17 @@ public abstract class AbstractHandlerMethodMapping<T> extends AbstractHandlerMap
 	 * If multiple matches are found, the best match is selected.
 	 * @param exchange the current exchange
 	 * @return the best-matching handler method, or {@code null} if no match
-	 * @see #handleMatch(T, HandlerMethod, ServerWebExchange)
-	 * @see #handleNoMatch(Set, ServerWebExchange)
+	 * @see #handleMatch
+	 * @see #handleNoMatch
 	 */
 	@Nullable
-	protected HandlerMethod lookupHandlerMethod(ServerWebExchange exchange)
-			throws Exception {
-
+	protected HandlerMethod lookupHandlerMethod(ServerWebExchange exchange) throws Exception {
 		List<Match> matches = new ArrayList<>();
 		addMatchingMappings(this.mappingRegistry.getMappings().keySet(), matches, exchange);
 
 		if (!matches.isEmpty()) {
 			Comparator<Match> comparator = new MatchComparator(getMappingComparator(exchange));
-			Collections.sort(matches, comparator);
+			matches.sort(comparator);
 			if (logger.isTraceEnabled()) {
 				logger.trace("Found " + matches.size() + " matching mapping(s) for [" +
 						exchange.getRequest().getPath() + "] : " + matches);

spring-webflux/src/main/java/org/springframework/web/reactive/result/method/annotation/MatrixVariableMapMethodArgumentResolver.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.
@@ -13,6 +13,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+
 package org.springframework.web.reactive.result.method.annotation;
 
 import java.util.Collections;
@@ -37,14 +38,13 @@ import org.springframework.web.reactive.result.method.SyncHandlerMethodArgumentR
 import org.springframework.web.server.ServerWebExchange;
 
 /**
- * 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.
+ * 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 an
- * single attribute with a Map value, and is resolved by
- * {@link MatrixVariableMethodArgumentResolver} instead.
+ * <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 5.0.1

spring-webflux/src/main/java/org/springframework/web/reactive/result/view/RedirectView.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.
@@ -142,9 +142,8 @@ public class RedirectView extends AbstractUrlBasedView {
 	/**
 	 * Configure one or more hosts associated with the application.
 	 * All other hosts will be considered external hosts.
-	 * <p>In effect this provides a way turn off encoding via
-	 * {@link ServerHttpResponse#encodeUrl(String)} for URLs that have a
-	 * host and that host is not listed as a known host.
+	 * <p>In effect this provides a way turn off encoding for URLs that
+	 * have a host and that host is not listed as a known host.
 	 * <p>If not set (the default) all redirect URLs are encoded.
 	 * @param hosts one or more application hosts
 	 */

spring-webmvc/src/main/java/org/springframework/web/servlet/mvc/method/annotation/MatrixVariableMapMethodArgumentResolver.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.
@@ -38,14 +38,13 @@ import org.springframework.web.method.support.ModelAndViewContainer;
 import org.springframework.web.servlet.HandlerMapping;
 
 /**
- * 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.
+ * 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 an
- * single attribute with a Map value, and is resolved by
- * {@link MatrixVariableMethodArgumentResolver} instead.
+ * <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.
@@ -233,7 +233,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