Javadoc format and related polishing

(cherry picked from commit 9d0e62e)

Author: jhoeller

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 @@
  * 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 String resolveStringValue(String strVal) {
 	/**
 	 * 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 void setValues(PreparedStatement ps) throws SQLException {
 	 * @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 void setValues(PreparedStatement ps) throws SQLException {
 	 * @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 @@ static FlushMode getFlushMode(Session session) {
 	 * {@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,15 +109,15 @@
 	/**
 	 * 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 "";
 
 	/**
 	 * 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 @@ protected void customizeContext(ConfigurableApplicationContext context, MergedCo
 	}
 
 
-	// --- 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 @@
  * 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 @@ private static ApplicationContext delegateLoading(SmartContextLoader loader, Mer
 
 	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 @@ private boolean supports(SmartContextLoader loader, MergedContextConfiguration m
 	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 @@ else if (configAttributes.hasClasses()) {
 			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 @@ else if (configAttributes.hasClasses()) {
 			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 ApplicationContext loadContext(MergedContextConfiguration mergedConfig) t
 
 		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 ApplicationContext loadContext(MergedContextConfiguration mergedConfig) t
 
 		// 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 final String[] processLocations(Class<?> clazz, String... locations) {
 	 */
 	@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.");
 	}
 
 }