Javadoc editing

for grammar, punctuation, usage, and (sometimes) missing content.

Author: Jay Bryant

spring-batch-core/src/main/java/org/springframework/batch/core/converter/DefaultJobParametersConverter.java

@@ -36,19 +36,20 @@
 import java.util.Properties;
 
 /**
- * Converter for {@link JobParameters} instances using a simple naming convention for
- * property keys. Key names that are prefixed with a - are considered non-identifying and
- * will not contribute to the identity of a {@link JobInstance}. Key names ending with
- * "(<type>)" where type is one of string, date, long are converted to the
- * corresponding type. The default type is string. E.g.
+ * Converter for {@link JobParameters} instances that uses a simple naming convention for
+ * property keys. Key names that are prefixed with a {@code -} are considered
+ * non-identifying and do not contribute to the identity of a {@link JobInstance}. Key
+ * names ending with "(<type>)" (where type is one of string, date, long) are
+ * converted to the corresponding type. The default type is string. Consider the following
+ * example:
  *
  * <pre>
  * schedule.date(date)=2007/12/11
  * department.id(long)=2345
  * </pre>
  *
- * The literal values are converted to the correct type using the default Spring
- * strategies, augmented if necessary by the custom editors provided.
+ * The literal values are converted to the correct type by using the default Spring
+ * strategies, augmented if necessary by any custom editors that have been provided.
  *
  * <br>
  *
@@ -96,9 +97,9 @@ public class DefaultJobParametersConverter implements JobParametersConverter {
 	private final NumberFormat longNumberFormat = new DecimalFormat("#");
 
 	/**
-	 * Check for suffix on keys and use those to decide how to convert the value.
+	 * Check for a suffix on keys and use those to decide how to convert the value.
 	 * @throws IllegalArgumentException if a number or date is passed in that cannot be
-	 * parsed, or cast to the correct type.
+	 * parsed or cast to the correct type.
 	 *
 	 * @see org.springframework.batch.core.converter.JobParametersConverter#getJobParameters(java.util.Properties)
 	 */
@@ -175,7 +176,7 @@ private boolean isIdentifyingKey(String key) {
 	}
 
 	/**
-	 * Delegate to {@link NumberFormat} to parse the value
+	 * Delegate to {@link NumberFormat} to parse the value.
 	 */
 	private Number parseNumber(String value) {
 		synchronized (numberFormat) {
@@ -192,9 +193,9 @@ private Number parseNumber(String value) {
 
 	/**
 	 * Use the same suffixes to create properties (omitting the string suffix because it
-	 * is the default). Non-identifying parameters will be prefixed with the
+	 * is the default). Non-identifying parameters are prefixed with the
 	 * {@link #NON_IDENTIFYING_FLAG}. However, since parameters are identifying by
-	 * default, they will <em>not</em> be prefixed with the {@link #IDENTIFYING_FLAG}.
+	 * default, they are <em>not</em> prefixed with the {@link #IDENTIFYING_FLAG}.
 	 *
 	 * @see org.springframework.batch.core.converter.JobParametersConverter#getProperties(org.springframework.batch.core.JobParameters)
 	 */
@@ -236,8 +237,10 @@ else if (jobParameter.getType() == ParameterType.DOUBLE) {
 	}
 
 	/**
-	 * @param value a decimal value
-	 * @return a best guess at the desired format
+	 * Makes a best guess at converting a double to a string representation of a decimal
+	 * format.
+	 * @param value A decimal value.
+	 * @return a best guess at the desired format.
 	 */
 	private String decimalFormat(double value) {
 		if (numberFormat != DEFAULT_NUMBER_FORMAT) {
@@ -250,15 +253,15 @@ private String decimalFormat(double value) {
 
 	/**
 	 * Public setter for injecting a date format.
-	 * @param dateFormat a {@link DateFormat}, defaults to "yyyy/MM/dd"
+	 * @param dateFormat A {@link DateFormat}, defaults to "yyyy/MM/dd".
 	 */
 	public void setDateFormat(DateFormat dateFormat) {
 		this.dateFormat = dateFormat;
 	}
 
 	/**
 	 * Public setter for the {@link NumberFormat}. Used to parse longs and doubles, so
-	 * must not contain decimal place (e.g. use "#" or "#,###").
+	 * must not contain decimal place (for example, use "#" or "#,###" but not "#.##").
 	 * @param numberFormat the {@link NumberFormat} to set
 	 */
 	public void setNumberFormat(NumberFormat numberFormat) {

spring-batch-core/src/main/java/org/springframework/batch/core/converter/JobParametersConverter.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2006-2018 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.
@@ -24,8 +24,8 @@
 
 /**
  * A factory for {@link JobParameters} instances. A job can be executed with many possible
- * runtime parameters, which identify the instance of the job. This converter allows job
- * parameters to be converted to and from Properties.
+ * runtime parameters, which identify the instance of the job. This converter lets job
+ * parameters be converted to and from properties.
  *
  * @author Dave Syer
  * @author Mahmoud Ben Hassine
@@ -35,18 +35,18 @@
 public interface JobParametersConverter {
 
 	/**
-	 * Get a new {@link JobParameters} instance. If given null, or an empty properties, an
-	 * empty JobParameters will be returned.
-	 * @param properties the runtime parameters in the form of String literals.
-	 * @return a {@link JobParameters} properties converted to the correct types.
+	 * Get a new {@link JobParameters} instance. If given null or an empty properties, an
+	 * empty JobParameters is returned.
+	 * @param properties The runtime parameters in the form of String literals.
+	 * @return a {@link JobParameters} object converted to the correct types.
 	 */
 	JobParameters getJobParameters(@Nullable Properties properties);
 
 	/**
 	 * The inverse operation: get a {@link Properties} instance. If given null or empty
-	 * JobParameters, an empty Properties should be returned.
-	 * @param params the {@link JobParameters} instance to be converted.
-	 * @return a representation of the parameters as properties
+	 * {@code JobParameters}, an empty {@code Properties} should be returned.
+	 * @param params The {@link JobParameters} instance to be converted.
+	 * @return a representation of the parameters as properties.
 	 */
 	Properties getProperties(@Nullable JobParameters params);