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

README.md

@@ -35,7 +35,7 @@ If you are using kiwi's custom constraints _in addition to custom constraints pr
 this requires some additional configuration, otherwise only one of the `ContributorValidationMessages.properties`
 provided by each library will be found, and therefore the custom messages for some constraints won't be found
 during validation. To fix this, all `ContributorValidationMessages.properties` files must be combined into a
-single file, for example using the [Maven Shade plugin](https://maven.apache.org/plugins/maven-shade-plugin/) and an
+single file, for example, using the [Maven Shade plugin](https://maven.apache.org/plugins/maven-shade-plugin/) and an
 [AppendingTransformer](https://maven.apache.org/plugins/maven-shade-plugin/examples/resource-transformers.html#AppendingTransformer):
 
 ```xml

src/main/java/org/kiwiproject/base/KiwiThrowables.java

@@ -39,7 +39,7 @@ public static final class ThrowableInfo {
          * @return a new instance representing the "empty" ThrowableInfo
          * @apiNote This is currently not public, but this might change in the future. For now, we assume that the
          * singleton instance returned by {@link #emptyThrowableInfo()} is the correct method to use. This class is
-         * immutable so creating new instances instead of using the singleton instance doesn't seem to make sense.
+         * immutable, so creating new instances instead of using the singleton instance doesn't seem to make sense.
          */
         private static ThrowableInfo emptyInstance() {
             return new ThrowableInfo(null, null, null, null);
@@ -74,14 +74,14 @@ public boolean isEmptyInstance() {
         }
 
         /**
-         * @return true if the Throwable this instance came from was not null and contained a message, otherwise false
+         * @return true, if the Throwable this instance came from was not null and contained a message, otherwise false
          */
         public boolean hasMessage() {
             return isNotBlank(message);
         }
 
         /**
-         * @return true if the Throwable this instance came from was not null and had a cause, otherwise false
+         * @return true, if the Throwable this instance came from was not null and had a cause, otherwise false
          */
         public boolean hasCause() {
             return nonNull(cause);

src/main/java/org/kiwiproject/base/process/ProcessHelper.java

@@ -172,7 +172,7 @@ public List<String> pgrepList(String user, String commandLine) {
      * process id (pid) and the matched command line.
      *
      * @param commandLine the full command line to match
-     * @return a list of {@link Pair} objects; each pair contains the pid as a Long and the associated full command
+     * @return a list of {@link Pair} objects; each pair contains the pid as a {@code Long} and the associated full command
      * @see Processes#pgrepParsedList(String)
      * @see Processes#wasPgrepFlagsCheckSuccessful()
      * @see Processes#getPgrepFlags()
@@ -187,7 +187,7 @@ public List<Pair<Long, String>> pgrepParsedList(String commandLine) {
      *
      * @param user        the OS user (passed to the {@code -u} option)
      * @param commandLine the full command line to match
-     * @return a list of {@link Pair} objects; each pair contains the pid as a Long and the associated full command
+     * @return a list of {@link Pair} objects; each pair contains the pid as a {@code Long} and the associated full command
      * @see Processes#pgrepParsedList(String, String)
      * @see Processes#wasPgrepFlagsCheckSuccessful()
      * @see Processes#getPgrepFlags()
@@ -232,7 +232,7 @@ public int kill(long processId, KillSignal signal, long timeout, TimeUnit unit,
      * @param action    the {@link KillTimeoutAction} to take if the process doesn't terminate within the allotted time
      * @return the exit code from the {@code kill} command, or {@code -1} if {@code action} is
      * {@link KillTimeoutAction#NO_OP} and the kill command times out
-     * @throws UncheckedIOException if an I/O error occurs killing the process
+     * @throws UncheckedIOException if an I/O error occurs while killing the process
      * @see Processes#kill(long, String, KillTimeoutAction)
      */
     public int kill(long processId, String signal, KillTimeoutAction action) {
@@ -249,7 +249,7 @@ public int kill(long processId, String signal, KillTimeoutAction action) {
      * @param action    the {@link KillTimeoutAction} to take if the process doesn't terminate within the allotted time
      * @return the exit code from the {@code kill} command, or {@code -1} if {@code action} is
      * {@link KillTimeoutAction#NO_OP} and the kill command times out
-     * @throws UncheckedIOException if an I/O error occurs killing the process
+     * @throws UncheckedIOException if an I/O error occurs while killing the process
      * @see Processes#kill(long, String, long, TimeUnit, KillTimeoutAction)
      */
     public int kill(long processId, String signal, long timeout, TimeUnit unit, KillTimeoutAction action) {

src/main/java/org/kiwiproject/base/process/Processes.java

@@ -67,7 +67,7 @@ public class Processes {
 
     /**
      * The command flags to use with the {@code pgrep} command for matching and printing the full command line.
-     * For example, to find the "sleep 25" process with pid 32332 we want pgrep to return results in the
+     * For example, to find the "sleep 25" process with pid 32332, we want pgrep to return results in the
      * format: "[pid] [full command]". For this example the expected result is: {@code 32332 sleep 25}.
      * <p>
      * However, there are differences in pgrep command line arguments between BSD-based systems (including macOS) and
@@ -179,7 +179,7 @@ static void logPgrepFlagWarnings() {
      * Use this method to determine if calling any of the pgrep methods in this class will work as expected.
      *
      * @return true if the pgrep check to determine the flags to use for full command matching was successful; false
-     * otherwise. If false you should NOT use any of the pgrep methods.
+     * otherwise. If false, you should NOT use any of the pgrep methods.
      * @see #getPgrepFlags()
      */
     public static boolean wasPgrepFlagsCheckSuccessful() {
@@ -225,7 +225,7 @@ public static long processId(Process process) {
      * @implNote the {@link Process#pid()} method says it can throw {@link UnsupportedOperationException} if the
      * "implementation does not support this operation" but does not specify under what circumstances that can
      * happen, and I have not been able to find this information using Google, Bing, or DuckDuckGo. This method
-     * logs a warning along with the exception, so if this occurs check your logs for the possible reason.
+     * logs a warning along with the exception, so if this occurs, check your logs for a possible reason.
      */
     public static OptionalLong processIdOrEmpty(Process process) {
         checkArgumentNotNull(process);
@@ -472,7 +472,7 @@ public static List<String> pgrepList(String user, String commandLine) {
      * process id (pid) and the matched command line.
      *
      * @param commandLine the full command line to match
-     * @return a list of {@link Pair} objects; each pair contains the pid as a Long and the associated full command
+     * @return a list of {@link Pair} objects; each pair contains the pid as a {@code Long} and the associated full command
      * @see #pgrepParsedList(String, String)
      * @see #wasPgrepFlagsCheckSuccessful()
      * @see #getPgrepFlags()
@@ -487,7 +487,7 @@ public static List<Pair<Long, String>> pgrepParsedList(String commandLine) {
      *
      * @param user        the OS user (passed to the {@code -u} option)
      * @param commandLine the full command line to match
-     * @return a list of {@link Pair} objects; each pair contains the pid as a Long and the associated full command
+     * @return a list of {@link Pair} objects; each pair contains the pid as a {@code Long} and the associated full command
      * @see #wasPgrepFlagsCheckSuccessful()
      * @see #getPgrepFlags()
      */
@@ -558,7 +558,7 @@ public static int kill(long processId, KillSignal signal, KillTimeoutAction acti
      * @param action    the {@link KillTimeoutAction} to take if the process doesn't terminate within the allotted time
      * @return the exit code from the {@code kill} command, or {@code -1} if {@code action} is
      * {@link KillTimeoutAction#NO_OP} and the kill command times out
-     * @throws UncheckedIOException if an I/O error occurs killing the process
+     * @throws UncheckedIOException if an I/O error occurs while killing the process
      */
     public static int kill(long processId, String signal, KillTimeoutAction action) {
         return kill(processId, signal, DEFAULT_KILL_TIMEOUT_SECONDS, TimeUnit.SECONDS, action);
@@ -589,7 +589,7 @@ public static int kill(long processId, KillSignal signal, long timeout, TimeUnit
      * @param action    the {@link KillTimeoutAction} to take if the process doesn't terminate within the allotted time
      * @return the exit code from the {@code kill} command, or {@code -1} if {@code action} is
      * {@link KillTimeoutAction#NO_OP} and the kill command times out
-     * @throws UncheckedIOException if an I/O error occurs killing the process
+     * @throws UncheckedIOException if an I/O error occurs while killing the process
      */
     public static int kill(long processId, String signal, long timeout, TimeUnit unit, KillTimeoutAction action) {
         try {

src/main/java/org/kiwiproject/collect/KiwiStreams.java

@@ -53,7 +53,7 @@ public static <T> Optional<T> findFirst(Stream<?> stream, Class<T> typeToFind, P
      * Normally you must hard code the type of stream directly in the code using either
      * {@link Collection#stream()} or {@link Collection#parallelStream()}. This method
      * provides a simple way to determine how to process a stream at runtime, for
-     * example based on number of elements or type of algorithm.
+     * example, based on number of elements or type of algorithm.
      *
      * @param <T> the type of collection elements
      * @param collection the collection to stream

src/main/java/org/kiwiproject/jaxrs/KiwiStandardResponses.java

@@ -33,7 +33,7 @@
  * by various people and analysis tools such as IntelliJ's inspections, Sonar, etc. However, we also like to return
  * {@link Optional} from data access code (e.g. a DAO "findById" method where the object might not exist if it was
  * recently deleted). In such cases, we can simply take the Optional returned by those finder methods and pass them
- * directly to the utilities provided here without needing to call additional methods, for example without needing to
+ * directly to the utilities provided here without needing to call additional methods, for example, without needing to
  * call {@code orElse(null)}. So, we acknowledge that it is generally not good to accept {@link Optional} arguments,
  * but we're trading off convenience in this class against "generally accepted" practice.
  * @see KiwiResources
@@ -49,7 +49,7 @@ public class KiwiStandardResponses {
      * and value.
      *
      * @param identifierField the field which identifies the entity being looked up, e.g. "id"
-     * @param identifier      the value of the identifier field, e.g. 42  the value of the identifier field, e.g. 42
+     * @param identifier      the value of the identifier field, e.g., 42 the value of the identifier field, e.g., 42
      * @param entity          the entity or null
      * @param entityType      the entity type
      * @param <T>             the entity type
@@ -73,7 +73,7 @@ public static <T> Response standardGetResponse(String identifierField,
      * and value.
      *
      * @param identifierField the field which identifies the entity being looked up, e.g. "id"
-     * @param identifier      the value of the identifier field, e.g. 42
+     * @param identifier      the value of the identifier field, e.g., 42
      * @param entity          an Optional that may or may not contain an entity
      * @param entityType      the entity type
      * @param <T>             the entity type
@@ -91,7 +91,7 @@ public static <T> Response standardGetResponse(String identifierField,
      * a message stating that the entity was not found using the given identifier field and value.
      *
      * @param identifierField the field which identifies the entity being looked up, e.g. "id"
-     * @param identifier      the value of the identifier field, e.g. 42
+     * @param identifier      the value of the identifier field, e.g., 42
      * @param entity          the entity or null
      * @param <T>             the entity type
      * @return a 200 or 404 response with {@code application/json} content type
@@ -112,7 +112,7 @@ public static <T> Response standardGetResponse(String identifierField,
      * a message stating that the entity was not found using the given identifier field and value.
      *
      * @param identifierField the field which identifies the entity being looked up, e.g. "id"
-     * @param identifier      the value of the identifier field, e.g. 42
+     * @param identifier      the value of the identifier field, e.g., 42
      * @param entity          an Optional that may or may not contain an entity
      * @param <T>             the entity type
      * @return a 200 or 404 response with {@code application/json} content type

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

@@ -22,9 +22,9 @@
  * <p>
  * Note that jackson-core and jackson-databind must be available at runtime.
  *
- * @implNote Currently the in-memory map will continue to grow unbounded. In the expected scenario, unknown properties
+ * @implNote Currently, the in-memory map will continue to grow unbounded. In the expected scenario, unknown properties
  * will be relatively rare, so we don't expect huge numbers of them. In addition, only unique unknown properties are
- * stored. The {@link #clearUnexpectedPaths()} method is provided to allow clearing all unexpected paths, for example
+ * stored. The {@link #clearUnexpectedPaths()} method is provided to allow clearing all unexpected paths, for example,
  * read the unexpected paths for analytics and then clear them.
  */
 @Slf4j
@@ -69,7 +69,7 @@ public boolean handleUnknownProperty(DeserializationContext ctxt,
 
         notifyConsumer(beanOrClass, path);
 
-        return true;  // to indicate the problem is "resolved"
+        return true;  // to indicate that the problem is "resolved"
     }
 
     private void notifyConsumer(Object beanOrClass, String path) {

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

@@ -49,7 +49,7 @@ public PropertyMaskingSafePropertyWriter(BeanPropertyWriter base, List<String> m
     }
 
     /**
-     * Construct new instance wrapping the given {@link BeanPropertyWriter} using the given
+     * Construct new instance wrapping the {@link BeanPropertyWriter} using the
      * {@link PropertyMaskingOptions} to define properties to be masked, as well as replacement text for
      * masked fields and serialization errors.
      *

src/main/java/org/kiwiproject/logging/LazyLogParameterSupplier.java

@@ -8,14 +8,14 @@
 import java.util.function.Supplier;
 
 /**
- * Provides lazy evaluation of one or more replacement parameters in a logging statement, for example when
+ * Provides lazy evaluation of one or more replacement parameters in a logging statement, for example, when
  * using SLF4J. This is useful when one or more values might be relatively expensive to compute, such as
  * serializing an object to JSON for DEBUG logging but not wanting to incur to JSON serialization cost at
  * higher log levels.
  * <p>
- * While many log frameworks now provide a way to pass a {@link Supplier} as an argument, not all do (e.g. SLF4J
- * version 1.7.x and earlier) and not all provide as much flexibility as you might want in order to mix and match
- * lazy and non-lazy arguments. This simple class lets you mix and match lazy and non-lazy parameters whether the
+ * While many log frameworks now provide a way to pass a {@link Supplier} as an argument, not all do (e.g., SLF4J
+ * version 1.7.x and earlier), and not all provide as much flexibility as you might want to mix and match
+ * lazy and non-lazy arguments. This class lets you mix and match lazy and non-lazy parameters whether the
  * logging API supports this or not.
  * <p>
  * To use, just statically import methods from {@link LazyLogParameterSupplier} and use them to wrap one or more
@@ -57,7 +57,7 @@ public class LazyLogParameterSupplier {
      * LOG.debug("Foo JSON with id {} is: {}", foo.getId(), lazy(foo::toJson));
      * </pre>
      *
-     * @param original supplier of a replacement value that might be expensive to compute, e.g. serialize an
+     * @param original supplier of a replacement value, which might be expensive to compute, e.g., serialize an
      *                 object to JSON
      * @return a {@link Supplier} that wraps {@code original}
      */

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

@@ -544,7 +544,7 @@ public static Optional<String> extractSubDomainNameFrom(String url) {
      * Searches the {@code commaDelimitedUrls} for its domains, and if found, replaces all entries with
      * {@code replacementDomain}. The {@code commaDelimitedUrls} can be a standalone URL.
      *
-     * @param commaDelimitedUrls the comma delimited URLs to search
+     * @param commaDelimitedUrls the comma-delimited URLs to search
      * @param replacementDomain  the domain to replace if found
      * @return the updated comma-delimited URLs if a domain is found, otherwise {@code commaDelimitedUrls} unchanged
      * @implNote This method assumes that the domains are the same for all URLs in the {@code commaDelimitedUrls}; it only

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

@@ -41,7 +41,7 @@ public boolean isPortAvailable(int port) {
     }
 
     /**
-     * Find the first open port starting at the given port inclusive, i.e. if {@code port} is 1024 then it is the first
+     * Find the first open port starting at the given port inclusive, i.e., if {@code port} is 1024 then it is the first
      * port checked. If no available port is found, return an empty {@link OptionalInt}.
      *
      * @param port the port to start from
@@ -58,7 +58,7 @@ public OptionalInt findFirstOpenPortFrom(int port) {
     }
 
     /**
-     * Find the first open port above the given port (i.e. if port is 1024 then the first port to be
+     * Find the first open port above the given port (i.e., if port is 1024 then the first port to be
      * checked will be 1025). If no available port is found, return an empty {@link OptionalInt}.
      *
      * @param port the port to check above

src/main/java/org/kiwiproject/search/PaginatedResult.java

@@ -1,7 +1,7 @@
 package org.kiwiproject.search;
 
 /**
- * Simple interface defining basic pagination for any kind of search, e.g. a database query, SOLR search, etc.
+ * Simple interface defining basic pagination for any kind of search, e.g., a database query, SOLR search, etc.
  */
 public interface PaginatedResult {
 
@@ -14,7 +14,7 @@ public interface PaginatedResult {
 
     /**
      * The page number of this result. Can be used in both zero- and one-based page numbering schemes as long
-     * as it is used consistently, e.g. the server and clients are both using one-based page numbering.
+     * as it is used consistently, e.g., the server and clients are both using one-based page numbering.
      *
      * @return the page number
      */

src/main/java/org/kiwiproject/spring/context/MongoRepositoryContext.java

@@ -113,7 +113,7 @@ public void attachListeners(ApplicationListener<?>... listeners) {
     /**
      * Convenience method to initialize a new {@link MongoTemplate} from the given MongoDB connection string.
      * <p>
-     * The returned instance is configured with write concern set to {@link WriteConcern#ACKNOWLEDGED}.
+     * The returned instance is configured with the write-concern set to {@link WriteConcern#ACKNOWLEDGED}.
      * <p>
      * This method also registers
      * {@link org.kiwiproject.spring.data.KiwiMongoConverters.BsonUndefinedToNullStringConverter BsonUndefinedToNullStringConverter}