Editing pass for Javadocs

Update javadocs of org.springframework.batch.core
but not further down that tree.

Issue spring-projects#4090

Author: Jay Bryant

spring-batch-core/src/main/java/org/springframework/batch/core/BatchStatus.java

@@ -17,8 +17,8 @@
 package org.springframework.batch.core;
 
 /**
- * Enumeration representing the status of an Execution.
- * 
+ * Enumeration representing the status of an execution.
+ *
  * @author Lucas Ward
  * @author Dave Syer
  * @author Michael Minella
@@ -28,14 +28,14 @@ public enum BatchStatus {
 
 	/**
 	 * The order of the status values is significant because it can be used to
-	 * aggregate a set of status values - the result should be the maximum
-	 * value. Since COMPLETED is first in the order, only if all elements of an
-	 * execution are COMPLETED will the aggregate status be COMPLETED. A running
-	 * execution is expected to move from STARTING to STARTED to COMPLETED
+	 * aggregate a set of status values. The result should be the maximum
+	 * value. Since {@code COMPLETED} is first in the order, only if all elements of an
+	 * execution are {@code COMPLETED} can the aggregate status be COMPLETED. A running
+	 * execution is expected to move from {@code STARTING} to {@code STARTED} to {@code COMPLETED}
 	 * (through the order defined by {@link #upgradeTo(BatchStatus)}). Higher
-	 * values than STARTED signify more serious failure. ABANDONED is used for
-	 * steps that have finished processing, but were not successful, and where
-	 * they should be skipped on a restart (so FAILED is the wrong status).
+	 * values than {@code STARTED} signify more serious failures. {@code ABANDONED} is used for
+	 * steps that have finished processing but were not successful and where
+	 * they should be skipped on a restart (so {@code FAILED} is the wrong status).
 	 */
 
 	/**
@@ -72,7 +72,7 @@ public enum BatchStatus {
 	UNKNOWN;
 
 	/**
-	 * Convenience method to return the higher value status of the statuses pass in to the method.
+	 * Convenience method to return the higher value status of the statuses passed to the method.
 	 *
 	 * @param status1 The first status to check.
 	 * @param status2 The second status to check.
@@ -83,8 +83,8 @@ public static BatchStatus max(BatchStatus status1, BatchStatus status2) {
 	}
 
 	/**
-	 * Convenience method to decide if a status indicates work is in progress.
-	 * 
+	 * Convenience method to decide if a status indicates that work is in progress.
+	 *
 	 * @return true if the status is STARTING, STARTED
 	 */
 	public boolean isRunning() {
@@ -94,8 +94,8 @@ public boolean isRunning() {
 	/**
 	 * Convenience method to decide if a status indicates execution was
 	 * unsuccessful.
-	 * 
-	 * @return true if the status is FAILED or greater
+	 *
+	 * @return {@code true} if the status is {@code FAILED} or greater.
 	 */
 	public boolean isUnsuccessful() {
 		return this == FAILED || this.isGreaterThan(FAILED);
@@ -104,13 +104,13 @@ public boolean isUnsuccessful() {
 	/**
 	 * Method used to move status values through their logical progression, and
 	 * override less severe failures with more severe ones. This value is
-	 * compared with the parameter and the one that has higher priority is
-	 * returned. If both are STARTED or less than the value returned is the
-	 * largest in the sequence STARTING, STARTED, COMPLETED. Otherwise the value
+	 * compared with the parameter, and the one that has higher priority is
+	 * returned. If both are {@code STARTED} or less than the value returned is the
+	 * largest in the sequence {@code STARTING}, {@code STARTED}, {@code COMPLETED}. Otherwise, the value
 	 * returned is the maximum of the two.
-	 * 
-	 * @param other another status to compare to
-	 * @return either this or the other status depending on their priority
+	 *
+	 * @param other Another status to which to compare.
+	 * @return either this or the other status, depending on their priority.
 	 */
 	public BatchStatus upgradeTo(BatchStatus other) {
 		if (isGreaterThan(STARTED) || other.isGreaterThan(STARTED)) {
@@ -124,36 +124,36 @@ public BatchStatus upgradeTo(BatchStatus other) {
 	}
 
 	/**
-	 * @param other a status value to compare
-	 * @return true if this is greater than other
+	 * @param other A status value to which to compare.
+	 * @return {@code true} if this is greater than {@code other}.
 	 */
 	public boolean isGreaterThan(BatchStatus other) {
 		return this.compareTo(other) > 0;
 	}
 
 	/**
-	 * @param other a status value to compare
-	 * @return true if this is less than other
+	 * @param other A status value to which to compare.
+	 * @return {@code true} if this is less than {@code other}.
 	 */
 	public boolean isLessThan(BatchStatus other) {
 		return this.compareTo(other) < 0;
 	}
 
 	/**
-	 * @param other a status value to compare
-	 * @return true if this is less than other
+	 * @param other A status value to which to compare.
+	 * @return {@code true} if this is less than {@code other}.
 	 */
 	public boolean isLessThanOrEqualTo(BatchStatus other) {
 		return this.compareTo(other) <= 0;
 	}
 
 	/**
-	 * Find a BatchStatus that matches the beginning of the given value. If no
-	 * match is found, return COMPLETED as the default because has is low
+	 * Find a {@code BatchStatus} that matches the beginning of the given value. If no
+	 * match is found, return {@code COMPLETED} as the default because it has low
 	 * precedence.
-	 * 
-	 * @param value a string representing a status
-	 * @return a BatchStatus
+	 *
+	 * @param value A string representing a status.
+	 * @return a {BatchStatus} object.
 	 */
 	public static BatchStatus match(String value) {
 		for (BatchStatus status : values()) {

spring-batch-core/src/main/java/org/springframework/batch/core/ChunkListener.java

@@ -18,8 +18,8 @@
 import org.springframework.batch.core.scope.context.ChunkContext;
 
 /**
- * Listener interface for the lifecycle of a chunk.  A chunk
- * can be thought of as a collection of items that will be
+ * Listener interface for the lifecycle of a chunk. A chunk
+ * can be thought of as a collection of items that are
  * committed together.
  *
  * @author Lucas Ward
@@ -52,11 +52,11 @@ default void afterChunk(ChunkContext context) {
 
 	/**
 	 * Callback after a chunk has been marked for rollback.  It is invoked
-	 * after transaction rollback.  While the rollback will have occurred,
-	 * transactional resources might still be active and accessible.  Due to
-	 * this, data access code within this callback will still "participate" in
+	 * after transaction rollback. While the rollback will have occurred,
+	 * transactional resources might still be active and accessible. Due to
+	 * this, data access code within this callback still "participates" in
 	 * the original transaction unless it declares that it runs in its own
-	 * transaction.  Hence: <em> Use PROPAGATION_REQUIRES_NEW for any
+	 * transaction. <em>As a result, you should use {@code PROPAGATION_REQUIRES_NEW} for any
 	 * transactional operation that is called from here.</em>
 	 *
 	 * @param context the chunk context containing the exception that caused

spring-batch-core/src/main/java/org/springframework/batch/core/DefaultJobKeyGenerator.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2006-2021 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.
@@ -26,8 +26,8 @@
 
 /**
  * Default implementation of the {@link JobKeyGenerator} interface.
- * This implementation provides a single hash value based on the JobParameters
- * passed in.  Only identifying parameters (per {@link JobParameter#isIdentifying()})
+ * This implementation provides a single hash value based on the {@link JobParameters} object
+ * passed in. Only identifying parameters (as per {@link JobParameter#isIdentifying()})
  * are used in the calculation of the key.
  *
  * @author Michael Minella

spring-batch-core/src/main/java/org/springframework/batch/core/Entity.java

@@ -22,9 +22,9 @@
 
 /**
  * Batch Domain Entity class. Any class that should be uniquely identifiable
- * from another should subclass from Entity. More information on this pattern
- * and the difference between Entities and Value Objects can be found in Domain
- * Driven Design by Eric Evans.
+ * from another should subclass from Entity. See Domain
+ * Driven Design, by Eric Evans, for more information on this pattern
+ * and the difference between Entities and Value Objects.
  *
  * @author Lucas Ward
  * @author Dave Syer
@@ -75,22 +75,22 @@ public void setId(Long id) {
 	}
 
 	/**
-	 * @return the version
+	 * @return the version.
 	 */
 	public Integer getVersion() {
 		return version;
 	}
 
 	/**
-	 * Public setter for the version needed only by repository methods.
-	 * @param version the version to set
+	 * Public setter for the version. Needed only by repository methods.
+	 * @param version The version to set.
 	 */
 	public void setVersion(Integer version) {
 		this.version = version;
 	}
 
 	/**
-	 * Increment the version number
+	 * Increment the version number.
 	 */
 	public void incrementVersion() {
 		if (version == null) {
@@ -100,14 +100,18 @@ public void incrementVersion() {
 		}
 	}
 
+  /**
+	* Creates a string representation of the {@code Entity},
+	* including the {@code id}, {@code version}, and class name.
+  */
 	@Override
 	public String toString() {
 		return String.format("%s: id=%d, version=%d", ClassUtils.getShortName(getClass()), id, version);
 	}
 
 	/**
-	 * Attempt to establish identity based on id if both exist. If either id
-	 * does not exist use Object.equals().
+	 * Attempt to establish identity based on {@code id} if both exist. If either {@code id}
+	 * does not exist, use {@code Object.equals()}.
 	 *
 	 * @see java.lang.Object#equals(java.lang.Object)
 	 */
@@ -130,13 +134,14 @@ public boolean equals(Object other) {
 	}
 
 	/**
-	 * Use ID if it exists to establish hash code, otherwise fall back to
-	 * Object.hashCode(). Based on the same information as equals, so if that
-	 * changes, this will. N.B. this follows the contract of Object.hashCode(),
+	 * Use {@code id}, if it exists, to establish a hash code. Otherwise fall back to
+	 * {@code Object.hashCode()}. It is based on the
+	 * same information as {@code equals}, so, if that
+	 * changes, this will. Note that this follows the contract of {@code Object.hashCode()}
 	 * but will cause problems for anyone adding an unsaved {@link Entity} to a
-	 * Set because Set.contains() will almost certainly return false for the
+	 * {@code Set} because {@code Set.contains()} almost certainly returns false for the
 	 * {@link Entity} after it is saved. Spring Batch does not store any of its
-	 * entities in Sets as a matter of course, so internally this is consistent.
+	 * entities in sets as a matter of course, so this is internally consistent.
 	 * Clients should not be exposed to unsaved entities.
 	 *
 	 * @see java.lang.Object#hashCode()