Fix javadoc warnings

Before this change there were numerous javadoc warnings being reported
while building Spring framework API.

This commit resolves most of the javadoc warnings, reducing the total
number from 265 to 103.

Issue: SPR-9113

spring-webmvc/src/main/java/org/springframework/web/servlet/FrameworkServlet.java

@@ -330,7 +330,7 @@ public abstract class FrameworkServlet extends HttpServletBean {
 	 * Specify the set of fully-qualified {@link ApplicationContextInitializer} class
 	 * names, per the optional "contextInitializerClasses" servlet init-param.
 	 * @see #configureAndRefreshWebApplicationContext(ConfigurableWebApplicationContext)
-	 * @see #applyInitializers(ConfigurableWebApplicationContext)
+	 * @see #applyInitializers(ConfigurableApplicationContext)
 	 */
 	public void setContextInitializerClasses(String contextInitializerClasses) {
 		this.contextInitializerClasses = contextInitializerClasses;
@@ -340,7 +340,7 @@ public abstract class FrameworkServlet extends HttpServletBean {
 	 * Specify which {@link ApplicationContextInitializer} instances should be used
 	 * to initialize the application context used by this {@code FrameworkServlet}.
 	 * @see #configureAndRefreshWebApplicationContext(ConfigurableWebApplicationContext)
-	 * @see #applyInitializers(ConfigurableWebApplicationContext)
+	 * @see #applyInitializers(ConfigurableApplicationContext)
 	 */
 	public void setContextInitializers(ApplicationContextInitializer<ConfigurableApplicationContext>... contextInitializers) {
 		for (ApplicationContextInitializer<ConfigurableApplicationContext> initializer : contextInitializers) {
@@ -691,12 +691,12 @@ public abstract class FrameworkServlet extends HttpServletBean {
 	 * <p>The default implementation is empty. <code>refresh()</code> will
 	 * be called automatically after this method returns.
 	 * <p>Note that this method is designed to allow subclasses to modify the application
-	 * context, while {@link #initializeWebApplicationContext} is designed to allow
+	 * context, while {@link #initWebApplicationContext} is designed to allow
 	 * end-users to modify the context through the use of
 	 * {@link ApplicationContextInitializer}s.
 	 * @param wac the configured WebApplicationContext (not refreshed yet)
 	 * @see #createWebApplicationContext
-	 * @see #initializeWebApplicationContext
+	 * @see #initWebApplicationContext
 	 * @see ConfigurableWebApplicationContext#refresh()
 	 */
 	protected void postProcessWebApplicationContext(ConfigurableWebApplicationContext wac) {

spring-webmvc/src/main/java/org/springframework/web/servlet/handler/DispatcherServletWebRequest.java

@@ -47,7 +47,7 @@ public class DispatcherServletWebRequest extends ServletWebRequest {
 	/**
 	 * Create a new DispatcherServletWebRequest instance for the given request and response.
 	 * @param request current HTTP request
-	 * @param request current HTTP response
+	 * @param response current HTTP response
 	 */
 	public DispatcherServletWebRequest(HttpServletRequest request, HttpServletResponse response) {
 		super(request, response);

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

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2011 the original author or authors.
+ * Copyright 2002-2012 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.
@@ -443,7 +443,7 @@ public class AnnotationMethodHandlerAdapter extends WebContentGenerator
 	/**
 	 * This method always returns -1 since an annotated controller can have many methods,
 	 * each requiring separate lastModified calculations. Instead, an
-	 * @{@link RequestMapping}-annotated method can calculate the lastModified value, call
+	 * {@link RequestMapping}-annotated method can calculate the lastModified value, call
 	 * {@link org.springframework.web.context.request.WebRequest#checkNotModified(long)}
 	 * to check it, and return {@code null} if that returns {@code true}.
 	 * @see org.springframework.web.context.request.WebRequest#checkNotModified(long)
@@ -483,7 +483,7 @@ public class AnnotationMethodHandlerAdapter extends WebContentGenerator
 	 * @return the ServletRequestDataBinder instance to use
 	 * @throws Exception in case of invalid state or arguments
 	 * @see ServletRequestDataBinder#bind(javax.servlet.ServletRequest)
-	 * @see ServletRequestDataBinder#convertIfNecessary(Object, Class, org.springframework.core.MethodParameter) 
+	 * @see ServletRequestDataBinder#convertIfNecessary(Object, Class, org.springframework.core.MethodParameter)
 	 */
 	protected ServletRequestDataBinder createBinder(HttpServletRequest request, Object target, String objectName) throws Exception {
 		return new ServletRequestDataBinder(target, objectName);

spring-webmvc/src/main/java/org/springframework/web/servlet/mvc/condition/RequestCondition.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2011 the original author or authors.
+ * Copyright 2002-2012 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.
@@ -22,15 +22,15 @@ import org.springframework.web.bind.annotation.RequestMapping;
 
 /**
  * The contract for request conditions.
- * 
- * <p>Request conditions can be combined via {@link #combine(Object)}, matched to 
- * a request via {@link #getMatchingCondition(HttpServletRequest)}, and compared 
- * to each other via {@link #compareTo(Object, HttpServletRequest)} to determine 
+ *
+ * <p>Request conditions can be combined via {@link #combine(Object)}, matched to
+ * a request via {@link #getMatchingCondition(HttpServletRequest)}, and compared
+ * to each other via {@link #compareTo(Object, HttpServletRequest)} to determine
  * which matches a request more closely.
- * 
- * @param <T> The type of objects that this RequestCondition can be combined 
+ *
+ * @param <T> The type of objects that this RequestCondition can be combined
  * with compared to.
- * 
+ *
  * @author Rossen Stoyanchev
  * @author Arjen Poutsma
  * @since 3.1
@@ -38,32 +38,32 @@ import org.springframework.web.bind.annotation.RequestMapping;
 public interface RequestCondition<T> {
 
 	/**
-	 * Defines the rules for combining this condition (i.e. the current instance) 
-	 * with another condition. For example combining type- and method-level 
-	 * {@link RequestMapping} conditions. 
-	 * 
+	 * Defines the rules for combining this condition (i.e. the current instance)
+	 * with another condition. For example combining type- and method-level
+	 * {@link RequestMapping} conditions.
+	 *
 	 * @param other the condition to combine with.
-	 * @returns a request condition instance that is the result of combining 
+	 * @return a request condition instance that is the result of combining
 	 * 	the two condition instances.
 	 */
 	T combine(T other);
 
 	/**
-	 * Checks if this condition matches the given request and returns a 
-	 * potentially new request condition with content tailored to the 
-	 * current request. For example a condition with URL patterns might 
-	 * return a new condition that contains matching patterns sorted 
+	 * Checks if this condition matches the given request and returns a
+	 * potentially new request condition with content tailored to the
+	 * current request. For example a condition with URL patterns might
+	 * return a new condition that contains matching patterns sorted
 	 * with best matching patterns on top.
-	 * 
-	 * @return a condition instance in case of a match; 
+	 *
+	 * @return a condition instance in case of a match;
 	 * 		or {@code null} if there is no match.
 	 */
 	T getMatchingCondition(HttpServletRequest request);
 
 	/**
-	 * Compares this condition to another condition in the context of 
-	 * a specific request. This method assumes both instances have 
-	 * been obtained via {@link #getMatchingCondition(HttpServletRequest)} 
+	 * Compares this condition to another condition in the context of
+	 * a specific request. This method assumes both instances have
+	 * been obtained via {@link #getMatchingCondition(HttpServletRequest)}
 	 * to ensure they have content relevant to current request only.
 	 */
 	int compareTo(T other, HttpServletRequest request);

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

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2011 the original author or authors.
+ * Copyright 2002-2012 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,10 +54,10 @@ public abstract class RequestMappingInfoHandlerMapping extends AbstractHandlerMe
 	}
 
 	/**
-	 * Check if the given RequestMappingInfo matches the current request and 
-	 * return a (potentially new) instance with conditions that match the 
+	 * Check if the given RequestMappingInfo matches the current request and
+	 * return a (potentially new) instance with conditions that match the
 	 * current request -- for example with a subset of URL patterns.
-	 * @returns an info in case of a match; or {@code null} otherwise. 
+	 * @return an info in case of a match; or {@code null} otherwise.
 	 */
 	@Override
 	protected RequestMappingInfo getMatchingMapping(RequestMappingInfo info, HttpServletRequest request) {
@@ -101,17 +101,17 @@ public abstract class RequestMappingInfoHandlerMapping extends AbstractHandlerMe
 	/**
 	 * Iterate all RequestMappingInfos once again, look if any match by URL at
 	 * least and raise exceptions accordingly.
-	 * 
-	 * @throws HttpRequestMethodNotSupportedException 
+	 *
+	 * @throws HttpRequestMethodNotSupportedException
 	 * 		if there are matches by URL but not by HTTP method
-	 * @throws HttpMediaTypeNotAcceptableException 
+	 * @throws HttpMediaTypeNotAcceptableException
 	 * 		if there are matches by URL but not by consumable media types
-	 * @throws HttpMediaTypeNotAcceptableException 
+	 * @throws HttpMediaTypeNotAcceptableException
 	 * 		if there are matches by URL but not by producible media types
 	 */
 	@Override
-	protected HandlerMethod handleNoMatch(Set<RequestMappingInfo> requestMappingInfos, 
-										  String lookupPath, 
+	protected HandlerMethod handleNoMatch(Set<RequestMappingInfo> requestMappingInfos,
+										  String lookupPath,
 										  HttpServletRequest request) throws ServletException {
 		Set<String> allowedMethods = new HashSet<String>(6);
 		Set<MediaType> consumableMediaTypes = new HashSet<MediaType>();

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

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2011 the original author or authors.
+ * Copyright 2002-2012 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.
@@ -32,8 +32,8 @@ import org.springframework.web.servlet.mvc.method.RequestMappingInfo;
 import org.springframework.web.servlet.mvc.method.RequestMappingInfoHandlerMapping;
 
 /**
- * Creates {@link RequestMappingInfo} instances from type and method-level 
- * {@link RequestMapping @RequestMapping} annotations in 
+ * Creates {@link RequestMappingInfo} instances from type and method-level
+ * {@link RequestMapping @RequestMapping} annotations in
  * {@link Controller @Controller} classes.
  *
  * @author Arjen Poutsma
@@ -49,7 +49,7 @@ public class RequestMappingHandlerMapping extends RequestMappingInfoHandlerMappi
 	/**
 	 * Whether to use suffix pattern match (".*") when matching patterns to
 	 * requests. If enabled a method mapped to "/users" also matches to "/users.*".
-	 * <p>The default value is {@code true}. 
+	 * <p>The default value is {@code true}.
 	 */
 	public void setUseSuffixPatternMatch(boolean useSuffixPatternMatch) {
 		this.useSuffixPatternMatch = useSuffixPatternMatch;
@@ -78,7 +78,7 @@ public class RequestMappingHandlerMapping extends RequestMappingInfoHandlerMappi
 	}
 
 	/**
-	 * {@inheritDoc} 
+	 * {@inheritDoc}
 	 * Expects a handler to have a type-level @{@link Controller} annotation.
 	 */
 	@Override
@@ -89,10 +89,10 @@ public class RequestMappingHandlerMapping extends RequestMappingInfoHandlerMappi
 	/**
 	 * Uses method and type-level @{@link RequestMapping} annotations to create
 	 * the RequestMappingInfo.
-	 * 
+	 *
 	 * @return the created RequestMappingInfo, or {@code null} if the method
 	 * does not have a {@code @RequestMapping} annotation.
-	 * 
+	 *
 	 * @see #getCustomMethodCondition(Method)
 	 * @see #getCustomTypeCondition(Class)
 	 */
@@ -114,9 +114,9 @@ public class RequestMappingHandlerMapping extends RequestMappingInfoHandlerMappi
 
 	/**
 	 * Provide a custom method-level request condition.
-	 * The custom {@link RequestCondition} can be of any type so long as the 
+	 * The custom {@link RequestCondition} can be of any type so long as the
 	 * same condition type is returned from all calls to this method in order
-	 * to ensure custom request conditions can be combined and compared. 
+	 * to ensure custom request conditions can be combined and compared.
 	 * @param method the handler method for which to create the condition
 	 * @return the condition, or {@code null}
 	 */
@@ -126,10 +126,10 @@ public class RequestMappingHandlerMapping extends RequestMappingInfoHandlerMappi
 	
 	/**
 	 * Provide a custom type-level request condition.
-	 * The custom {@link RequestCondition} can be of any type so long as the 
+	 * The custom {@link RequestCondition} can be of any type so long as the
 	 * same condition type is returned from all calls to this method in order
-	 * to ensure custom request conditions can be combined and compared. 
-	 * @param method the handler method for which to create the condition
+	 * to ensure custom request conditions can be combined and compared.
+	 * @param handlerType the handler type for which to create the condition
 	 * @return the condition, or {@code null}
 	 */
 	protected RequestCondition<?> getCustomTypeCondition(Class<?> handlerType) {
@@ -141,13 +141,13 @@ public class RequestMappingHandlerMapping extends RequestMappingInfoHandlerMappi
 	 */
 	private RequestMappingInfo createRequestMappingInfo(RequestMapping annotation, RequestCondition<?> customCondition) {
 		return new RequestMappingInfo(
-				new PatternsRequestCondition(annotation.value(), 
+				new PatternsRequestCondition(annotation.value(),
 						getUrlPathHelper(), getPathMatcher(), this.useSuffixPatternMatch, this.useTrailingSlashMatch),
 				new RequestMethodsRequestCondition(annotation.method()),
 				new ParamsRequestCondition(annotation.params()),
 				new HeadersRequestCondition(annotation.headers()),
 				new ConsumesRequestCondition(annotation.consumes(), annotation.headers()),
-				new ProducesRequestCondition(annotation.produces(), annotation.headers()), 
+				new ProducesRequestCondition(annotation.produces(), annotation.headers()),
 				customCondition);
 	}
 

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

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2011 the original author or authors.
+ * Copyright 2002-2012 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.
@@ -37,8 +37,8 @@ import org.springframework.web.servlet.HandlerMapping;
 
 /**
  * A Servlet-specific {@link org.springframework.web.method.annotation.ModelAttributeMethodProcessor} that applies data
- * binding through a WebDataBinder of type {@link ServletRequestDataBinder}. 
- * 
+ * binding through a WebDataBinder of type {@link ServletRequestDataBinder}.
+ *
  * <p>Also adds a fall-back strategy to instantiate the model attribute from a
  * URI template variable or from a request parameter if the name matches the
  * model attribute name and there is an appropriate type conversion strategy.
@@ -50,7 +50,7 @@ public class ServletModelAttributeMethodProcessor extends ModelAttributeMethodPr
 
 	/**
 	 * @param annotationNotRequired if "true", non-simple method arguments and
-	 * return values are considered model attributes with or without a 
+	 * return values are considered model attributes with or without a
 	 * {@code @ModelAttribute} annotation.
 	 */
 	public ServletModelAttributeMethodProcessor(boolean annotationNotRequired) {
@@ -62,12 +62,12 @@ public class ServletModelAttributeMethodProcessor extends ModelAttributeMethodPr
 	 * request parameter if the name matches to the model attribute name and
 	 * if there is an appropriate type conversion strategy. If none of these
 	 * are true delegate back to the base class.
-	 * @see #createAttributeFromUriValue
+	 * @see #createAttributeFromRequestValue(String, String, MethodParameter, WebDataBinderFactory, NativeWebRequest)
 	 */
 	@Override
-	protected final Object createAttribute(String attributeName, 
-										   MethodParameter parameter, 
-										   WebDataBinderFactory binderFactory, 
+	protected final Object createAttribute(String attributeName,
+										   MethodParameter parameter,
+										   WebDataBinderFactory binderFactory,
 										   NativeWebRequest request) throws Exception {
 
 		String value = getRequestValueForAttribute(attributeName, request);
@@ -83,7 +83,7 @@ public class ServletModelAttributeMethodProcessor extends ModelAttributeMethodPr
 	
 	/**
 	 * Obtain a value from the request that may be used to instantiate the
-	 * model attribute through type conversion from String to the target type. 
+	 * model attribute through type conversion from String to the target type.
 	 * <p>The default implementation looks for the attribute name to match
 	 * a URI variable first and then a request parameter.
 	 * @param attributeName the model attribute name
@@ -105,7 +105,7 @@ public class ServletModelAttributeMethodProcessor extends ModelAttributeMethodPr
 
 	@SuppressWarnings("unchecked")
 	protected final Map<String, String> getUriTemplateVariables(NativeWebRequest request) {
-		Map<String, String> variables = 
+		Map<String, String> variables =
 			(Map<String, String>) request.getAttribute(
 					HandlerMapping.URI_TEMPLATE_VARIABLES_ATTRIBUTE, RequestAttributes.SCOPE_REQUEST);
 		return (variables != null) ? variables : Collections.<String, String>emptyMap();
@@ -114,7 +114,7 @@ public class ServletModelAttributeMethodProcessor extends ModelAttributeMethodPr
 	/**
 	 * Create a model attribute from a String request value (e.g. URI template
 	 * variable, request parameter) using type conversion.
-	 * <p>The default implementation converts only if there a registered 
+	 * <p>The default implementation converts only if there a registered
 	 * {@link Converter} that can perform the conversion.
 	 * @param sourceValue the source value to create the model attribute from
 	 * @param attributeName the name of the attribute, never {@code null}
@@ -125,9 +125,9 @@ public class ServletModelAttributeMethodProcessor extends ModelAttributeMethodPr
 	 * @throws Exception
 	 */
 	protected Object createAttributeFromRequestValue(String sourceValue,
-												 String attributeName, 
-												 MethodParameter parameter, 
-												 WebDataBinderFactory binderFactory, 
+												 String attributeName,
+												 MethodParameter parameter,
+												 WebDataBinderFactory binderFactory,
 												 NativeWebRequest request) throws Exception {
 		DataBinder binder = binderFactory.createBinder(request, null, attributeName);
 		ConversionService conversionService = binder.getConversionService();

spring-webmvc/src/main/java/org/springframework/web/servlet/resource/DefaultServletHttpRequestHandler.java

@@ -30,7 +30,8 @@ import org.springframework.web.context.ServletContextAware;
 /**
  * An {@link HttpRequestHandler} for serving static files using the Servlet container's "default" Servlet.
  *
- * <p>This handler is intended to be used with a "/*" mapping when the {@link DispatcherServlet}
+ * <p>This handler is intended to be used with a "/*" mapping when the
+ * {@link org.springframework.web.servlet.DispatcherServlet DispatcherServlet}
  * is mapped to "/", thus  overriding the Servlet container's default handling of static resources.
  * The mapping to this handler should generally be ordered as the last in the chain so that it will
  * only execute when no other more specific mappings (i.e., to controllers) can be matched.

spring-webmvc/src/main/java/org/springframework/web/servlet/support/RequestContext.java

@@ -50,16 +50,16 @@ 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.
- * 
+ *
  * <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>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).
- * 
+ *
  * @author Juergen Hoeller
  * @since 03.03.2003
  * @see org.springframework.web.servlet.DispatcherServlet
@@ -83,8 +83,8 @@ public class RequestContext {
 	public static final String WEB_APPLICATION_CONTEXT_ATTRIBUTE = RequestContext.class.getName() + ".CONTEXT";
 
 	/**
-	 * The name of the bean to use to look up in an implementation of 
-	 * {@link RequestDataValueProcessor} has been configured. 
+	 * The name of the bean to use to look up in an implementation of
+	 * {@link RequestDataValueProcessor} has been configured.
 	 */
 	private static final String REQUEST_DATA_VALUE_PROCESSOR_BEAN_NAME = "requestDataValueProcessor";
 
@@ -148,7 +148,7 @@ public class RequestContext {
 	 * @param model the model attributes for the current view (can be <code>null</code>, using the request attributes
 	 * for Errors retrieval)
 	 * @see org.springframework.web.servlet.DispatcherServlet
-	 * @see #RequestContext(javax.servlet.http.HttpServletRequest, javax.servlet.ServletContext, Map)
+	 * @see #RequestContext(javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse, javax.servlet.ServletContext, Map)
 	 */
 	public RequestContext(HttpServletRequest request, Map<String, Object> model) {
 		initContext(request, null, null, model);
@@ -226,7 +226,7 @@ public class RequestContext {
 		try {
 			this.requestDataValueProcessor = this.webApplicationContext.getBean(
 					REQUEST_DATA_VALUE_PROCESSOR_BEAN_NAME, RequestDataValueProcessor.class);
-		} 
+		}
 		catch (NoSuchBeanDefinitionException ex) {
 			// Ignored
 		}
@@ -366,7 +366,7 @@ public class RequestContext {
 	}
 
 	/**
-	 * Return the RequestDataValueProcessor instance to use obtained from the 
+	 * Return the RequestDataValueProcessor instance to use obtained from the
 	 * WebApplicationContext under the name {@code "requestDataValueProcessor"}.
 	 * Or {@code null} if no matching bean was found.
 	 */
@@ -402,9 +402,9 @@ public class RequestContext {
 	 * Return a context-aware URl for the given relative URL with placeholders (named keys with braces <code>{}</code>).
 	 * For example, send in a relative URL <code>foo/{bar}?spam={spam}</code> and a parameter map
 	 * <code>{bar=baz,spam=nuts}</code> and the result will be <code>[contextpath]/foo/baz?spam=nuts</code>.
-	 * 
+	 *
 	 * @param relativeUrl the relative URL part
-	 * @param a map of parameters to insert as placeholders in the url
+	 * @param params a map of parameters to insert as placeholders in the url
 	 * @return a URL that points back to the server with an absolute path (also URL-encoded accordingly)
 	 */
 	public String getContextUrl(String relativeUrl, Map<String, ?> params) {
@@ -418,9 +418,9 @@ public class RequestContext {
 	}
 
 	/**
-	 * Return the path to URL mappings within the current servlet including the 
+	 * Return the path to URL mappings within the current servlet including the
 	 * context path and the servlet path of the original request. This is useful
-	 * for building links to other resources within the application where a 
+	 * for building links to other resources within the application where a
 	 * servlet mapping of the style {@code "/main/*"} is used.
 	 * <p>Delegates to the UrlPathHelper for decoding the context path.
 	 * @see javax.servlet.http.HttpServletRequest#getContextPath