Clean up / fix grammatical errors in documentation and comments (#1185)

.github/workflows/build.yml

@@ -22,7 +22,7 @@ jobs:
         with:
           fetch-depth: 0  # Shallow clones should be disabled for a better relevancy of analysis
 
-      # Setup the version of Java
+      # Set up the version of Java
       - name: Set up JDK ${{ matrix.java_version }}
         uses: actions/setup-java@v4
         with:

src/main/java/org/kiwiproject/beans/BeanConverter.java

@@ -65,7 +65,7 @@ public T convert(T input) {
     }
 
     /**
-     * This conversion method takes two parameters and copies properties from one object to another
+     * This conversion method takes two parameters, and it copies properties from one object to another
      *
      * @param input  the object to copy the properties from
      * @param target the object to copy the properties too (destination)
@@ -83,14 +83,14 @@ public <R> R convert(T input, R target) {
 
         var propertyNames = getPropertySet(input, inputWrapper);
 
-        // This can not be a foreach because if failOnError is true, the exceptions need to bubble.
+        // This cannot be a foreach because if failOnError is true, the exceptions need to bubble.
         for (String propName : propertyNames) {
             if (hasPropertyMapper(propName)) {
                 // custom mapper
                 var func = getPropertyMapper(propName);
                 func.apply(input);
             } else if (input != target) {
-                // only need to map simple properties if it's not the same object
+                // only need to map simple properties if it's a different object
                 var inputValue = readBeanValue(input, inputWrapper, propName);
                 writeBeanValue(target, targetWrapper, propName, inputValue);
 

src/main/java/org/kiwiproject/concurrent/Async.java

@@ -23,12 +23,12 @@
 
 /**
  * Static utilities that work with {@link java.util.concurrent.CompletableFuture} and can make testing easier by
- * permitting selective (e.g. in unit tests) forcing of synchronous behavior for things that would normally
+ * permitting selective (e.g., in unit tests) forcing of synchronous behavior for things that would normally
  * execute asynchronously. This applies only to some methods, so read the method's documentation before assuming.
  * <p>
  * Use the {@code xxxAsync} methods when you need to control concurrent behavior and make things deterministic
- * during unit tests (e.g. blocking on futures). Note this does actually change the true behavior of the code under
- * test, since methods will execute synchronously, so use with care, caution, and understanding.
+ * during unit tests (e.g., blocking on futures). Note this does actually change the true behavior of the code under
+ * test, since methods will execute synchronously, so use them with care, caution, and understanding.
  *
  * @implNote the "asyncMode" flag is a STATIC variable and should only ever be changed during testing using the
  * {@link #setUnitTestAsyncMode(Mode)} method. Generally, you should set this before tests and reset after

src/main/java/org/kiwiproject/concurrent/AsyncException.java

@@ -23,7 +23,7 @@ public class AsyncException extends RuntimeException {
     private final transient CompletableFuture<?> future;
 
     /**
-     * Construct instance with given message and future.
+     * Construct instance with the given message and future.
      *
      * @param message the exception message
      * @param future  the {@link CompletableFuture} that caused the error, may be null
@@ -34,7 +34,7 @@ public AsyncException(String message, @Nullable CompletableFuture<?> future) {
     }
 
     /**
-     * Construct instance with given message, cause, and future.
+     * Construct instance with the given message, cause, and future.
      *
      * @param message the exception message
      * @param cause   the original cause of the exception
@@ -50,7 +50,7 @@ public AsyncException(String message, Throwable cause, @Nullable CompletableFutu
      *
      * @return true if this instance contains a CompletableFuture
      * @apiNote When a single asynchronous operation is performed and there is only one future, then callers can
-     * expect this to contain a CompletableFuture and return true. When multiple futures are acted upon (e.g. waiting
+     * expect this to contain a CompletableFuture and return true. When multiple futures are acted upon (e.g., waiting
      * for all to complete), callers should expect this instance not to contain a CompletableFuture and this method
      * to return false.
      */
@@ -59,7 +59,7 @@ public boolean hasFuture() {
     }
 
     /**
-     * The future which causes the exception. May be null. Use {@link #hasFuture()} to check if this instance
+     * The future which causes the exception; it may be null. Use {@link #hasFuture()} to check if this instance
      * contains a future.
      *
      * @param <T> the generic type of the CompletableFuture

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

@@ -30,7 +30,7 @@ public class EndpointConfiguration {
 
     /**
      * Use this to uniquely identify an endpoint within a {@link SecureEndpointsConfiguration}, or to provide
-     * a way to find an {@link EndpointConfiguration} in any collection of them, e.g. using a
+     * a way to find an {@link EndpointConfiguration} in any collection of them, e.g., using a
      * {@link java.util.stream.Stream#filter(Predicate)} on a stream of endpoint configurations.
      *
      * @see SecureEndpointsConfiguration#getEndpointByTag(String)
@@ -39,7 +39,7 @@ public class EndpointConfiguration {
     private String tag;
 
     /**
-     * The connection scheme, e.g. https or https.
+     * The connection scheme, e.g., https or https.
      */
     private String scheme;
 
@@ -87,7 +87,7 @@ public class EndpointConfiguration {
      * instance that becomes the "parent" of this endpoint.
      *
      * @implNote This was implemented well before we started using Lombok, thus the manual builder code. Since there
-     * are some differences here, e.g. the constructor accepting the "parent" and the {@link #buildEndpoint()} method,
+     * are some differences here, e.g., the constructor accepting the "parent" and the {@link #buildEndpoint()} method,
      * not sure how feasible it is to refactor to use Lombok, or if it's worth bothering. In addition, we have left
      * the original setXxx() methods in here and added Lombok-style xxx() methods. While permissible, you
      * should be consistent in using all xxx() or all setXxx().
@@ -210,8 +210,8 @@ public boolean isSecure() {
     }
 
     /**
-     * Set the domain(s), which can be a single domain (e.g. example.org) or multiple domains separated by commas. If
-     * a comma-separated list of domains is specified, whitespace is allowed and trimmed. For example this is
+     * Set the domain(s), which can be a single domain (e.g., example.org) or multiple domains separated by commas. If
+     * a comma-separated list of domains is specified, whitespace is allowed and trimmed. For example, this is
      * valid: " domain-1.test , domain-2.test , domain-3.test " and results in the three domains "domain-1.test",
      * "domain-2.test", and "domain-3.test".
      *
@@ -236,7 +236,7 @@ public List<String> getDomains() {
      * round-robin among the domains returned by {@link #getDomains()}.
      *
      * @return the URI as a {@link String}
-     * @implNote This currently builds URIs using simple string substitution, any leading or trailing slashes
+     * @implNote This currently builds URIs using simple string substitution; any leading or trailing slashes
      * on the domain are stripped.
      */
     public String getURI() {
@@ -271,7 +271,7 @@ private String getUriWithNextHost(String thePath) {
      * ever a (good) reason to change this to use an internal lock or similar, it will be relatively easy since
      * this method is private, thus not a part of the public API. This change was made because of an error we
      * encountered wherein we saw some {@link ArrayIndexOutOfBoundsException} occurring on the
-     * {@code domainList.get(index)} call. This cause was due to multiple threads accessing concurrently.
+     * {@code domainList.get(index)} call. The cause was due to multiple threads accessing it concurrently.
      */
     private synchronized String getNextDomain() {
         checkState(nonNull(domainList), "No domains have been set on this endpoint!");

src/main/java/org/kiwiproject/dropwizard/jdbi3/DatabaseType.java

@@ -9,7 +9,7 @@
 /**
  * This enum allows you to instantiate a {@link JdbiPlugin} for certain databases based on the JDBC database URL.
  * <p>
- * Currently, supports only Postgres and H2.
+ * Currently, this supports only Postgres and H2.
  */
 enum DatabaseType {
 
@@ -27,7 +27,7 @@ enum DatabaseType {
     /**
      * Given a JDBC database URL, attempt to find and instantiate a plugin.
      * <p>
-     * Currently, supports only H2 and Postgres.
+     * Currently, this supports only H2 and Postgres.
      *
      * @param databaseUrl the JDBC database URL
      * @return an Optional with a plugin instance or an empty Optional
@@ -40,7 +40,7 @@ static Optional<JdbiPlugin> pluginFromDatabaseUrl(String databaseUrl) {
     /**
      * Determine the database type from the given JDBC database URL.
      * <p>
-     * Currently, supports only H2 and Postgres.
+     * Currently, this supports only H2 and Postgres.
      *
      * @param databaseUrl the JDBC database URL
      * @return an Optional containing the database type if found, otherwise an empty Optional

src/main/java/org/kiwiproject/dropwizard/jdbi3/Jdbi3Builders.java

@@ -24,7 +24,7 @@
  * <p>
  * The {@link SqlObjectPlugin} is always installed, and is assumed to be on the classpath.
  * <p>
- * Note also that when installing plugins, JDBI ignores duplicates (e.g. if you attempt to install more than one
+ * Note also that when installing plugins, JDBI ignores duplicates (e.g., if you attempt to install more than one
  * {@link SqlObjectPlugin}) <em>only when the plugin is designed as a "single-install" plugin</em>. JDBI plugins
  * are "single-install" when they extend the package-private {@code JdbiPlugin.Singleton} class.
  */

src/main/java/org/kiwiproject/jaxrs/exception/ConstraintViolationExceptionMapper.java

@@ -16,15 +16,15 @@
  * here. But in reality, many web frameworks use 422 to indicate an input validation failure, which is how we are
  * using it here.
  * <p>
- * It is important to note that the {@link Response.Status} does <em>not</em> contain an enum constant for 422 status,
+ * It is important to note that the {@link Response.Status} does <em>not</em> contain an enum constant for status 422,
  * so that {@link Response.Status#fromStatusCode(int)} will return {@code null} when given 422.
  */
 @Provider
 public class ConstraintViolationExceptionMapper implements ExceptionMapper<ConstraintViolationException> {
 
     /**
-     * We have no way to obtain the item ID from a {@link ConstraintViolationException}. Instead, we will set
-     * it to null, which is not lovely but there's not much else we can do.
+     * We have no way to get the item ID from a {@link ConstraintViolationException}. Instead, we will set
+     * it to null, which is not lovely, but there's little else we can do.
      */
     private static final String ITEM_ID = null;
 

src/main/java/org/kiwiproject/jaxrs/exception/ErrorMessage.java

@@ -18,7 +18,7 @@
  * Dropwizard class of the same name.
  * <p>
  * Each instance contains the HTTP status (error) code; the error message; an optional identifier to identify the
- * specific item causing the error (e.g. a primary key); and an optional field/property name for cases when a specific
+ * specific item causing the error (e.g., a primary key); and an optional field/property name for cases when a specific
  * field causes the error.
  */
 @Getter

src/main/java/org/kiwiproject/jaxrs/exception/JaxrsBadRequestException.java

@@ -29,7 +29,7 @@ public JaxrsBadRequestException(String message) {
     }
 
     /**
-     * New instance with given message, cause, and 400 status code.
+     * New instance with given message, cause, and a 400 status code.
      *
      * @param message the message for this exception
      * @param cause   the cause of this exception
@@ -39,7 +39,7 @@ public JaxrsBadRequestException(String message, Throwable cause) {
     }
 
     /**
-     * New instance with the given message and field name, and 400 status code.
+     * New instance with the given message and field name, and a 400 status code.
      *
      * @param message   the message for this exception
      * @param fieldName the field/property name that caused this error
@@ -49,7 +49,7 @@ public JaxrsBadRequestException(String message, String fieldName) {
     }
 
     /**
-     * New instance with the given message, field name, item ID, and 400 status code.
+     * New instance with the given message, field name, item ID, and a 400 status code.
      *
      * @param message   the message for this exception
      * @param fieldName the field/property name that caused this error

src/main/java/org/kiwiproject/jaxrs/exception/JaxrsConflictException.java

@@ -20,7 +20,7 @@ public JaxrsConflictException(Throwable cause) {
     }
 
     /**
-     * New instance with given message and 409 status code.
+     * New instance with given message and a 409 status code.
      *
      * @param message the message for this exception
      */
@@ -29,7 +29,7 @@ public JaxrsConflictException(String message) {
     }
 
     /**
-     * New instance with given message, cause, and 409 status code.
+     * New instance with given message, cause, and a 409 status code.
      *
      * @param message the message for this exception
      * @param cause   the cause of this exception
@@ -39,7 +39,7 @@ public JaxrsConflictException(String message, Throwable cause) {
     }
 
     /**
-     * New instance with the given message and field name, and 409 status code.
+     * New instance with the given message and field name, and a 409 status code.
      *
      * @param message   the message for this exception
      * @param fieldName the field/property name that caused this error
@@ -49,7 +49,7 @@ public JaxrsConflictException(String message, String fieldName) {
     }
 
     /**
-     * New instance with the given message, field name, item ID, and 409 status code.
+     * New instance with the given message, field name, item ID, and a 409 status code.
      *
      * @param message   the message for this exception
      * @param fieldName the field/property name that caused this error
@@ -60,7 +60,7 @@ public JaxrsConflictException(String message, String fieldName, String itemId) {
     }
 
     /**
-     * New instance with the given message, field name, item ID, cause, and 409 status code.
+     * New instance with the given message, field name, item ID, cause, and a 409 status code.
      *
      * @param message   the message for this exception
      * @param fieldName the field/property name that caused this error

src/main/java/org/kiwiproject/jaxrs/exception/JaxrsException.java

@@ -80,7 +80,7 @@ public JaxrsException(String message, int statusCode) {
     }
 
     /**
-     * New instance with given message and cause.
+     * New instance with the given message and cause.
      *
      * @param message the message for this exception
      * @param cause   the cause of this exception
@@ -140,7 +140,7 @@ private static String nullSafeMessage(Throwable throwable) {
     }
 
     /**
-     * New "aggregate" instance with given list of ErrorMessage objects. The {@code statusCode} can be
+     * New "aggregate" instance with the given list of ErrorMessage objects. The {@code statusCode} can be
      * {@code null} if a "rolled up" overall status is desired, or an explicit code be given to represent
      * all the errors. The message of this exception is taken from the first ErrorMessage.
      *
@@ -163,7 +163,7 @@ private static ErrorMessage firstErrorOrNull(List<ErrorMessage> errors) {
     }
 
     /**
-     * New "aggregate" instance with given list of JaxrsException objects.
+     * New "aggregate" instance with the given list of JaxrsException objects.
      *
      * @param exceptions the JaxrsException objects that caused this exception
      */
@@ -231,17 +231,17 @@ public int getStatusCode() {
      * Calculates an overall status code as the "roll up" of the status codes in the ErrorMessage objects contained
      * in this exception.
      * <p>
-     * If there are no ErrorMessage objects a default status code is returned. If there is exactly one ErrorMessage,
+     * If there are no ErrorMessage objects, a default status code is returned. If there is exactly one ErrorMessage,
      * then its status code is returned.
      * <p>
      * If there are multiple ErrorMessage objects, and they all have the same status code, then the overall status
      * is just that status code.
      * <p>
      * Last, if there are multiple ErrorMessage objects, and some have different status codes, then the overall status
-     * is calculated to be the base status code (e.g. 400) of the highest error family (e.g. 4xx). For example, if
+     * is calculated to be the base status code (e.g., 400) of the highest error family (e.g., 4xx). For example, if
      * there are multiple 4xx errors then the overall status is considered as the base of the 4xx series, or 400.
      * Or if there are both 4xx and 5xx errors, the overall status is 500 (the base of the 5xx series). This is
-     * obviously a lossy "algorithm" and is meant as an overall indication of the error family. Inspection of all
+     * a lossy "algorithm" and is meant as an overall sign of the error family. Inspection of all
      * contained errors is required to fully determine the causes.
      *
      * @return the "rolled up" status code

src/main/java/org/kiwiproject/jaxrs/exception/JaxrsForbiddenException.java

@@ -29,7 +29,7 @@ public JaxrsForbiddenException(String message) {
     }
 
     /**
-     * New instance with given message, cause, and 403 status code.
+     * New instance with the given message, cause, and 403 status code.
      *
      * @param message the message for this exception
      * @param cause   the cause of this exception
@@ -39,7 +39,7 @@ public JaxrsForbiddenException(String message, Throwable cause) {
     }
 
     /**
-     * New instance with the given message and field name, and 403 status code.
+     * New instance with the given message and field name, and a 403 status code.
      *
      * @param message   the message for this exception
      * @param fieldName the field/property name that caused this error
@@ -49,7 +49,7 @@ public JaxrsForbiddenException(String message, String fieldName) {
     }
 
     /**
-     * New instance with the given message, field name, item ID, and 403 status code.
+     * New instance with the given message, field name, item ID, and a 403 status code.
      *
      * @param message   the message for this exception
      * @param fieldName the field/property name that caused this error

src/main/java/org/kiwiproject/jaxrs/exception/JaxrsInternalServerErrorException.java

@@ -30,7 +30,7 @@ public JaxrsInternalServerErrorException(String message) {
     }
 
     /**
-     * New instance with given message, cause, and 500 status code.
+     * New instance with given message, cause, and a 500 status code.
      *
      * @param message the message for this exception
      * @param cause   the cause of this exception
@@ -40,7 +40,7 @@ public JaxrsInternalServerErrorException(String message, Throwable cause) {
     }
 
     /**
-     * New instance with the given message and field name, and 500 status code.
+     * New instance with the given message and field name, and a 500 status code.
      *
      * @param message   the message for this exception
      * @param fieldName the field/property name that caused this error
@@ -50,7 +50,7 @@ public JaxrsInternalServerErrorException(String message, String fieldName) {
     }
 
     /**
-     * New instance with the given message, field name, item ID, and 500 status code.
+     * New instance with the given message, field name, item ID, and a 500 status code.
      *
      * @param message   the message for this exception
      * @param fieldName the field/property name that caused this error
@@ -61,7 +61,7 @@ public JaxrsInternalServerErrorException(String message, String fieldName, Strin
     }
 
     /**
-     * New instance with the given message, field name, item ID, cause, and 500 status code.
+     * New instance with the given message, field name, item ID, cause, and a 500 status code.
      *
      * @param message   the message for this exception
      * @param fieldName the field/property name that caused this error