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

… 4 (#1188)

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

@@ -36,7 +36,7 @@ public static <T> T firstNonNullOrNull(T first, T second, T... rest) {
      * @param second the second object supplier
      * @param rest   zero or more additional object suppliers
      * @param <T>    the type of objects
-     * @return the first non-null supplied object or null if all suppliers return null
+     * @return the first non-null object supplied, or null if all suppliers return null
      * @implNote once a non-null object is supplied, no further suppliers are called
      */
     @SafeVarargs

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

@@ -34,7 +34,7 @@
  * @implNote Several methods in this class use Lombok {@link lombok.SneakyThrows} so that they do not need to declare
  * that they throw {@code Exception}s of type T, <em>for the case that T is a checked exception</em>. Read more details about
  * how this works in {@link lombok.SneakyThrows}. Most notably, this should give you more insight into how the JVM (versus
- * Java the language) actually work: <em>"The JVM does not check for the consistency of the checked exception system;
+ * Java the language) actually works: <em>"The JVM does not check for the consistency of the checked exception system;
  * javac does, and this annotation lets you opt out of its mechanism."</em>
  */
 @UtilityClass
@@ -601,7 +601,7 @@ public static <K, V> void checkArgumentNotEmpty(Map<K, V> map,
 
     /**
      * Ensures that a collection of items has an even count, throwing an {@link IllegalArgumentException} if
-     * items is null or there is an odd number of items.
+     * {@code items} is null or there is an odd number of items.
      *
      * @param items items to count
      * @param <T>   the object type
@@ -614,7 +614,7 @@ public static <T> void checkEvenItemCount(T... items) {
 
     /**
      * Ensures that a collection of items has an even count, throwing an {@link IllegalArgumentException} if
-     * items is null or there is an odd number of items.
+     * {@code items} is null or there is an odd number of items.
      *
      * @param items items to count
      * @param <T>   the object type
@@ -678,7 +678,7 @@ public static <T> T requireNotNullElseGet(T obj, Supplier<? extends T> supplier)
      * Ensures int {@code value} is a positive number (greater than zero).
      *
      * @param value the value to check for positivity
-     * @throws IllegalStateException if the value is not positive (e.g. greater than zero)
+     * @throws IllegalStateException if the value is not positive (e.g., greater than zero)
      * @see Preconditions#checkState(boolean, Object)
      */
     public static void checkPositive(int value) {
@@ -690,7 +690,7 @@ public static void checkPositive(int value) {
      *
      * @param value        the value to check for positivity
      * @param errorMessage the error message to put in the exception if not positive
-     * @throws IllegalStateException if the value is not positive (e.g. greater than zero)
+     * @throws IllegalStateException if the value is not positive (e.g., greater than zero)
      * @see Preconditions#checkState(boolean, Object)
      */
     public static void checkPositive(int value, String errorMessage) {
@@ -704,7 +704,7 @@ public static void checkPositive(int value, String errorMessage) {
      * @param errorMessageTemplate a template for the exception message if value is not positive, according to how
      *                             {@link KiwiStrings#format(String, Object...)} handles placeholders
      * @param errorMessageArgs     the arguments to populate into the error message template
-     * @throws IllegalStateException if the value is not positive (e.g. greater than zero)
+     * @throws IllegalStateException if the value is not positive (e.g., greater than zero)
      * @see Preconditions#checkState(boolean, Object)
      */
     public static void checkPositive(int value, String errorMessageTemplate, Object... errorMessageArgs) {
@@ -717,7 +717,7 @@ public static void checkPositive(int value, String errorMessageTemplate, Object.
      * Ensures long {@code value} is a positive number (greater than zero).
      *
      * @param value the value to check for positivity
-     * @throws IllegalStateException if the value is not positive (e.g. greater than zero)
+     * @throws IllegalStateException if the value is not positive (e.g., greater than zero)
      * @see Preconditions#checkState(boolean, Object)
      */
     public static void checkPositive(long value) {
@@ -729,7 +729,7 @@ public static void checkPositive(long value) {
      *
      * @param value        the value to check for positivity
      * @param errorMessage the error message to put in the exception if not positive
-     * @throws IllegalStateException if the value is not positive (e.g. greater than zero)
+     * @throws IllegalStateException if the value is not positive (e.g., greater than zero)
      * @see Preconditions#checkState(boolean, Object)
      */
     public static void checkPositive(long value, String errorMessage) {
@@ -743,7 +743,7 @@ public static void checkPositive(long value, String errorMessage) {
      * @param errorMessageTemplate a template for the exception message if value is not positive, according to how
      *                             {@link KiwiStrings#format(String, Object...)} handles placeholders
      * @param errorMessageArgs     the arguments to be substituted into the message template
-     * @throws IllegalStateException if the value is not positive (e.g. greater than zero)
+     * @throws IllegalStateException if the value is not positive (e.g., greater than zero)
      * @see Preconditions#checkState(boolean, Object)
      */
     public static void checkPositive(long value, String errorMessageTemplate, Object... errorMessageArgs) {
@@ -768,7 +768,7 @@ public static void checkPositiveOrZero(int value) {
      *
      * @param value        the value to check for positivity
      * @param errorMessage the error message to put in the exception if not positive
-     * @throws IllegalStateException if the value is not positive (e.g. greater than zero)
+     * @throws IllegalStateException if the value is not positive (e.g., greater than zero)
      * @see Preconditions#checkState(boolean, Object)
      */
     public static void checkPositiveOrZero(int value, String errorMessage) {
@@ -782,7 +782,7 @@ public static void checkPositiveOrZero(int value, String errorMessage) {
      * @param errorMessageTemplate a template for the exception message if value is not zero or positive, according to how
      *                             {@link KiwiStrings#format(String, Object...)} handles placeholders
      * @param errorMessageArgs     the arguments to populate into the error message template
-     * @throws IllegalStateException if the value is not positive (e.g. greater than zero)
+     * @throws IllegalStateException if the value is not positive (e.g., greater than zero)
      * @see Preconditions#checkState(boolean, Object)
      */
     public static void checkPositiveOrZero(int value, String errorMessageTemplate, Object... errorMessageArgs) {
@@ -807,7 +807,7 @@ public static void checkPositiveOrZero(long value) {
      *
      * @param value        the value to check for positivity
      * @param errorMessage the error message to put in the exception if not positive
-     * @throws IllegalStateException if the value is not positive (e.g. greater than zero)
+     * @throws IllegalStateException if the value is not positive (e.g., greater than zero)
      * @see Preconditions#checkState(boolean, Object)
      */
     public static void checkPositiveOrZero(long value, String errorMessage) {
@@ -821,7 +821,7 @@ public static void checkPositiveOrZero(long value, String errorMessage) {
      * @param errorMessageTemplate a template for the exception message if value is not zero or positive, according to how
      *                             {@link KiwiStrings#format(String, Object...)} handles placeholders
      * @param errorMessageArgs     the arguments to populate into the error message template
-     * @throws IllegalStateException if the value is not positive (e.g. greater than zero)
+     * @throws IllegalStateException if the value is not positive (e.g., greater than zero)
      * @see Preconditions#checkState(boolean, Object)
      */
     public static void checkPositiveOrZero(long value, String errorMessageTemplate, Object... errorMessageArgs) {
@@ -848,7 +848,7 @@ public static int requirePositive(int value) {
      * @param value        the value to check for positivity
      * @param errorMessage the error message to put in the exception if not positive
      * @return the given value if positive
-     * @throws IllegalStateException if the value is not positive (e.g. greater than zero)
+     * @throws IllegalStateException if the value is not positive (e.g., greater than zero)
      * @see Preconditions#checkState(boolean, Object)
      */
     public static int requirePositive(int value, String errorMessage) {
@@ -864,7 +864,7 @@ public static int requirePositive(int value, String errorMessage) {
      *                             {@link KiwiStrings#format(String, Object...)} handles placeholders
      * @param errorMessageArgs     the arguments to populate into the error message template
      * @return the given value if positive
-     * @throws IllegalStateException if the value is not positive (e.g. greater than zero)
+     * @throws IllegalStateException if the value is not positive (e.g., greater than zero)
      * @see Preconditions#checkState(boolean, Object)
      */
     public static int requirePositive(int value, String errorMessageTemplate, Object... errorMessageArgs) {
@@ -890,7 +890,7 @@ public static long requirePositive(long value) {
      * @param value        the value to check for positivity
      * @param errorMessage the error message to put in the exception if not positive
      * @return the given value if positive
-     * @throws IllegalStateException if the value is not positive (e.g. greater than zero)
+     * @throws IllegalStateException if the value is not positive (e.g., greater than zero)
      * @see Preconditions#checkState(boolean, Object)
      */
     public static long requirePositive(long value, String errorMessage) {
@@ -906,7 +906,7 @@ public static long requirePositive(long value, String errorMessage) {
      *                             {@link KiwiStrings#format(String, Object...)} handles placeholders
      * @param errorMessageArgs     the arguments to populate into the error message template
      * @return the given value if positive
-     * @throws IllegalStateException if the value is not positive (e.g. greater than zero)
+     * @throws IllegalStateException if the value is not positive (e.g., greater than zero)
      * @see Preconditions#checkState(boolean, Object)
      */
     public static long requirePositive(long value, String errorMessageTemplate, Object... errorMessageArgs) {
@@ -919,7 +919,7 @@ public static long requirePositive(long value, String errorMessageTemplate, Obje
      *
      * @param value the value to check for positivity or zero
      * @return the given value if positive or zero
-     * @throws IllegalStateException if the value is not positive zero
+     * @throws IllegalStateException if the value is not positive or zero
      */
     public static int requirePositiveOrZero(int value) {
         checkPositiveOrZero(value);
@@ -932,7 +932,7 @@ public static int requirePositiveOrZero(int value) {
      * @param value        the value to check for positivity
      * @param errorMessage the error message to put in the exception if not positive
      * @return the given value if positive or zero
-     * @throws IllegalStateException if the value is not positive (e.g. greater than zero)
+     * @throws IllegalStateException if the value is not positive (e.g., greater than zero)
      * @see Preconditions#checkState(boolean, Object)
      */
     public static int requirePositiveOrZero(int value, String errorMessage) {
@@ -948,7 +948,7 @@ public static int requirePositiveOrZero(int value, String errorMessage) {
      *                             {@link KiwiStrings#format(String, Object...)} handles placeholders
      * @param errorMessageArgs     the arguments to populate into the error message template
      * @return the given value if positive or zero
-     * @throws IllegalStateException if the value is not positive (e.g. greater than zero)
+     * @throws IllegalStateException if the value is not positive (e.g., greater than zero)
      * @see Preconditions#checkState(boolean, Object)
      */
     public static int requirePositiveOrZero(int value, String errorMessageTemplate, Object... errorMessageArgs) {
@@ -961,7 +961,7 @@ public static int requirePositiveOrZero(int value, String errorMessageTemplate,
      *
      * @param value the value to check for positivity or zero
      * @return the given value if positive or zero
-     * @throws IllegalStateException if the value is not positive zero
+     * @throws IllegalStateException if the value is not positive or zero
      */
     public static long requirePositiveOrZero(long value) {
         checkPositiveOrZero(value);
@@ -974,7 +974,7 @@ public static long requirePositiveOrZero(long value) {
      * @param value        the value to check for positivity
      * @param errorMessage the error message to put in the exception if not positive
      * @return the given value if positive or zero
-     * @throws IllegalStateException if the value is not positive (e.g. greater than zero)
+     * @throws IllegalStateException if the value is not positive (e.g., greater than zero)
      * @see Preconditions#checkState(boolean, Object)
      */
     public static long requirePositiveOrZero(long value, String errorMessage) {
@@ -990,7 +990,7 @@ public static long requirePositiveOrZero(long value, String errorMessage) {
      *                             {@link KiwiStrings#format(String, Object...)} handles placeholders
      * @param errorMessageArgs     the arguments to populate into the error message template
      * @return the given value if positive or zero
-     * @throws IllegalStateException if the value is not positive (e.g. greater than zero)
+     * @throws IllegalStateException if the value is not positive (e.g., greater than zero)
      * @see Preconditions#checkState(boolean, Object)
      */
     public static long requirePositiveOrZero(long value, String errorMessageTemplate, Object... errorMessageArgs) {

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

@@ -9,7 +9,7 @@
 import java.util.OptionalLong;
 
 /**
- * Static utilities that operate on primitive values, and are not already provided by classes in Guava's
+ * Static utilities that operate on primitive values, and are not provided by classes in Guava's
  * {@link com.google.common.primitives} package.
  */
 @UtilityClass

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

@@ -21,7 +21,7 @@
 public class KiwiProperties {
 
     /**
-     * Crates a <i>mutable</i> {@link Properties} instance by parsing the items argument in pairs.
+     * Crates a <i>mutable</i> {@link Properties} instance by parsing the {@code items} argument in pairs.
      * The items argument contains keys and values in the form:
      * <p>
      * <i>key-1, value-1, key-2, value-2, ... , key-N, value-N</i>
@@ -41,7 +41,7 @@ public static Properties newProperties(Object... items) {
     }
 
     /**
-     * Creates a <i>mutable</i> {@link Properties} instance by parsing the items argument in pairs.
+     * Creates a <i>mutable</i> {@link Properties} instance by parsing the {@code items} argument in pairs.
      * The items argument contains keys and values in the form:
      * <p>
      * <i>key-1, value-1, key-2, value-2, ... , key-N, value-N</i>
@@ -58,7 +58,7 @@ public static Properties newProperties(String... items) {
     }
 
     /**
-     * Creates a <i>mutable</i> {@link Properties} instance by parsing the items argument in pairs from the list.
+     * Creates a <i>mutable</i> {@link Properties} instance by parsing the {@code items} argument in pairs from the list.
      *
      * @param items the items containing keys and values, in pairs
      * @return a new Properties instance with data from items
@@ -78,11 +78,11 @@ public static Properties newProperties(List<String> items) {
      * @return a new Properties instance with data from the map
      * @throws NullPointerException if any of the items is null
      * @implNote The reason this method restricts the map keys and values to strings is because Properties is derived
-     * from {@link java.util.Hashtable} and the JavaDoc states:
+     * from {@link java.util.Hashtable} and the Javadoc states:
      * "Because {@code Properties} inherits from {@code Hashtable}, the {@code put} and {@code putAll} methods can be
      * applied to a {@code Properties} object. Their use is strongly discouraged as they allow the caller to insert
      * entries whose keys or values are not {@code Strings}. The {@code setProperty} method should be used instead."
-     * This of course is simply poor design (they should have used composition and hidden the internal storage details
+     * This, of course, is simply poor design (they should have used composition and hidden the internal storage details
      * instead of extending Hashtable).
      */
     public static Properties newProperties(Map<String, String> map) {
@@ -94,17 +94,17 @@ public static Properties newProperties(Map<String, String> map) {
 
     /**
      * Creates a <i>mutable</i> {@link Properties} instance from each key/value pair list inside the outer list.
-     * The items argument must contain keys and values in teh form:
+     * The {@code items} argument must contain keys and values in teh form:
      * <p>
      * <i>[ [key-1, value-1], [key-2, value-2], ... , [key-N, value-N]</i>
      * </p>
      *
-     * @param items the items list containing a series of two-items key/value pair lists
+     * @param items a list containing a series of two-items key/value pair lists
      * @return a new Properties instance with data from items
      * @throws NullPointerException if any of the items is null
      * @throws IllegalArgumentException if any of the key/value pair lists do not have at least two elements
      * @implNote only the first and second elements of the key/value pair sub-lists are used when creating the
-     * Properties instance. Thus while it does not make much sense, this method will not throw an exception if the
+     * Properties instance. Thus, while it makes little sense, this method will not throw an exception if the
      * sub-lists contain more than two elements.
      */
     public static Properties newPropertiesFromStringPairs(List<List<String>> items) {

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

@@ -17,7 +17,7 @@ public class KiwiSets {
      *
      * @param set the set
      * @param <T> the type of items in the set
-     * @return {@code true} if set is null or empty; {@code false} otherwise
+     * @return {@code true} if {@code set} is null or empty; {@code false} otherwise
      */
     public static <T> boolean isNullOrEmpty(Set<T> set) {
         return set == null || set.isEmpty();
@@ -28,7 +28,7 @@ public static <T> boolean isNullOrEmpty(Set<T> set) {
      *
      * @param set the set
      * @param <T> the type of items in the set
-     * @return {@code true} if set is neither null nor empty; {@code false} otherwise
+     * @return {@code true} if {@code set} is neither null nor empty; {@code false} otherwise
      */
     public static <T> boolean isNotNullOrEmpty(Set<T> set) {
         return !isNullOrEmpty(set);
@@ -39,7 +39,7 @@ public static <T> boolean isNotNullOrEmpty(Set<T> set) {
      *
      * @param set the set
      * @param <T> the type of items in the set
-     * @return {@code true} if set is non-null and has exactly one item; {@code false}
+     * @return {@code true} if {@code set} is non-null and has exactly one item; {@code false}
      */
     public static <T> boolean hasOneElement(Set<T> set) {
         return nonNull(set) && set.size() == 1;