From 392f9c8deb2e2526d43d7867576df0c721d4db04 Mon Sep 17 00:00:00 2001
From: Juergen Hoeller <jhoeller@pivotal.io>
Date: Fri, 15 Jul 2016 22:47:05 +0200
Subject: [PATCH] Javadoc fixes and pruning of deprecated references (cherry
 picked from commit 69dd40e)

---
 .../tomcat/TomcatLoadTimeWeaver.java          |  4 +--
 .../jdbc/datasource/ConnectionHandle.java     |  4 +--
 .../MarshallingMessageConverter.java          |  2 +-
 .../handler/HandlerMethodSelector.java        |  2 +-
 .../web/method/HandlerMethodSelector.java     |  2 +-
 .../ModelAttributeMethodProcessor.java        | 34 +++++++++++--------
 .../springframework/web/util/HtmlUtils.java   |  3 +-
 .../servlet/mvc/WebContentInterceptor.java    |  3 +-
 .../annotation/MvcUriComponentsBuilder.java   | 17 ++++------
 .../web/servlet/support/RequestContext.java   | 17 +++++-----
 10 files changed, 44 insertions(+), 44 deletions(-)

diff --git a/spring-context/src/main/java/org/springframework/instrument/classloading/tomcat/TomcatLoadTimeWeaver.java b/spring-context/src/main/java/org/springframework/instrument/classloading/tomcat/TomcatLoadTimeWeaver.java
index 1ef36c9551..6cb876e847 100644
--- a/spring-context/src/main/java/org/springframework/instrument/classloading/tomcat/TomcatLoadTimeWeaver.java
+++ b/spring-context/src/main/java/org/springframework/instrument/classloading/tomcat/TomcatLoadTimeWeaver.java
@@ -25,8 +25,8 @@ import org.springframework.util.Assert;
 import org.springframework.util.ClassUtils;
 
 /**
- * {@link org.springframework.instrument.classloading.LoadTimeWeaver} implementation for Tomcat's
- * new {@link org.apache.tomcat.InstrumentableClassLoader InstrumentableClassLoader}.
+ * {@link org.springframework.instrument.classloading.LoadTimeWeaver} implementation
+ * for Tomcat's new {@code org.apache.tomcat.InstrumentableClassLoader}.
  * Also capable of handling Spring's TomcatInstrumentableClassLoader when encountered.
  *
  * @author Juergen Hoeller
diff --git a/spring-jdbc/src/main/java/org/springframework/jdbc/datasource/ConnectionHandle.java b/spring-jdbc/src/main/java/org/springframework/jdbc/datasource/ConnectionHandle.java
index 2343aef442..7b361385ac 100644
--- a/spring-jdbc/src/main/java/org/springframework/jdbc/datasource/ConnectionHandle.java
+++ b/spring-jdbc/src/main/java/org/springframework/jdbc/datasource/ConnectionHandle.java
@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2014 the original author or authors.
+ * Copyright 2002-2016 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.
@@ -26,7 +26,7 @@ import java.sql.Connection;
  * @since 1.1
  * @see SimpleConnectionHandle
  * @see ConnectionHolder
- * @see org.springframework.orm.jdo.JpaDialect#getJdbcConnection
+ * @see org.springframework.orm.jpa.JpaDialect#getJdbcConnection
  * @see org.springframework.orm.jdo.JdoDialect#getJdbcConnection
  */
 public interface ConnectionHandle {
diff --git a/spring-messaging/src/main/java/org/springframework/messaging/converter/MarshallingMessageConverter.java b/spring-messaging/src/main/java/org/springframework/messaging/converter/MarshallingMessageConverter.java
index 12d9d8d8bb..965af15880 100644
--- a/spring-messaging/src/main/java/org/springframework/messaging/converter/MarshallingMessageConverter.java
+++ b/spring-messaging/src/main/java/org/springframework/messaging/converter/MarshallingMessageConverter.java
@@ -40,7 +40,7 @@ import org.springframework.util.MimeType;
  * {@link Marshaller} and {@link Unmarshaller} abstractions.
  *
  * <p>This converter requires a {@code Marshaller} and {@code Unmarshaller} before it can
- * be used. These can be injected by the {@linkplain MarshallingMessageConverter(Marshaller)
+ * be used. These can be injected by the {@linkplain #MarshallingMessageConverter(Marshaller)
  * constructor} or {@linkplain #setMarshaller(Marshaller) bean properties}.
  *
  * @author Arjen Poutsma
diff --git a/spring-messaging/src/main/java/org/springframework/messaging/handler/HandlerMethodSelector.java b/spring-messaging/src/main/java/org/springframework/messaging/handler/HandlerMethodSelector.java
index 69bd0c1aca..3d438200c7 100644
--- a/spring-messaging/src/main/java/org/springframework/messaging/handler/HandlerMethodSelector.java
+++ b/spring-messaging/src/main/java/org/springframework/messaging/handler/HandlerMethodSelector.java
@@ -39,7 +39,7 @@ public abstract class HandlerMethodSelector {
 	 * @param handlerType the handler type to search handler methods on
 	 * @param handlerMethodFilter a {@link MethodFilter} to help recognize handler methods of interest
 	 * @return the selected methods, or an empty set
-	 * @see MethodIntrospector#selectMethods(Class, MethodFilter)
+	 * @see MethodIntrospector#selectMethods
 	 */
 	public static Set<Method> selectMethods(Class<?> handlerType, MethodFilter handlerMethodFilter) {
 		return MethodIntrospector.selectMethods(handlerType, handlerMethodFilter);
diff --git a/spring-web/src/main/java/org/springframework/web/method/HandlerMethodSelector.java b/spring-web/src/main/java/org/springframework/web/method/HandlerMethodSelector.java
index 82acd2c3bd..4fc0545b15 100644
--- a/spring-web/src/main/java/org/springframework/web/method/HandlerMethodSelector.java
+++ b/spring-web/src/main/java/org/springframework/web/method/HandlerMethodSelector.java
@@ -39,7 +39,7 @@ public abstract class HandlerMethodSelector {
 	 * @param handlerType the handler type to search handler methods on
 	 * @param handlerMethodFilter a {@link MethodFilter} to help recognize handler methods of interest
 	 * @return the selected methods, or an empty set
-	 * @see MethodIntrospector#selectMethods(Class, MethodFilter)
+	 * @see MethodIntrospector#selectMethods
 	 */
 	public static Set<Method> selectMethods(Class<?> handlerType, MethodFilter handlerMethodFilter) {
 		return MethodIntrospector.selectMethods(handlerType, handlerMethodFilter);
diff --git a/spring-web/src/main/java/org/springframework/web/method/annotation/ModelAttributeMethodProcessor.java b/spring-web/src/main/java/org/springframework/web/method/annotation/ModelAttributeMethodProcessor.java
index 72e43cd1b6..000debe454 100644
--- a/spring-web/src/main/java/org/springframework/web/method/annotation/ModelAttributeMethodProcessor.java
+++ b/spring-web/src/main/java/org/springframework/web/method/annotation/ModelAttributeMethodProcessor.java
@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2015 the original author or authors.
+ * Copyright 2002-2016 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,23 +38,24 @@ import org.springframework.web.method.support.HandlerMethodReturnValueHandler;
 import org.springframework.web.method.support.ModelAndViewContainer;
 
 /**
- * Resolves method arguments annotated with {@code @ModelAttribute} and handles
- * return values from methods annotated with {@code @ModelAttribute}.
+ * Resolve {@code @ModelAttribute} annotated method arguments and handle
+ * return values from {@code @ModelAttribute} annotated methods.
  *
- * <p>Model attributes are obtained from the model or if not found possibly
- * created with a default constructor if it is available. Once created, the
- * attributed is populated with request data via data binding and also
- * validation may be applied if the argument is annotated with
- * {@code @javax.validation.Valid}.
+ * <p>Model attributes are obtained from the model or created with a default
+ * constructor (and then added to the model). Once created the attribute is
+ * populated via data binding to Servlet request parameters. Validation may be
+ * applied if the argument is annotated with {@code @javax.validation.Valid}.
+ * or Spring's own {@code @org.springframework.validation.annotation.Validated}.
  *
- * <p>When this handler is created with {@code annotationNotRequired=true},
+ * <p>When this handler is created with {@code annotationNotRequired=true}
  * any non-simple type argument and return value is regarded as a model
  * attribute with or without the presence of an {@code @ModelAttribute}.
  *
  * @author Rossen Stoyanchev
  * @since 3.1
  */
-public class ModelAttributeMethodProcessor implements HandlerMethodArgumentResolver, HandlerMethodReturnValueHandler {
+public class ModelAttributeMethodProcessor
+		implements HandlerMethodArgumentResolver, HandlerMethodReturnValueHandler {
 
 	protected final Log logger = LogFactory.getLog(getClass());
 
@@ -62,6 +63,7 @@ public class ModelAttributeMethodProcessor implements HandlerMethodArgumentResol
 
 
 	/**
+	 * Class constructor.
 	 * @param annotationNotRequired if "true", non-simple method arguments and
 	 * return values are considered model attributes with or without a
 	 * {@code @ModelAttribute} annotation.
@@ -72,8 +74,9 @@ public class ModelAttributeMethodProcessor implements HandlerMethodArgumentResol
 
 
 	/**
-	 * Returns {@code true} if the parameter is annotated with {@link ModelAttribute}
-	 * or in default resolution mode, and also if it is not a simple type.
+	 * Returns {@code true} if the parameter is annotated with
+	 * {@link ModelAttribute} or, if in default resolution mode, for any
+	 * method parameter that is not a simple type.
 	 */
 	@Override
 	public boolean supportsParameter(MethodParameter parameter) {
@@ -102,8 +105,8 @@ public class ModelAttributeMethodProcessor implements HandlerMethodArgumentResol
 			NativeWebRequest webRequest, WebDataBinderFactory binderFactory) throws Exception {
 
 		String name = ModelFactory.getNameForParameter(parameter);
-		Object attribute = (mavContainer.containsAttribute(name) ?
-				mavContainer.getModel().get(name) : createAttribute(name, parameter, binderFactory, webRequest));
+		Object attribute = (mavContainer.containsAttribute(name) ? mavContainer.getModel().get(name) :
+				createAttribute(name, parameter, binderFactory, webRequest));
 
 		WebDataBinder binder = binderFactory.createBinder(webRequest, attribute, name);
 		if (binder.getTarget() != null) {
@@ -182,7 +185,8 @@ public class ModelAttributeMethodProcessor implements HandlerMethodArgumentResol
 
 	/**
 	 * Return {@code true} if there is a method-level {@code @ModelAttribute}
-	 * or if it is a non-simple type when {@code annotationNotRequired=true}.
+	 * or, in default resolution mode, for any return value type that is not
+	 * a simple type.
 	 */
 	@Override
 	public boolean supportsReturnType(MethodParameter returnType) {
diff --git a/spring-web/src/main/java/org/springframework/web/util/HtmlUtils.java b/spring-web/src/main/java/org/springframework/web/util/HtmlUtils.java
index cb43aa9e04..6210945626 100644
--- a/spring-web/src/main/java/org/springframework/web/util/HtmlUtils.java
+++ b/spring-web/src/main/java/org/springframework/web/util/HtmlUtils.java
@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2015 the original author or authors.
+ * Copyright 2002-2016 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,7 +36,6 @@ import org.springframework.util.Assert;
  * @author Martin Kersten
  * @author Craig Andrews
  * @since 01.03.2003
- * @see org.apache.commons.lang.StringEscapeUtils
  */
 public abstract class HtmlUtils {
 
diff --git a/spring-webmvc/src/main/java/org/springframework/web/servlet/mvc/WebContentInterceptor.java b/spring-webmvc/src/main/java/org/springframework/web/servlet/mvc/WebContentInterceptor.java
index 038667f4b6..5e5810e5ea 100644
--- a/spring-webmvc/src/main/java/org/springframework/web/servlet/mvc/WebContentInterceptor.java
+++ b/spring-webmvc/src/main/java/org/springframework/web/servlet/mvc/WebContentInterceptor.java
@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2015 the original author or authors.
+ * Copyright 2002-2016 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.
@@ -102,7 +102,6 @@ public class WebContentInterceptor extends WebContentGenerator implements Handle
 	 * <p>Only relevant for the "cacheMappings" setting.
 	 * @see #setCacheMappings
 	 * @see org.springframework.web.servlet.handler.AbstractUrlHandlerMapping#setUrlPathHelper
-	 * @see org.springframework.web.servlet.mvc.multiaction.AbstractUrlMethodNameResolver#setUrlPathHelper
 	 */
 	public void setUrlPathHelper(UrlPathHelper urlPathHelper) {
 		Assert.notNull(urlPathHelper, "UrlPathHelper must not be null");
diff --git a/spring-webmvc/src/main/java/org/springframework/web/servlet/mvc/method/annotation/MvcUriComponentsBuilder.java b/spring-webmvc/src/main/java/org/springframework/web/servlet/mvc/method/annotation/MvcUriComponentsBuilder.java
index 25018ff9e6..040746474d 100644
--- a/spring-webmvc/src/main/java/org/springframework/web/servlet/mvc/method/annotation/MvcUriComponentsBuilder.java
+++ b/spring-webmvc/src/main/java/org/springframework/web/servlet/mvc/method/annotation/MvcUriComponentsBuilder.java
@@ -38,8 +38,8 @@ import org.springframework.cglib.proxy.Enhancer;
 import org.springframework.cglib.proxy.Factory;
 import org.springframework.cglib.proxy.MethodProxy;
 import org.springframework.core.DefaultParameterNameDiscoverer;
-import org.springframework.core.MethodParameter;
 import org.springframework.core.MethodIntrospector;
+import org.springframework.core.MethodParameter;
 import org.springframework.core.ParameterNameDiscoverer;
 import org.springframework.core.annotation.AnnotatedElementUtils;
 import org.springframework.core.annotation.SynthesizingMethodParameter;
@@ -118,7 +118,7 @@ public class MvcUriComponentsBuilder {
 	 * @see #fromMethodName(Class, String, Object...)
 	 * @see #fromMethodCall(Object)
 	 * @see #fromMappingName(String)
-	 * @see #fromMethod(java.lang.reflect.Method, Object...)
+	 * @see #fromMethod(Class, Method, Object...)
 	 */
 	protected MvcUriComponentsBuilder(UriComponentsBuilder baseUrl) {
 		Assert.notNull(baseUrl, "'baseUrl' is required");
@@ -168,7 +168,7 @@ public class MvcUriComponentsBuilder {
 	/**
 	 * Create a {@link UriComponentsBuilder} from the mapping of a controller
 	 * method and an array of method argument values. This method delegates
-	 * to {@link #fromMethod(java.lang.reflect.Method, Object...)}.
+	 * to {@link #fromMethod(Class, Method, Object...)}.
 	 * @param controllerType the controller
 	 * @param methodName the method name
 	 * @param args the argument values
@@ -207,7 +207,7 @@ public class MvcUriComponentsBuilder {
 	/**
 	 * Create a {@link UriComponentsBuilder} by invoking a "mock" controller method.
 	 * The controller method and the supplied argument values are then used to
-	 * delegate to {@link #fromMethod(java.lang.reflect.Method, Object...)}.
+	 * delegate to {@link #fromMethod(Class, Method, Object...)}.
 	 * <p>For example, given this controller:
 	 * <pre class="code">
 	 * &#064;RequestMapping("/people/{id}/addresses")
@@ -361,7 +361,7 @@ public class MvcUriComponentsBuilder {
 	}
 
 	/**
-	 * An alternative to {@link #fromMethod(java.lang.reflect.Method, Object...)}
+	 * An alternative to {@link #fromMethod(Class, Method, Object...)}
 	 * that accepts a {@code UriComponentsBuilder} representing the base URL.
 	 * This is useful when using MvcUriComponentsBuilder outside the context of
 	 * processing a request or to apply a custom baseUrl not matching the
@@ -557,8 +557,7 @@ public class MvcUriComponentsBuilder {
 	 * on the controller is invoked, the supplied argument values are remembered
 	 * and the result can then be used to create a {@code UriComponentsBuilder}
 	 * via {@link #fromMethodCall(Object)}.
-	 * <p>
-	 * Note that this is a shorthand version of {@link #controller(Class)} intended
+	 * <p>Note that this is a shorthand version of {@link #controller(Class)} intended
 	 * for inline use (with a static import), for example:
 	 * <pre class="code">
 	 * MvcUriComponentsBuilder.fromMethodCall(on(FooController.class).getFoo(1)).build();
@@ -574,8 +573,7 @@ public class MvcUriComponentsBuilder {
 	 * on the controller is invoked, the supplied argument values are remembered
 	 * and the result can then be used to create {@code UriComponentsBuilder} via
 	 * {@link #fromMethodCall(Object)}.
-	 * <p>
-	 * This is a longer version of {@link #on(Class)}. It is needed with controller
+	 * <p>This is a longer version of {@link #on(Class)}. It is needed with controller
 	 * methods returning void as well for repeated invocations.
 	 * <pre class="code">
 	 * FooController fooController = controller(FooController.class);
@@ -778,7 +776,6 @@ public class MvcUriComponentsBuilder {
 		}
 
 		/**
-		 * @see #MethodArgumentBuilder(Class, Method)
 		 * @deprecated as of 4.2, this is deprecated in favor of alternative constructors
 		 * that accept a controllerType argument
 		 */
diff --git a/spring-webmvc/src/main/java/org/springframework/web/servlet/support/RequestContext.java b/spring-webmvc/src/main/java/org/springframework/web/servlet/support/RequestContext.java
index 9fae867961..df008b774b 100644
--- a/spring-webmvc/src/main/java/org/springframework/web/servlet/support/RequestContext.java
+++ b/spring-webmvc/src/main/java/org/springframework/web/servlet/support/RequestContext.java
@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2015 the original author or authors.
+ * Copyright 2002-2016 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,17 +53,18 @@ import org.springframework.web.util.UrlPathHelper;
 import org.springframework.web.util.WebUtils;
 
 /**
- * Context holder for request-specific state, like current web application context, current locale, current theme,
- * and potential binding errors. Provides easy access to localized messages and Errors instances.
+ * Context holder for request-specific state, like current web application context, current locale,
+ * current theme, and potential binding errors. Provides easy access to localized messages and
+ * Errors instances.
  *
- * <p>Suitable for exposition to views, and usage within JSP's "useBean" tag, JSP scriptlets, JSTL EL, Velocity
- * templates, etc. Necessary for views that do not have access to the servlet request, like Velocity templates.
+ * <p>Suitable for exposition to views, and usage within JSP's "useBean" tag, JSP scriptlets, JSTL EL,
+ * etc. Necessary for views that do not have access to the servlet request, like FreeMarker templates.
  *
  * <p>Can be instantiated manually, or automatically exposed to views as model attribute via AbstractView's
  * "requestContextAttribute" property.
  *
- * <p>Will also work outside of DispatcherServlet requests, accessing the root WebApplicationContext and using
- * an appropriate fallback for the locale (the HttpServletRequest's primary locale).
+ * <p>Will also work outside of DispatcherServlet requests, accessing the root WebApplicationContext
+ * and using an appropriate fallback for the locale (the HttpServletRequest's primary locale).
  *
  * @author Juergen Hoeller
  * @author Rossen Stoyanchev
@@ -467,7 +468,7 @@ public class RequestContext {
 	/**
 	 * (De)activate default HTML escaping for messages and errors, for the scope of this RequestContext.
 	 * <p>The default is the application-wide setting (the "defaultHtmlEscape" context-param in web.xml).
-	 * @see org.springframework.web.util.WebUtils#isDefaultHtmlEscape
+	 * @see org.springframework.web.util.WebUtils#getDefaultHtmlEscape
 	 */
 	public void setDefaultHtmlEscape(boolean defaultHtmlEscape) {
 		this.defaultHtmlEscape = defaultHtmlEscape;