Clean up / fix grammatical errors in documentation and comments, part 6

src/main/java/org/kiwiproject/config/SecureEndpointsConfiguration.java

@@ -15,7 +15,7 @@
 /**
  * Configuration for secure REST endpoints, including the configuration from an {@link SSLContextConfiguration}
  * as well as adding a collection of {@link EndpointConfiguration} instances. Supports programmatic creation
- * using a builder. Also supports construction from external configuration, e.g. from a YAML configuration file, using
+ * using a builder. Also supports construction from external configuration, e.g., from a YAML configuration file, using
  * the no-args constructor and setter methods.
  * <p>
  * As this is a configuration class that supports population from external configuration, it is mutable.
@@ -30,7 +30,7 @@ public class SecureEndpointsConfiguration extends SSLContextConfiguration {
     private List<EndpointConfiguration> endpoints;
 
     /**
-     * Create instance with empty collection of endpoints.
+     * Create instance with an empty collection of endpoints.
      */
     public SecureEndpointsConfiguration() {
         this.endpoints = new ArrayList<>();

src/main/java/org/kiwiproject/jdbc/SqlOrder.java

@@ -9,7 +9,7 @@
 /**
  * Simple enum that represents the values for SQL {@code ORDER BY} clauses.
  * <p>
- * This is useful in building queries, for example when using JDBI and the SQL objects API you might
+ * This is useful in building queries, for example, when using JDBI and the SQL objects API you might
  * need to add dynamic ordering based on user input but want to ensure no SQL injection attack is possible.
  * So you would accept user input and then use {@link #from(String)} to get a {@link SqlOrder} instance.
  * Then, you could use it in a JDBI {@code SqlQuery} annotation as one example.
@@ -23,7 +23,7 @@ public enum SqlOrder {
      *
      * @param value the value to convert from
      * @return the SqlOrder enum corresponding to the given value
-     * @throws IllegalArgumentException if an invalid value is provided that does not map to a SqlOrder enum constant
+     * @throws IllegalArgumentException if an invalid value is provided but does not map to a SqlOrder enum constant
      */
     public static SqlOrder from(String value) {
         var trimmedValue = Optional.ofNullable(value).map(String::trim).orElse("");
@@ -61,7 +61,7 @@ public <T> List<T> searchWith(Supplier<List<T>> ascSearch, Supplier<List<T>> des
     /**
      * Return a string that can be used directly in a SQL {@code ORDER BY} clause.
      *
-     * @return a string that can be used in a SQL query
+     * @return a string that can be used in an SQL query
      */
     public String toSql() {
         return name();

src/main/java/org/kiwiproject/jsch/SftpConfig.java

@@ -96,7 +96,7 @@ public class SftpConfig {
     private String knownHostsFile;
 
     /**
-     * Provides option to disable strict host key checking, equivalent to the
+     * Provides an option to disable strict host key checking, equivalent to the
      * {@code -o StrictHostKeyChecking=[yes|no]} option.
      * <p>
      * The default is false. See the {@code ssh_info} man page for more details.
@@ -120,7 +120,7 @@ public class SftpConfig {
      * @param host                      the remote host
      * @param user                      the SFTP username
      * @param password                  the SFTP password
-     * @param privateKeyFilePath        path to private key file
+     * @param privateKeyFilePath        path to the private key file
      * @param preferredAuthentications  comma-separated list of authentications to attempt
      * @param remoteBasePath            root directory of the remote SFTP location
      * @param errorPath                 local directory to write out any errors if SFTP fails
@@ -129,8 +129,8 @@ public class SftpConfig {
      * @param timeout                   the SFTP connection timeout
      * @implNote This is intentionally not using Lombok because using {@link lombok.AllArgsConstructor} together
      * with @{@link lombok.Builder} results in an all-args constructor that does not respect {@link lombok.Builder.Default}.
-     * As a result we need to handle the defaults ourselves. This is intended to be used during deserialization
-     * from an external configuration file (e.g. a Dropwizard YAML configuration file, or from JSON). Prefer the
+     * As a result, we need to handle the defaults ourselves. This is intended to be used during deserialization
+     * from an external configuration file (e.g., a Dropwizard YAML configuration file, or from JSON). Prefer the
      * builder when constructing programmatically.
      */
     // Suppress Sonar's "Methods should not have too many parameters". We need this for the builder and for

src/main/java/org/kiwiproject/jsch/SftpConnector.java

@@ -62,7 +62,7 @@ public SftpConnector(JSch jsch, SftpConfig config) {
      *
      * @param config The configuration used for setting up the connection
      * @return The initialized and opened sftp connection
-     * @apiNote This is a convenience method to not have to call connect after initialization.
+     * @apiNote This is a convenience method to not have to call {@code connect} after initialization.
      */
     public static SftpConnector setupAndOpenConnection(SftpConfig config) {
         return setupAndOpenConnection(new JSch(), config);

src/main/java/org/kiwiproject/jsch/SftpTransfers.java

@@ -191,7 +191,7 @@ public String getFileContent(Path remotePath, String remoteFilename) {
 
     /**
      * Gets a file off of a remote server with the given path and given filename and returns an {@link InputStream}. This
-     * is useful if the remote file is binary and not a text based file.
+     * is useful if the remote file is binary and not a text-based file.
      * <p>
      * Note: The caller of this method is responsible for closing the stream.
      *

src/main/java/org/kiwiproject/json/RuntimeJsonException.java

@@ -6,7 +6,7 @@
 public class RuntimeJsonException extends RuntimeException {
 
     /**
-     * Create instance with given cause.
+     * Create an instance with the given cause.
      *
      * @param cause the cause
      */
@@ -15,7 +15,7 @@ public RuntimeJsonException(Throwable cause) {
     }
 
     /**
-     * Create instance with given message and cause.
+     * Create an instance with the given message and cause.
      *
      * @param message the message
      * @param cause   the cause

src/main/java/org/kiwiproject/net/SimpleHostAndPort.java

@@ -14,7 +14,7 @@
  * (Just go look at the code in {@link com.google.common.net.HostAndPort#fromString(String)} if you don't believe me.)
  * Because it is much simpler, it also only handles a very specific host/port format, which is {@code host:port}.
  * <p>
- * It also does not attempt to validate anything about the host or port, e.g. it will happily accept a negative port
+ * It also does not attempt to validate anything about the host or port, e.g., it will happily accept a negative port
  * value or a one-character long host name.
  */
 @EqualsAndHashCode
@@ -33,7 +33,7 @@ public class SimpleHostAndPort {
      * <p>
      * <em>No validation is performed on the default values.</em>
      *
-     * @param hostPortString a string containing host and port, e.g. acme.com:8001
+     * @param hostPortString a string containing host and port, e.g., acme.com:8001
      * @param defaultHost    a default host if the host/port string is blank
      * @param defaultPort    a default port if the host/port string is blank
      * @return a new SimpleHostAndPort instance
@@ -49,7 +49,7 @@ public static SimpleHostAndPort from(String hostPortString, String defaultHost,
     /**
      * Parse {@code hostPortString} assuming format {@code host:port}
      *
-     * @param hostPortString a string containing host and port, e.g. foo.com:9000
+     * @param hostPortString a string containing host and port, e.g., foo.com:9000
      * @return a new SimpleHostAndPort instance
      * @throws IllegalStateException if not in the expected format
      * @throws IllegalArgumentException if hostPortString is blank or port is not a valid number

src/main/java/org/kiwiproject/reflect/RuntimeReflectionException.java

@@ -4,7 +4,7 @@
  * A custom runtime exception for wrapping (checked or unchecked) exceptions related to reflection.
  * <p>
  * There are no restrictions on the wrapped {@link Throwable}, but the <em>intent</em> is that they should be
- * some checked or unchecked exception that was thrown by a reflective operation, e.g. reflectively
+ * some checked or unchecked exception that was thrown by a reflective operation, e.g., reflectively
  * finding or invoking a method, or accessing a field.
  */
 @SuppressWarnings("unused")

src/main/java/org/kiwiproject/retry/RetryResult.java

@@ -16,16 +16,16 @@
 
 /**
  * Defines a result of one or more attempts to get some type of object. The list of errors should reflect the order
- * in which errors occurred, e.g. the first error should be the error for the first attempt, second error should be
+ * in which errors occurred, e.g., the first error should be the error for the first attempt, the second error should be
  * the error for the second attempt, etc.
  * <p>
- * A unique identifier is automatically assigned to new {@link RetryResult} instances for easy identification, e.g.
+ * A unique identifier is automatically assigned to new {@link RetryResult} instances for easy identification, e.g.,
  * when logging retry exceptions.
  * <p>
- * Note that there is nothing precluding a {@link RetryResult} from representing a failure but not actually have any
+ * Note that there is nothing precluding a {@link RetryResult} from representing a failure but not have any
  * errors. This could happen, for example, if retry code executes a {@link java.util.function.Supplier}
  * and that supplier is implemented to catch all exceptions and return {@code null} to force a retry. We generally
- * recommend to implement Suppliers to throw exceptions when errors occur. They will need to be subclasses of
+ * recommend implementing Suppliers to throw exceptions when errors occur. They will need to be subclasses of
  * {@link RuntimeException} since {@link java.util.function.Supplier} doesn't permit checked exceptions, plus we
  * generally prefer unchecked exceptions.
  *
@@ -143,7 +143,7 @@ public int getNumErrors() {
      * Assumes there is at least one error, and returns the last one that was thrown regardless of the number
      * of attempts.
      * <p>
-     * You should check if there are any errors, e.g. using {@link #hasAnyErrors()}, before calling this method.
+     * You should check if there are any errors, e.g., using {@link #hasAnyErrors()}, before calling this method.
      * Alternatively consider using {@link #getLastErrorIfPresent}.
      *
      * @return the most recent exception that occurred

src/main/java/org/kiwiproject/retry/RetryResultLogger.java

@@ -25,8 +25,8 @@ public class RetryResultLogger {
      *
      * @param result                    the result
      * @param logger                    the SLF4J logger to use
-     * @param actionDescriptionSupplier a {@link Supplier} that provides a description of the action that was attempted
-     *                                  for example "Create new order #12345" or "Update order #456"
+     * @param actionDescriptionSupplier a {@link Supplier} that provides a description of the action that was attempted,
+     *                                  for example, "Create new order #12345" or "Update order #456"
      * @param <T>                       the type held in the result
      * @see #logSummary(RetryResult, Logger, String)
      */
@@ -46,8 +46,8 @@ public static <T> void logSummaryIfFailed(RetryResult<T> result,
      *
      * @param result                    the result
      * @param logger                    the SLF4J logger to use
-     * @param actionDescriptionSupplier a {@link Supplier} that provides a description of the action that was attempted
-     *                                  for example "Create new order #12345" or "Update order #456"
+     * @param actionDescriptionSupplier a {@link Supplier} that provides a description of the action that was attempted,
+     *                                  for example, "Create new order #12345" or "Update order #456"
      * @param <T>                       the type held in the result
      */
     public static <T> void logSummaryIfHasErrorsOrMultipleAttempts(RetryResult<T> result,
@@ -71,7 +71,7 @@ private static <T> void logSummaryWithDescriptionSupplier(RetryResult<T> result,
 
     /**
      * Logs a high-level summary of the result. The log level is dependent on whether the result was successful
-     * or not, and whether there were any errors (e.g. a result was successful but took more than one attempt).
+     * or not, and whether there were any errors (e.g., a result was successful but took more than one attempt).
      * <p>
      * The log levels are:
      * <p>
@@ -83,8 +83,8 @@ private static <T> void logSummaryWithDescriptionSupplier(RetryResult<T> result,
      *
      * @param result            the result
      * @param logger            the SLF4J logger to use
-     * @param actionDescription a {@link Supplier} that provides a description of the action that was attempted
-     *                          for example "Create new order #12345" or "Update order #456"
+     * @param actionDescription a {@link Supplier} that provides a description of the action that was attempted,
+     *                          for example, "Create new order #12345" or "Update order #456"
      * @param <T>               the type held in the result
      */
     public static <T> void logSummary(RetryResult<T> result, Logger logger, String actionDescription) {