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

… 2 (#1186)

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

@@ -53,11 +53,11 @@
     String[] replacedBy() default "";
 
     /**
-     * The issue number or other reference or descriptor which caused or is related to the deprecation, if any.
+     * The issue number or another reference or descriptor which caused or is related to the deprecation, if any.
      * <p>
      * For example, one or more JIRA issue numbers.
      *
-     * @return a reference to an issue, ticket, or other descriptor
+     * @return a reference to an issue, ticket, or another descriptor
      */
     String[] reference() default "";
 

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

@@ -5,7 +5,7 @@
 
 /**
  * {@link Double} utilities. Mainly wrappers around existing method in {@link Double} and {@link DoubleMath} that
- * are (in our opinion anyway) easier to work with or read the code, e.g. return a boolean for comparisons instead
+ * are (in our opinion anyway) easier to work with or read the code, e.g., return a boolean for comparisons instead
  * of an int.
  */
 @UtilityClass

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

@@ -49,7 +49,7 @@ public String number() {
     }
 
     /**
-     * Given a signal, prepend a leading dash if necessary, e.g. change "9" into "-9".
+     * Given a signal, prepend a leading dash if necessary, e.g., change "9" into "-9".
      *
      * @param signal the signal to modify
      * @return the possibly modified signal with a leading dash

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

@@ -10,7 +10,7 @@
 public enum KillTimeoutAction {
 
     /**
-     * The process will be forced killed (e.g. like a {@code kill -9}) after timeout
+     * The process will be forced killed (e.g., like a {@code kill -9}) after timeout
      */
     FORCE_KILL,
 

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

@@ -24,7 +24,7 @@ public class KiwiArrays {
      *
      * @param items the array
      * @param <T>   the type of items in the array
-     * @return {@code true} if array is null or empty; {@code false} otherwise
+     * @return {@code true} if the array is null or empty; {@code false} otherwise
      */
     public static <T> boolean isNullOrEmpty(T[] items) {
         return items == null || items.length == 0;
@@ -46,7 +46,7 @@ public static <T> boolean isNotNullOrEmpty(T[] items) {
      *
      * @param items the array
      * @param <T>   the type of items in the array
-     * @return {@code true} if array is non-null and has exactly one item; {@code false} otherwise
+     * @return {@code true} if the array is non-null and has exactly one item; {@code false} otherwise
      */
     public static <T> boolean hasOneElement(T[] items) {
         return nonNull(items) && items.length == 1;
@@ -100,12 +100,12 @@ public static <T> T first(T[] items) {
     }
 
     /**
-     * Returns an {@link Optional} containing the first element in specified array of items, or an empty optional
+     * Returns an {@link Optional} containing the first element in the specified array of items, or an empty optional
      * if the array is null or empty.
      *
      * @param items the array
      * @param <T>   the type of items in the array
-     * @return Optional containing first element if exists, otherwise Optional.empty()
+     * @return Optional containing the first element if exists, otherwise Optional.empty()
      */
     public static <T> Optional<T> firstIfPresent(T[] items) {
         return isNotNullOrEmpty(items) ? Optional.of(first(items)) : Optional.empty();
@@ -206,7 +206,7 @@ public static <T> T last(T[] items) {
     }
 
     /**
-     * Returns an {@link Optional} containing the last element in specified array of items, or an empty optional
+     * Returns an {@link Optional} containing the last element in the specified array of items, or an empty optional
      * if the array is null or empty.
      *
      * @param items the array
@@ -255,7 +255,7 @@ public static <T> T[] distinct(T[] collection, Class<T> arrayType) {
      * @param <T>        the type of items in the collection
      * @return a new array with only unique elements or null.
      */
-    @SuppressWarnings({"unchecked", "java:S1168"}) //Ignoring Sonar warning to return empty array since this method's name says it will return null
+    @SuppressWarnings({"unchecked", "java:S1168"}) //Ignoring Sonar warning to return an empty array since this method's name says it will return null
     public static <T> T[] distinctOrNull(T[] collection, Class<T> arrayType) {
         if (isNull(collection)) {
             return null;
@@ -267,8 +267,9 @@ public static <T> T[] distinctOrNull(T[] collection, Class<T> arrayType) {
     }
 
     /**
-     * Returns a new array with the same elements and the same size as the original, however the initial position in the array
-     * is now the element specified by the "startOffset" and the array wraps around through the contents to end with "startOffset" - 1
+     * Returns a new array with the same elements and the same size as the original.
+     * However, the initial position in the array is now the element specified by the "startOffset"
+     * and the array wraps around through the contents to end with ("startOffset" - 1).
      *
      * @param input       the original array
      * @param startOffset the desired offset to start the new array

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

@@ -25,7 +25,7 @@ public class KiwiCollections {
      *
      * @param collection the collection
      * @param <T>        the type of items in the collection
-     * @return {@code true} if collection is null or empty; {@code false} otherwise
+     * @return {@code true} if the collection is null or empty; {@code false} otherwise
      */
     public static <T> boolean isNullOrEmpty(Collection<T> collection) {
         return collection == null || collection.isEmpty();
@@ -36,7 +36,7 @@ public static <T> boolean isNullOrEmpty(Collection<T> collection) {
      *
      * @param collection the collection
      * @param <T>        the type of items in the collection
-     * @return {@code true} if collection is neither null nor empty; {@code false} otherwise
+     * @return {@code true} if the collection is neither null nor empty; {@code false} otherwise
      */
     public static <T> boolean isNotNullOrEmpty(Collection<T> collection) {
         return !isNullOrEmpty(collection);
@@ -47,7 +47,7 @@ public static <T> boolean isNotNullOrEmpty(Collection<T> collection) {
      *
      * @param collection the collection
      * @param <T>        the type of items in the collection
-     * @return {@code true} if collection is non-null and has exactly one item; {@code false}
+     * @return {@code true} if the collection is non-null and has exactly one item; {@code false}
      */
     public static <T> boolean hasOneElement(Collection<T> collection) {
         return nonNull(collection) && collection.size() == 1;
@@ -59,7 +59,7 @@ public static <T> boolean hasOneElement(Collection<T> collection) {
      *
      * @param sequencedCollection the sequenced collection
      * @param <T>                 the type of elements in the collection
-     * @return {@link Optional} containing first element if exists, otherwise Optional.empty()
+     * @return {@link Optional} containing the first element if exists, otherwise Optional.empty()
      * @throws IllegalArgumentException if sequencedCollection is not a sequenced collection
      */
     public static <T> Optional<T> firstIfPresent(Collection<T> sequencedCollection) {

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

@@ -67,7 +67,7 @@ public static <E extends Enum<E>> Collector<E, EnumSet<E>, EnumSet<E>> toEnumSet
      * @param valueMapper a mapping function to produce values
      * @param <T>         the type of the input elements
      * @param <K>         the output type of the key mapping function
-     * @param <U>         the outptu type of the value mapping function
+     * @param <U>         the output type of the value mapping function
      * @return a {@link Collector} which collects elements into an {@link java.util.EnumMap} whose keys
      * are the result of applying key and value mapping functions.
      */
@@ -86,7 +86,7 @@ public static <E extends Enum<E>> Collector<E, EnumSet<E>, EnumSet<E>> toEnumSet
     }
 
     /**
-     * Returns a {@link Collector} that collects intoa {@link LinkedHashMap}.
+     * Returns a {@link Collector} that collects into a {@link LinkedHashMap}.
      *
      * @param keyMapper   a mapping function to produce keys
      * @param valueMapper a mapping function to produce values
@@ -116,8 +116,8 @@ public static <E extends Enum<E>> Collector<E, EnumSet<E>, EnumSet<E>> toEnumSet
      * @param u1 the first value supplied to the merge function
      * @param u2 the second value supplied to the merge function
      * @return a new {@link IllegalStateException} object
-     * @implNote There is not an easy way to obtain the actual duplicate key here, since the merge function is a
-     * {@link java.util.function.BinaryOperator} that accepts the two values needing to be merged. So unfortunately
+     * @implNote There is not an easy way to get the actual duplicate key here, since the merge function is a
+     * {@link java.util.function.BinaryOperator} that accepts the two values needing to be merged. So unfortunately,
      * the best we can easily do is report the values attempting to be merged, and let the person doing the
      * investigation hopefully backtrack to the duplicate key.
      */

src/main/java/org/kiwiproject/dropwizard/lifecycle/KiwiDropwizardLifecycles.java

@@ -50,7 +50,7 @@ public void stop() {
      * <p>
      * Useful when you have some external object that has a start method, but you don't want to clutter your
      * code by creating an anonymous inner class just to specify the start action. For example, if you have
-     * a monitoring class that needs to start when the application starts, you can ensure that happens
+     * a monitoring class that needs to start when the application starts, you can ensure that it happens
      * using code like:
      * <p>
      * {@code KiwiDropwizardLifecycles.manage(lifecycle, () -> monitor.start());}

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

@@ -59,7 +59,7 @@ public boolean isEnabled(int level) {
      * Log the given message at the given level.
      * <p>
      * If provided an invalid level, a message will be logged about the invalid level, along with the given message,
-     * at the SLF4J ERROR level. This is intended to provide both information about the problem and provide
+     * at the SLF4J ERROR level. This is intended to provide information about the problem and provide
      * the original message, rather than throwing an exception or suppressing the message.
      *
      * @param level   one of the public constants in {@link com.jcraft.jsch.Logger}

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

@@ -61,12 +61,12 @@
  * to find the first value in an array property {@code luckyNumbers}, the path is {@code luckyNumbers.[0]}.
  * Similarly, to find the 13th lucky number the path is {@code luckyNumbers.[12]}.
  * <p>
- * Paths for nested JSON objects  follow the syntax {@code objectName.propertyName}; for JSON that contains a
+ * Paths for nested JSON objects follow the syntax {@code objectName.propertyName}; for JSON that contains a
  * {@code homeAddress} object that contains a {@code zipCode}, the path is {@code homeAddress.zipCode}.
  *
  * @implNote This uses Jackson to perform JSON mapping to and from objects, so Jackson will need to be available
  * at runtime. In addition, if you use the no-args constructor, this relies on Dropwizard's {@link Jackson} class
- * which does a bunch of configuration on the default Jackson {@link ObjectMapper}. So you would also need
+ * which does a bunch of configuration on the default Jackson {@link ObjectMapper}. So, you would need
  * Dropwizard available at runtime as well, specifically {@code dropwizard-jackson}.
  */
 @Slf4j
@@ -179,7 +179,7 @@ public static ObjectMapper configureForMillisecondDateTimestamps(ObjectMapper ma
 
     /**
      * Provides direct access to the underlying object mapper. Care should be taken when accessing the
-     * {@link ObjectMapper} directly, particularly if any changes are made to how objects are serialized/de-serialized.
+     * {@link ObjectMapper} directly, particularly if any changes are made to how objects are serialized/deserialized.
      *
      * @return the object mapper; any changes made to it will potentially change the behavior of this JsonHelper instance
      */
@@ -420,7 +420,7 @@ public <T> T toObject(@Nullable String json, TypeReference<T> targetType) {
      * input JSON is blank
      *
      * @param json        the JSON content
-     * @param targetClass the  type of object to convert into
+     * @param targetClass the type of object to convert into
      * @param <T>         the object type
      * @return an Optional that may contain a converted object
      */
@@ -500,7 +500,7 @@ public Map<String, String> toFlatMap(@Nullable Object object) {
     /**
      * Parse the given object as JSON, then flatten all its properties to a map whose keys are the object property
      * names and whose values are converted to the given {@code valueClass} type. In practice, this will often
-     * just be {@code Object.class} but could be a more specific type, e.g. if you have a map containing student
+     * just be {@code Object.class} but could be a more specific type, e.g., if you have a map containing student
      * names and grades then the values could all be of type {@code Double}.
      * <p>
      * This also flattens arrays/collections and maps. Flattened arrays use the following syntax:
@@ -794,7 +794,7 @@ private static Pair<ContainerNode<?>, JsonNode> getPathNode(JsonNode root, Strin
      * The returned map of differences has keys that are the properties that are different. The map values are
      * the values for the corresponding key/property in the first and second objects, respectively.
      * <p>
-     * NOTE: This is an expensive operation so be careful of using it in production code in areas where performance
+     * NOTE: This is an expensive operation, so be careful of using it in production code in areas where performance
      * is critical.
      *
      * @param object1      the first object
@@ -811,9 +811,9 @@ public Map<String, List<String>> jsonDiff(@Nullable Object object1, @Nullable Ob
      * perspective of the first object in the given list.
      * <p>
      * The returned map of differences has keys that are the properties that are different. The map values are
-     * the values for the corresponding key/property in the first and subsequent objects, respectively.
+     * the values for the corresponding key/property in the first and later objects, respectively.
      * <p>
-     * NOTE: This is an expensive operation so be careful of using it in production code in areas where performance
+     * NOTE: This is an expensive operation, so be careful of using it in production code in areas where performance
      * is critical.
      *
      * @param objectList   the list of objects to compare; the first object is the reference object
@@ -833,9 +833,9 @@ public Map<String, List<String>> jsonDiff(@NonNull List<Object> objectList, Stri
      * perspective of the first JSON object in the given list.
      * <p>
      * The returned map of differences has keys that are the properties that are different. The map values are
-     * the values for the corresponding key/property in the first and subsequent objects, respectively.
+     * the values for the corresponding key/property in the first and later objects, respectively.
      * <p>
-     * NOTE: This is an expensive operation so be careful of using it in production code in areas where performance
+     * NOTE: This is an expensive operation, so be careful of using it in production code in areas where performance
      * is critical.
      *
      * @param listOfJson the list of JSON objects to compare
@@ -855,7 +855,7 @@ public Map<String, List<String>> jsonDiff(@NonNull List<String> listOfJson) {
                     if (isNotNullOrEmpty(results)) {
                         var match = first(results);
                         if (!results.stream().allMatch(s -> StringUtils.equals(s, match))) {
-                            resultMap.put(path, new ArrayList<>(results));  // must use mutable list to handle nulls
+                            resultMap.put(path, new ArrayList<>(results));  // must use a mutable list to handle nulls
                         }
                     }
                 });
@@ -1051,7 +1051,7 @@ private static void mergeOrReplaceArray(String fieldName,
 
     /**
      * Parse the given object as JSON, and return a list containing the property paths in the object. The paths
-     * include arrays, collections and maps.
+     * include arrays, collections, and maps.
      * <p>
      * For details on the property path syntax, see {@link #toFlatMap(Object, Class)}.
      *
@@ -1105,7 +1105,7 @@ private static void appendArrayNodePaths(List<String> paths, JsonNode child, Str
             var currentIndex = index.getAndIncrement();
             var currentPath = parentPrefix + f("[%s]", currentIndex);
             if (!arrayElement.isContainerNode()) {
-                // not a container (e.g. object or array), so add the path
+                // not a container (e.g., object or array), so add the path
                 paths.add(currentPath);
             }
             appendChildPaths(paths, arrayElement, currentPath + ".");

src/main/java/org/kiwiproject/security/KeyStoreType.java

@@ -7,10 +7,10 @@
  * {@link java.security.KeyStore#getInstance(String)}.
  *
  * @implNote These are from the Java 11 documentation, specifically from "Java Security Standard Algorithm Names".
- * Also note that while that document lists the types in lower case, the JDK actually uppercases the protocol so using
- * the actual uppercase enum names here works (until and unless they add new protocols that contain things like dots
- * or underscores or other such characters that aren't allowed as enum names). In any case, the types are
- * case-insensitive in the JDK. See the {@link java.security.Provider} class, in the constructor of the nested
+ * Also note that while that document lists the types in lower case, the JDK actually uppercases the protocol, so using
+ * the actual uppercase enum names here works. At least, it works until and unless they add new protocols that contain
+ * things like dots or underscores or other such characters that aren't allowed as enum names). In any case, the types
+ * are case-insensitive in the JDK. See the {@link java.security.Provider} class, in the constructor of the nested
  * (and private) {@code ServiceKey} class where the following LOC resides:
  * {@code algorithm = algorithm.toUpperCase(ENGLISH);}
  */

src/main/java/org/kiwiproject/time/KiwiDateTimeConverters.java

@@ -24,7 +24,7 @@
  * <p>
  * All methods throw {@link IllegalArgumentException} if null values are passed into them.
  *
- * @implNote {@link Date}, according to its JavaDoc, is "intended to reflect coordinated universal time (UTC)"
+ * @implNote {@link Date}, according to its Javadoc, is "intended to reflect coordinated universal time (UTC)"
  * though "it may not do so exactly". The utilities in this class convert arguments to UTC before converting
  * to {@link Date} in order to reflect that intention.
  */

src/main/java/org/kiwiproject/time/KiwiDateTimeFormatters.java

@@ -21,7 +21,7 @@
  * we decided to split them into separate utilities. So if you are looking for utilities to parse strings into
  * date/time objects, see {@link KiwiDateTimeParsers}.
  * <p>
- * None of these are difficult to implement, but if you are constantly doing them, the time and code adds up
+ * None of these are difficult to implement, but if you are constantly doing them, the time and code necessary adds up
  * over time.
  * <p>
  * All methods throw {@link IllegalArgumentException} if {@code null} arguments are passed to them.

src/main/java/org/kiwiproject/time/KiwiDateTimeParsers.java

@@ -23,7 +23,7 @@
  * we decided to split them into separate utilities. So if you are looking for utilities to format date/time objects
  * into strings, see {@link KiwiDateTimeFormatters}.
  * <p>
- * None of these are difficult to implement, but if you are constantly doing them, the time and code adds up
+ * None of these are difficult to implement, but if you are constantly doing them, the time and code necessary adds up
  * over time.
  * <p>
  * All methods throw {@link IllegalArgumentException} if {@code null} or blank arguments are passed to them.