Further updates in response to feedback.

Author: Jay Bryant

spring-batch-core/src/main/java/org/springframework/batch/core/configuration/StepRegistry.java

@@ -31,7 +31,7 @@
 public interface StepRegistry {
 
 	/**
-	 * Registers all the step of the given job. If the job is already registered, the
+	 * Registers all the step instances of the given job. If the job is already registered, the
 	 * method {@link #unregisterStepsFromJob(String)} is called before registering the
 	 * given steps.
 	 * @param jobName the give job name
@@ -42,7 +42,7 @@ public interface StepRegistry {
 	void register(String jobName, Collection<Step> steps) throws DuplicateJobException;
 
 	/**
-	 * Unregisters all the steps of the given job. If the job is not registered, nothing
+	 * Unregisters all the steps instances of the given job. If the job is not registered, nothing
 	 * happens.
 	 * @param jobName the given job name
 	 */

spring-batch-core/src/main/java/org/springframework/batch/core/configuration/annotation/EnableBatchProcessing.java

@@ -94,7 +94,7 @@
  * annotation. Once you have an <code>&#064;EnableBatchProcessing</code> class in your configuration, you have an
  * instance of {@link StepScope} and {@link org.springframework.batch.core.scope.JobScope}, so your beans inside steps
  * can have <code>&#064;Scope("step")</code> and <code>&#064;Scope("job")</code> respectively. You can also
- * use <code>&#064;Autowired</code> to insert some useful stuff into your context:
+ * use <code>&#064;Autowired</code> to insert some useful beans into your context:
  *
  * <ul>
  * <li>a {@link JobRepository} (bean name "jobRepository" of type {@link org.springframework.batch.core.repository.support.SimpleJobRepository})</li>

spring-batch-core/src/main/java/org/springframework/batch/core/configuration/support/ApplicationContextJobFactory.java

@@ -33,9 +33,9 @@ public class ApplicationContextJobFactory implements JobFactory {
 
 	/**
 	 * @param jobName the ID of the {@link Job} in the application context to be
-	 * created
+	 * created.
 	 * @param applicationContextFactory a factory for an application context
-	 * that contains a job with the job name provided
+	 * that contains a job with the job name provided.
 	 */
 	public ApplicationContextJobFactory(String jobName, ApplicationContextFactory applicationContextFactory) {
 		@SuppressWarnings("resource")

spring-batch-core/src/main/java/org/springframework/batch/core/configuration/support/AutomaticJobRegistrar.java

@@ -72,7 +72,7 @@ public void setApplicationContext(ApplicationContext applicationContext) {
 	}
 
 	/**
-	 * Add some factories to the set that is used to load contexts and jobs.
+	 * Add a single {@link ApplicationContextFactory} to the set that is used to load contexts and jobs.
 	 *
 	 * @param applicationContextFactory the {@link ApplicationContextFactory} values to use
 	 */
@@ -84,7 +84,7 @@ public void addApplicationContextFactory(ApplicationContextFactory applicationCo
 	}
 
 	/**
-	 * Add some factories to the set that is used to load contexts and jobs.
+	 * Add an array of {@link ApplicationContextFactory} instances to the set that is used to load contexts and jobs.
 	 *
 	 * @param applicationContextFactories the {@link ApplicationContextFactory} values to use
 	 */
@@ -166,7 +166,7 @@ public void start() {
 	/**
 	 * Check whether this component has been started.
 	 *
-	 * @return {@code true} if started successfully and not stopped
+	 * @return {@code true} if started successfully and not stopped.
 	 * @see Lifecycle#isRunning()
 	 */
 	@Override

spring-batch-core/src/main/java/org/springframework/batch/core/configuration/xml/AbstractFlowParser.java

@@ -151,7 +151,7 @@ protected Class<?> getBeanClass(Element element) {
 	}
 
 	/**
-	 * Performs the parsing.
+	 * Performs the parsing for a flow definition.
 	 *
 	 * @param element the top level element containing a flow definition
 	 * @param parserContext the {@link ParserContext}
@@ -284,6 +284,8 @@ public static Collection<BeanDefinition> getNextElements(ParserContext parserCon
 	}
 
 	/**
+	 * Retrieve a list of {@link StateTransition} instances from a {@link ParserContext}.
+	 *
 	 * @param parserContext The parser context for the bean factory
 	 * @param stepId The ID of the current state if it is a step state, null
 	 * otherwise
@@ -333,6 +335,8 @@ else if (hasNextAttribute) {
 	}
 
 	/**
+	 * Verifies that {@code transitionElement} is not in the list of state transition patterns.
+	 *
 	 * @param transitionElement The element to parse
 	 * @param patterns A list of patterns on state transitions for this element
 	 * @param element The {@link Element} representing the source.
@@ -431,7 +435,7 @@ protected static Collection<BeanDefinition> createTransition(FlowExecutionStatus
 	 * Gets the batch status from the end transition name by the element.
 	 *
 	 * @param elementName An end transition element name
-	 * @return the {@code BatchStatus} corresponding to the transition name.
+	 * @return the {@link BatchStatus} corresponding to the transition name.
 	 */
 	protected static FlowExecutionStatus getBatchStatusFromEndTransitionName(String elementName) {
 		elementName = stripNamespace(elementName);

spring-batch-core/src/main/java/org/springframework/batch/core/configuration/xml/ChunkElementParser.java

@@ -267,7 +267,7 @@ else if (refElements.size() == 1) {
 
 	/**
 	 * Handle the adapter method attribute by using an
-	 * {@code AbstractMethodInvokingDelegator}.
+	 * {@link AbstractMethodInvokingDelegator}.
 	 */
 	private void handleAdapterMethodAttribute(String propertyName, String adapterClassName,
 			MutablePropertyValues stepPvs, Element element) {

spring-batch-core/src/main/java/org/springframework/batch/core/configuration/xml/CoreNamespaceUtils.java

@@ -208,10 +208,7 @@ public static boolean isAbstract(Element element) {
 
 	/**
 	 * Check that the schema location declared in the source file being parsed
-	 * matches the Spring Batch version. (The old 2.0 schema is not 100%
-	 * compatible with the new parser, so it is an error to explicitly define
-	 * 2.0. It might be an error to declare spring-batch.xsd as an alias, but
-	 * you are only going to find that out when one of the sub parses breaks.)
+	 * matches the Spring Batch version.
 	 *
 	 * @param element The element that is to be parsed next.
 	 * @return {@code true} if we find a schema declaration that matches.

spring-batch-core/src/main/java/org/springframework/batch/core/configuration/xml/SimpleFlowFactoryBean.java

@@ -158,10 +158,10 @@ private State getProxyState(State state) {
 	 * Provides an extension point to provide alternative {@link StepState}
 	 * implementations within a {@link SimpleFlow}.
 	 *
-	 * @param state The state that is used to create the StepState
-	 * @param oldName The name to be replaced
-	 * @param stateName The name for the new State
-	 * @return a state for the requested data
+	 * @param state The state that is used to create the {@code StepState}.
+	 * @param oldName The name to be replaced.
+	 * @param stateName The name for the new State.
+	 * @return a state for the requested data.
 	 */
 	protected State createNewStepState(State state, String oldName, String stateName) {
 		return new StepState(stateName, ((StepState) state).getStep(oldName));

spring-batch-core/src/main/java/org/springframework/batch/core/configuration/xml/SplitParser.java

@@ -52,7 +52,7 @@ public class SplitParser {
 	 * reference.
 	 *
 	 * @param jobFactoryRef The reference to the {@link JobParserJobFactoryBean}
-	 * from the enclosing tag
+	 * from the enclosing tag.
 	 */
 	public SplitParser(String jobFactoryRef) {
 		this.jobFactoryRef = jobFactoryRef;

spring-batch-core/src/main/java/org/springframework/batch/core/configuration/xml/StepParserStepFactoryBean.java

@@ -901,8 +901,10 @@ public void setKeyGenerator(KeyGenerator keyGenerator) {
 	// =========================================================
 
 	/**
-	 * Public setter for the capacity of the cache in the retry policy. If more items than this fail without being
-	 * skipped or recovered, an exception will be thrown. This guards against inadvertent infinite loops generated
+	 *
+	 * Public setter for the capacity of the cache in the retry policy.
+	 * If there are more items than the specified capacity, the the step fails without being skipped or recovered,
+	 * and an exception is thrown. This guards against inadvertent infinite loops generated
 	 * by item identity problems.<br>
 	 * <br>
 	 * The default value should be high enough for most purposes. To breach the limit in a single-threaded step,