Polish Javadoc

Author: sbrannen

spring-context/src/main/java/org/springframework/cache/interceptor/BasicOperation.java

@@ -27,7 +27,7 @@
 public interface BasicOperation {
 
 	/**
-	 * Return the cache name(s) associated to the operation.
+	 * Return the cache name(s) associated with the operation.
 	 */
 	Set<String> getCacheNames();
 

spring-context/src/main/java/org/springframework/cache/interceptor/CacheOperationInvocationContext.java

@@ -19,33 +19,33 @@
 import java.lang.reflect.Method;
 
 /**
- * Represent the context of the invocation of a cache operation.
+ * Representation of the context of the invocation of a cache operation.
  *
- * <p>The cache operation is static and independent of a particular invocation,
- * this gathers the operation and a particular invocation.
+ * <p>The cache operation is static and independent of a particular invocation;
+ * this interface gathers the operation and a particular invocation.
  *
  * @author Stephane Nicoll
  * @since 4.1
  */
 public interface CacheOperationInvocationContext<O extends BasicOperation> {
 
 	/**
-	 * Return the cache operation
+	 * Return the cache operation.
 	 */
 	O getOperation();
 
 	/**
-	 * Return the target instance on which the method was invoked
+	 * Return the target instance on which the method was invoked.
 	 */
 	Object getTarget();
 
 	/**
-	 * Return the method
+	 * Return the method which was invoked.
 	 */
 	Method getMethod();
 
 	/**
-	 * Return the argument used to invoke the method
+	 * Return the argument list used to invoke the method.
 	 */
 	Object[] getArgs();
 

spring-expression/src/main/java/org/springframework/expression/spel/SpelCompilerMode.java

@@ -19,28 +19,28 @@
 /**
  * Captures the possible configuration settings for a compiler that can be
  * used when evaluating expressions.
- * 
+ *
  * @author Andy Clement
  * @since 4.1
  */
 public enum SpelCompilerMode {
 
 	/**
-	 * The compiler is switched off, this is the default. 
+	 * The compiler is switched off; this is the default.
 	 */
 	OFF,
 
-	/** 
-	 * In immediate mode, expressions are compiled as soon as possible (usually after 1 interpreted run). 
+	/**
+	 * In immediate mode, expressions are compiled as soon as possible (usually after 1 interpreted run).
 	 * If a compiled expression fails it will throw an exception to the caller.
 	 */
 	IMMEDIATE,
 
-	/** 
-	 * In mixed mode, expression evaluate silently switches between interpreted and compiled over time.
+	/**
+	 * In mixed mode, expression evaluation silently switches between interpreted and compiled over time.
 	 * After a number of runs the expression gets compiled. If it later fails (possibly due to inferred
 	 * type information changing) then that will be caught internally and the system switches back to
-	 * interpreted mode. It may subsequently compile it again later. 
+	 * interpreted mode. It may subsequently compile it again later.
 	 */
 	MIXED
 

spring-expression/src/main/java/org/springframework/expression/spel/SpelParserConfiguration.java

@@ -51,14 +51,14 @@ public class SpelParserConfiguration {
 
 
 	/**
-	 * Create a new {@link SpelParserConfiguration} instance with default settings.
+	 * Create a new {@code SpelParserConfiguration} instance with default settings.
 	 */
 	public SpelParserConfiguration() {
 		this(null, null, false, false, Integer.MAX_VALUE);
 	}
 
 	/**
-	 * Create a new {@link SpelParserConfiguration} instance.
+	 * Create a new {@code SpelParserConfiguration} instance.
 	 * @param compilerMode the compiler mode for the parser
 	 * @param compilerClassLoader the ClassLoader to use as the basis for expression compilation
 	 */
@@ -67,7 +67,7 @@ public SpelParserConfiguration(SpelCompilerMode compilerMode, ClassLoader compil
 	}
 
 	/**
-	 * Create a new {@link SpelParserConfiguration} instance.
+	 * Create a new {@code SpelParserConfiguration} instance.
 	 * @param autoGrowNullReferences if null references should automatically grow
 	 * @param autoGrowCollections if collections should automatically grow
 	 * @see #SpelParserConfiguration(boolean, boolean, int)
@@ -77,7 +77,7 @@ public SpelParserConfiguration(boolean autoGrowNullReferences, boolean autoGrowC
 	}
 
 	/**
-	 * Create a new {@link SpelParserConfiguration} instance.
+	 * Create a new {@code SpelParserConfiguration} instance.
 	 * @param autoGrowNullReferences if null references should automatically grow
 	 * @param autoGrowCollections if collections should automatically grow
 	 * @param maximumAutoGrowSize the maximum size that the collection can auto grow
@@ -87,7 +87,7 @@ public SpelParserConfiguration(boolean autoGrowNullReferences, boolean autoGrowC
 	}
 
 	/**
-	 * Create a new {@link SpelParserConfiguration} instance.
+	 * Create a new {@code SpelParserConfiguration} instance.
 	 * @param compilerMode the compiler mode that parsers using this configuration object should use
 	 * @param compilerClassLoader the ClassLoader to use as the basis for expression compilation
 	 * @param autoGrowNullReferences if null references should automatically grow

spring-jms/src/main/java/org/springframework/jms/annotation/JmsListenerConfigurer.java

@@ -19,10 +19,10 @@
 import org.springframework.jms.config.JmsListenerEndpointRegistrar;
 
 /**
- * Optional interface to be implemented by Spring managed bean willing
+ * Optional interface to be implemented by a Spring managed bean willing
  * to customize how JMS listener endpoints are configured. Typically
- * used to defined the default {@link org.springframework.jms.config.JmsListenerContainerFactory
- * JmsListenerContainerFactory} to use or for registering jms endpoints
+ * used to define the default {@link org.springframework.jms.config.JmsListenerContainerFactory
+ * JmsListenerContainerFactory} to use or for registering JMS endpoints
  * in a <em>programmatic</em> fashion as opposed to the <em>declarative</em>
  * approach of using the @{@link JmsListener} annotation.
  *

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

@@ -122,7 +122,6 @@
  *  <li>and the {@link HandlerMapping} for serving resources
  * </ul>
  * Note that those beans can be configured by using the {@code path-matching} MVC namespace element.
-
  *
  * <p>Both the {@link RequestMappingHandlerAdapter} and the
  * {@link ExceptionHandlerExceptionResolver} are configured with instances of

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

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2012 the original author or authors.
+ * Copyright 2002-2014 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,39 +33,38 @@
  * HTTP requests throughout the lifecycle of an application. To be able to
  * configure a Controller easily, Controller implementations are encouraged
  * to be (and usually are) JavaBeans.
- * </p>
  *
- * <p><b><a name="workflow">Workflow</a></b></p>
+ * <h3><a name="workflow">Workflow</a></h3>
  *
- * <p>
- * After a <cde>DispatcherServlet</code> has received a request and has
- * done its work to resolve locales, themes and suchlike, it then tries
+ * <p>After a {@code DispatcherServlet} has received a request and has
+ * done its work to resolve locales, themes, and suchlike, it then tries
  * to resolve a Controller, using a
  * {@link org.springframework.web.servlet.HandlerMapping HandlerMapping}.
  * When a Controller has been found to handle the request, the
  * {@link #handleRequest(HttpServletRequest, HttpServletResponse) handleRequest}
  * method of the located Controller will be invoked; the located Controller
- * is then responsible for handling the actual request and - if applicable -
- * returning an appropriate
+ * is then responsible for handling the actual request and &mdash; if applicable
+ * &mdash; returning an appropriate
  * {@link org.springframework.web.servlet.ModelAndView ModelAndView}.
- * So actually, this method is the main entrypoint for the
+ * So actually, this method is the main entry point for the
  * {@link org.springframework.web.servlet.DispatcherServlet DispatcherServlet}
- * which delegates requests to controllers.</p>
+ * which delegates requests to controllers.
  *
- * <p>So basically any <i>direct</i> implementation of the Controller interface
+ * <p>So basically any <i>direct</i> implementation of the {@code Controller} interface
  * just handles HttpServletRequests and should return a ModelAndView, to be further
  * interpreted by the DispatcherServlet. Any additional functionality such as
- * optional validation, form handling, etc should be obtained through extending
- * one of the abstract controller classes mentioned above.</p>
+ * optional validation, form handling, etc. should be obtained through extending
+ * {@link org.springframework.web.servlet.mvc.AbstractController AbstractController}
+ * or one of its subclasses.
  *
- * <p><b>Notes on design and testing</b></p>
+ * <h3>Notes on design and testing</h3>
  *
  * <p>The Controller interface is explicitly designed to operate on HttpServletRequest
  * and HttpServletResponse objects, just like an HttpServlet. It does not aim to
  * decouple itself from the Servlet API, in contrast to, for example, WebWork, JSF or Tapestry.
  * Instead, the full power of the Servlet API is available, allowing Controllers to be
  * general-purpose: a Controller is able to not only handle web user interface
- * requests but also to process remoting protocols or to generate reports on demand.</p>
+ * requests but also to process remoting protocols or to generate reports on demand.
  *
  * <p>Controllers can easily be tested by passing in mock objects for the
  * HttpServletRequest and HttpServletResponse objects as parameters to the
@@ -74,11 +73,11 @@
  * that are suitable for testing any kind of web components, but are particularly
  * suitable for testing Spring web controllers. In contrast to a Struts Action,
  * there is no need to mock the ActionServlet or any other infrastructure;
- * HttpServletRequest and HttpServletResponse are sufficient.</p>
+ * mocking HttpServletRequest and HttpServletResponse is sufficient.
  *
  * <p>If Controllers need to be aware of specific environment references, they can
  * choose to implement specific awareness interfaces, just like any other bean in a
- * Spring (web) application context can do, for example:</p>
+ * Spring (web) application context can do, for example:
  * <ul>
  * <li>{@code org.springframework.context.ApplicationContextAware}</li>
  * <li>{@code org.springframework.context.ResourceLoaderAware}</li>
@@ -90,7 +89,7 @@
  * In general, it is recommended to keep the dependencies as minimal as possible:
  * for example, if all you need is resource loading, implement ResourceLoaderAware only.
  * Alternatively, derive from the WebApplicationObjectSupport base class, which gives
- * you all those references through convenient accessors - but requires an
+ * you all those references through convenient accessors but requires an
  * ApplicationContext reference on initialization.
  *
  * <p>Controllers can optionally implement the {@link LastModified} interface.
@@ -111,9 +110,9 @@ public interface Controller {
 
 	/**
 	 * Process the request and return a ModelAndView object which the DispatcherServlet
-	 * will render. A {@code null} return value is not an error: It indicates that
-	 * this object completed request processing itself, thus there is no ModelAndView
-	 * to render.
+	 * will render. A {@code null} return value is not an error: it indicates that
+	 * this object completed request processing itself and that there is therefore no
+	 * ModelAndView to render.
 	 * @param request current HTTP request
 	 * @param response current HTTP response
 	 * @return a ModelAndView to render, or {@code null} if handled directly

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

@@ -49,8 +49,8 @@
  * All files that have the ".manifest" file extension, or the extension given in the constructor, will be transformed
  * by this class.
  *
- * This hash is computed using the content of the appcache manifest and the content of the linked resources; so
- * changing a resource linked in the manifest or the manifest itself should invalidate browser cache.
+ * <p>This hash is computed using the content of the appcache manifest and the content of the linked resources; so
+ * changing a resource linked in the manifest or the manifest itself should invalidate the browser cache.
  *
  * @author Brian Clozel
  * @see <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/offline.html#offline">HTML5 offline
@@ -71,7 +71,7 @@ public class AppCacheManifestTransformer extends ResourceTransformerSupport {
 
 
 	/**
-	 * Create an AppCacheResourceTransformer that transforms files with extension ".manifest"
+	 * Create an AppCacheResourceTransformer that transforms files with extension ".manifest".
 	 */
 	public AppCacheManifestTransformer() {
 		this("manifest");
@@ -145,8 +145,8 @@ public Resource transform(HttpServletRequest request, Resource resource, Resourc
 	private static interface SectionTransformer {
 
 		/**
-		 * Transforms a line in a section of the manifest
-		 * <p>The actual transformation depends on the chose transformation strategy
+		 * Transforms a line in a section of the manifest.
+		 * <p>The actual transformation depends on the chosen transformation strategy
 		 * for the current manifest section (CACHE, NETWORK, FALLBACK, etc).
 		 */
 		String transform(String line, HashBuilder builder, Resource resource,

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

@@ -29,11 +29,11 @@
 
 /**
  * Resolves request paths containing a version string that can be used as part
- * of an HTTP caching strategy in which a resource is cached with a far future
- * date (e.g. 1 year) and cached until the version, and therefore the URL, is
- * changed.
+ * of an HTTP caching strategy in which a resource is cached with a date in the
+ * distant future (e.g. 1 year) and cached until the version, and therefore the
+ * URL, is changed.
  *
- * <p>Different versioning strategies exist and this resolver must be configured
+ * <p>Different versioning strategies exist, and this resolver must be configured
  * with one or more such strategies along with path mappings to indicate which
  * strategy applies to which resources.
  *
@@ -42,9 +42,10 @@
  * cannot be combined with JavaScript module loaders. For such cases the
  * {@code FixedVersionStrategy} is a better choice.
  *
- * <p>Note that using this resolver to serve CSS files means the
+ * <p>Note that using this resolver to serve CSS files means that the
  * {@link CssLinkResourceTransformer} should also be used in order to modify
- * links within CSS files to also contain versions.
+ * links within CSS files to also contain the appropriate versions generated
+ * by this resolver.
  *
  * @author Brian Clozel
  * @author Rossen Stoyanchev
@@ -95,11 +96,12 @@ public VersionResourceResolver addContentVersionStrategy(String... pathPatterns)
 
 	/**
 	 * Insert a fixed, prefix-based version in resource URLs that match the given
-	 * path patterns, e.g. {@code "{version}/js/main.js"}. This is useful (vs
+	 * path patterns, for example: <code>"{version}/js/main.js"</code>. This is useful (vs.
 	 * content-based versions) when using JavaScript module loaders.
-	 * <p>The version may be a random number, the current date, fetched from a
-	 * git commit sha, a property file, environment variable, and set with SpEL
-	 * expressions in the configuration (e.g. see {@code @Value} in Java config).
+	 * <p>The version may be a random number, the current date, or a value
+	 * fetched from a git commit sha, a property file, or environment variable
+	 * and set with SpEL expressions in the configuration (e.g. see {@code @Value}
+	 * in Java config).
 	 * @param version a version string
 	 * @param pathPatterns one or more resource URL path patterns
 	 * @return the current instance for chained method invocation