Improve Javadocs

Author: Jay Bryant

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

@@ -1,5 +1,5 @@
 /*
- * Copyright 2014-2018 the original author or authors.
+ * Copyright 2014-2022 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.
@@ -16,9 +16,9 @@
 package org.springframework.batch.core.configuration;
 
 /**
- * Represents an error has occurred in the configuration of base batch infrastructure
- * (creation of a {@link org.springframework.batch.core.repository.JobRepository} for
- * example.
+ * Represents that an error has occurred in the configuration of the base batch
+ * infrastructure (the creation of a
+ * {@link org.springframework.batch.core.repository.JobRepository}, for example).
  *
  * @author Michael Minella
  * @author Mahmoud Ben Hassine
@@ -29,6 +29,7 @@ public class BatchConfigurationException extends RuntimeException {
 	private static final long serialVersionUID = 1L;
 
 	/**
+	 * Create an exception with the given {@Link Throwable}.
 	 * @param t an exception to be wrapped
 	 */
 	public BatchConfigurationException(Throwable t) {

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

@@ -1,5 +1,5 @@
 /*
- * Copyright 2006-2007 the original author or authors.
+ * Copyright 2006-2022 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,6 +36,7 @@ public DuplicateJobException(String msg) {
 	}
 
 	/**
+	 * Create an exception with the given message and the given exception.
 	 * @param msg error message.
 	 * @param e instance of {@link Throwable} that is the cause of the exception.
 	 */

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

@@ -32,7 +32,7 @@ public interface JobFactory {
 	Job createJob();
 
 	/**
-	 * @return The {@link String} containing the {@link Job} name.
+	 * @return The {@link String} that contains the {@link Job} name.
 	 */
 	String getJobName();
 

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

@@ -1,5 +1,5 @@
 /*
- * Copyright 2006-2007 the original author or authors.
+ * Copyright 2006-2022 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,7 @@ public interface JobRegistry extends ListableJobLocator {
 
 	/**
 	 * Unregisters a previously registered {@link Job}. If it was not previously
-	 * registered there is no error.
+	 * registered, there is no error.
 	 * @param jobName the {@link Job} to unregister.
 	 */
 	void unregister(String jobName);

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

@@ -1,5 +1,5 @@
 /*
- * Copyright 2012 the original author or authors.
+ * Copyright 2012-2022 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,7 +22,7 @@
 import java.util.Collection;
 
 /**
- * Registry keeping track of all the {@link Step} defined in a
+ * Registry keeping track of all the {@link Step} instances defined in a
  * {@link org.springframework.batch.core.Job}.
  *
  * @author Sebastien Gerard
@@ -31,9 +31,9 @@
 public interface StepRegistry {
 
 	/**
-	 * Registers all the step of the given job. If the job is already registered, the
-	 * method {@link #unregisterStepsFromJob(String)} is called before registering the
-	 * given steps.
+	 * 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
 	 * @param steps the job steps
 	 * @throws DuplicateJobException if a job with the same job name has already been
@@ -42,8 +42,8 @@ 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
-	 * happens.
+	 * Unregisters all the steps instances of the given job. If the job is not registered,
+	 * nothing happens.
 	 * @param jobName the given job name
 	 */
 	void unregisterStepsFromJob(String jobName);

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

@@ -37,9 +37,9 @@
 import org.springframework.transaction.PlatformTransactionManager;
 
 /**
- * Base {@code Configuration} class providing common structure for enabling and using
- * Spring Batch. Customization is available by implementing the {@link BatchConfigurer}
- * interface.
+ * Base {@code Configuration} class that provides a common structure for enabling and
+ * using Spring Batch. Customization is available by implementing the
+ * {@link BatchConfigurer} interface.
  *
  * @author Dave Syer
  * @author Michael Minella
@@ -65,7 +65,7 @@ public abstract class AbstractBatchConfiguration implements InitializingBean {
 	/**
 	 * Establish the {@link JobBuilderFactory} for the batch execution.
 	 * @return The instance of the {@link JobBuilderFactory}.
-	 * @throws Exception The {@link Exception} thrown if error occurs.
+	 * @throws Exception The {@link Exception} thrown if an error occurs.
 	 */
 	@Bean
 	public JobBuilderFactory jobBuilders() throws Exception {
@@ -75,7 +75,7 @@ public JobBuilderFactory jobBuilders() throws Exception {
 	/**
 	 * Establish the {@link StepBuilderFactory} for the batch execution.
 	 * @return The instance of the {@link StepBuilderFactory}.
-	 * @throws Exception The {@link Exception} thrown if error occurs.
+	 * @throws Exception The {@link Exception} thrown if an error occurs.
 	 */
 	@Bean
 	public StepBuilderFactory stepBuilders() throws Exception {
@@ -85,31 +85,31 @@ public StepBuilderFactory stepBuilders() throws Exception {
 	/**
 	 * Establish the {@link JobRepository} for the batch execution.
 	 * @return The instance of the {@link JobRepository}.
-	 * @throws Exception The {@link Exception} thrown if error occurs.
+	 * @throws Exception The {@link Exception} thrown if an error occurs.
 	 */
 	@Bean
 	public abstract JobRepository jobRepository() throws Exception;
 
 	/**
 	 * Establish the {@link JobLauncher} for the batch execution.
 	 * @return The instance of the {@link JobLauncher}.
-	 * @throws Exception The {@link Exception} thrown if error occurs.
+	 * @throws Exception The {@link Exception} thrown if an error occurs.
 	 */
 	@Bean
 	public abstract JobLauncher jobLauncher() throws Exception;
 
 	/**
 	 * Establish the {@link JobExplorer} for the batch execution.
 	 * @return The instance of the {@link JobExplorer}.
-	 * @throws Exception The {@link Exception} thrown if error occurs.
+	 * @throws Exception The {@link Exception} thrown if an error occurs.
 	 */
 	@Bean
 	public abstract JobExplorer jobExplorer() throws Exception;
 
 	/**
 	 * Establish the {@link JobRegistry} for the batch execution.
 	 * @return The instance of the {@link JobRegistry}.
-	 * @throws Exception The {@link Exception} thrown if error occurs.
+	 * @throws Exception The {@link Exception} thrown if an error occurs.
 	 */
 	@Bean
 	public JobRegistry jobRegistry() throws Exception {
@@ -119,7 +119,7 @@ public JobRegistry jobRegistry() throws Exception {
 	/**
 	 * Establish the {@link PlatformTransactionManager} for the batch execution.
 	 * @return The instance of the {@link PlatformTransactionManager}.
-	 * @throws Exception The {@link Exception} thrown if error occurs.
+	 * @throws Exception The {@link Exception} thrown if an error occurs.
 	 */
 	public abstract PlatformTransactionManager transactionManager() throws Exception;
 

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

@@ -1,5 +1,5 @@
 /*
- * Copyright 2012-2013 the original author or authors.
+ * Copyright 2012-2022 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.
@@ -21,7 +21,7 @@
 import org.springframework.util.Assert;
 
 /**
- * Base {@code Configuration} class providing common structure for enabling and using
+ * Base {@code Configuration} class that provides common structure for enabling and using
  * Spring Batch. Customization is available by implementing the {@link BatchConfigurer}
  * interface.
  *
@@ -50,4 +50,4 @@ public String[] selectImports(AnnotationMetadata importingClassMetadata) {
 		return imports;
 	}
 
-}
+}

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

@@ -21,8 +21,8 @@
 import org.springframework.transaction.PlatformTransactionManager;
 
 /**
- * Strategy interface for users to provide as a factory for custom components needed by a
- * Batch system.
+ * Strategy interface that users can provide as a factory for custom components needed by
+ * a Batch system.
  *
  * @author Dave Syer
  *

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

@@ -49,18 +49,18 @@ public class DefaultBatchConfigurer implements BatchConfigurer, InitializingBean
 
 	/**
 	 * Create a new {@link DefaultBatchConfigurer} with the passed datasource. This
-	 * constructor will configure a default {@link JdbcTransactionManager}.
+	 * constructor configures a default {@link JdbcTransactionManager}.
 	 * @param dataSource to use for the job repository and job explorer
 	 */
 	public DefaultBatchConfigurer(DataSource dataSource) {
 		this(dataSource, new JdbcTransactionManager(dataSource));
 	}
 
 	/**
-	 * Create a new {@link DefaultBatchConfigurer} with the passed datasource and
+	 * Create a new {@link DefaultBatchConfigurer} with the given datasource and
 	 * transaction manager.
-	 * @param dataSource to use for the job repository and job explorer
-	 * @param transactionManager to use for the job repository
+	 * @param dataSource The data source to use for the job repository and job explorer.
+	 * @param transactionManager The transaction manager to use for the job repository.
 	 */
 	public DefaultBatchConfigurer(DataSource dataSource, PlatformTransactionManager transactionManager) {
 		Assert.notNull(dataSource, "DataSource must not be null");

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

@@ -63,8 +63,8 @@
  * }
  * </pre>
  *
- * The user should provide a {@link DataSource} as a bean in the context, or else
- * implement {@link BatchConfigurer} in the configuration class itself, e.g.
+ * You should provide a {@link DataSource} as a bean in the context or else implement
+ * {@link BatchConfigurer} in the configuration class itself -- for example:
  *
  * <pre class="code">
  * &#064;Configuration
@@ -86,16 +86,17 @@
  * }
  * </pre>
  *
- * If multiple {@link javax.sql.DataSource}s are defined in the context, the primary
- * autowire candidate will be used, otherwise an exception will be thrown.
+ * If multiple {@link javax.sql.DataSource} instances are defined in the context, the
+ * primary autowire candidate is used. Otherwise, an exception is thrown.
  *
  * Note that only one of your configuration classes needs to have the
  * <code>&#064;EnableBatchProcessing</code> annotation. Once you have an
- * <code>&#064;EnableBatchProcessing</code> class in your configuration you will 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 will also be able to
- * <code>&#064;Autowired</code> some useful stuff into your context:
+ * <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 beans into your
+ * context:
  *
  * <ul>
  * <li>a {@link JobRepository} (bean name "jobRepository" of type
@@ -108,19 +109,19 @@
  * "jobExplorer" of type
  * {@link org.springframework.batch.core.explore.support.SimpleJobExplorer})</li>
  * <li>a {@link JobBuilderFactory} (bean name "jobBuilders") as a convenience to prevent
- * you from having to inject the job repository into every job, as in the examples
- * above</li>
+ * you from having to inject the job repository into every job, as in the earlier
+ * examples</li>
  * <li>a {@link StepBuilderFactory} (bean name "stepBuilders") as a convenience to prevent
  * you from having to inject the job repository and transaction manager into every
  * step</li>
  * </ul>
  *
- * The transaction manager provided by this annotation will be of type
- * {@link org.springframework.jdbc.support.JdbcTransactionManager} configured with the
- * {@link javax.sql.DataSource} provided within the context.
+ * The transaction manager provided by this annotation is of type
+ * {@link org.springframework.jdbc.support.JdbcTransactionManager} and is configured with
+ * the {@link javax.sql.DataSource} provided within the context.
  *
- * In order to use a custom transaction manager, a custom {@link BatchConfigurer} should
- * be provided. For example:
+ * To use a custom transaction manager, you should provide a custom
+ * {@link BatchConfigurer} -- for example:
  *
  * <pre class="code">
  * &#064;Configuration
@@ -142,14 +143,13 @@
  * }
  * </pre>
  *
- * If the configuration is specified as <code>modular=true</code> then the context will
- * also contain an {@link AutomaticJobRegistrar}. The job registrar is useful for
- * modularizing your configuration if there are multiple jobs. It works by creating
- * separate child application contexts containing job configurations and registering those
- * jobs. The jobs can then create steps and other dependent components without needing to
- * worry about bean definition name clashes. Beans of type
- * {@link ApplicationContextFactory} will be registered automatically with the job
- * registrar. Example:
+ * If the configuration is specified as <code>modular=true</code>, the context also
+ * contains an {@link AutomaticJobRegistrar}. The job registrar is useful for modularizing
+ * your configuration if there are multiple jobs. It works by creating separate child
+ * application contexts to contain job configurations and register those jobs. The jobs
+ * can then create steps and other dependent components without needing to worry about
+ * bean definition name clashes. Beans of type {@link ApplicationContextFactory} are
+ * automatically registered with the job registrar. Example:
  *
  * <pre class="code">
  * &#064;Configuration
@@ -171,12 +171,12 @@
  * }
  * </pre>
  *
- * Note that a modular parent context in general should <em>not</em> itself contain
+ * Note that a modular parent context, in general, should <em>not</em> itself contain
  * &#64;Bean definitions for job, especially if a {@link BatchConfigurer} is provided,
- * because cyclic configuration dependencies are otherwise likely to develop.
+ * because cyclic configuration dependencies are likely to develop.
  *
  * <p>
- * For reference, the first example above can be compared to the following Spring XML
+ * For reference, compare the first example shown earlier to the following Spring XML
  * configuration:
  *
  * <pre class="code">
@@ -208,11 +208,11 @@
 
 	/**
 	 * Indicate whether the configuration is going to be modularized into multiple
-	 * application contexts. If true then you should not create any &#64;Bean Job
-	 * definitions in this context, but rather supply them in separate (child) contexts
-	 * through an {@link ApplicationContextFactory}.
+	 * application contexts. If true, you should not create any &#64;Bean Job definitions
+	 * in this context but, rather, supply them in separate (child) contexts through an
+	 * {@link ApplicationContextFactory}.
 	 * @return boolean indicating whether the configuration is going to be modularized
-	 * into multiple application contexts. Defaults to false.
+	 * into multiple application contexts. Defaults to {@code false}.
 	 */
 	boolean modular() default false;
 

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

@@ -20,7 +20,7 @@
 import org.springframework.util.Assert;
 
 /**
- * Convenient factory for a {@link JobBuilder} which sets the {@link JobRepository}
+ * Convenient factory for a {@link JobBuilder} that sets the {@link JobRepository}
  * automatically.
  *
  * @author Dave Syer
@@ -41,8 +41,8 @@ public JobBuilderFactory(JobRepository jobRepository) {
 	}
 
 	/**
-	 * Creates a job builder and initializes its job repository. Note that if the builder
-	 * is used to create a @Bean definition then the name of the job and the bean name
+	 * Creates a job builder and initializes its job repository. Note that, if the builder
+	 * is used to create a @Bean definition, the name of the job and the bean name
 	 * might be different.
 	 * @param name the name of the job
 	 * @return a job builder