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

… 3 (#1187)

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

@@ -83,7 +83,7 @@ public static <E extends Enum<E>> boolean equals(Enum<E> enumValue, @Nullable Ch
      * @param <E> the enum type
      * @param enumValue the enum to use for the comparison
      * @param value the value to use for the comparison, may be null
-     * @return if the enum name equals the value in case-insensitive manner, false otherwise
+     * @return if the enum name equals the value in a case-insensitive manner, false otherwise
      */
     public static <E extends Enum<E>> boolean equalsIgnoreCase(Enum<E> enumValue, @Nullable CharSequence value) {
         checkEnumNotNull(enumValue);
@@ -96,7 +96,7 @@ private static <E extends Enum<E>> void checkEnumNotNull(Enum<E> enumValue) {
 
     /**
      * Compares the given enum's {@link Enum#name() name} with the given value for
-     * inverse equality, i.e. they are not equal.
+     * inverse equality, i.e., they are not equal.
      *
      * @param <E> the enum type
      * @param enumValue the enum to use for the comparison
@@ -109,12 +109,12 @@ public static <E extends Enum<E>> boolean notEquals(Enum<E> enumValue, @Nullable
 
     /**
      * Compares the given enum's {@link Enum#name() name} with the given value, ignoring case, for
-     * inverse equality, i.e. they are not equal.
+     * inverse equality, i.e., they are not equal.
      *
      * @param <E> the enum type
      * @param enumValue the enum to use for the comparison
      * @param value the value to use for the comparison, may be null
-     * @return true if the enum name does not equal the value in case-insensitive manner, false otherwise
+     * @return true if the enum name does not equal the value in a case-insensitive manner, false otherwise
      */
     public static <E extends Enum<E>> boolean notEqualsIgnoreCase(Enum<E> enumValue, @Nullable CharSequence value) {
         return !equalsIgnoreCase(enumValue, value);
@@ -141,7 +141,7 @@ public static <E extends Enum<E>> boolean equalsAny(@Nullable CharSequence value
      * @param <E> the enum type
      * @param value the value to use for the comparison, may be null
      * @param enumValues the enums to use for the comparison
-     * @return true if the value equals the name of the enums in case-insensitive manner, false otherwise
+     * @return true if the value equals the name of the enums in a case-insensitive manner, false otherwise
      */
     @SafeVarargs
     public static <E extends Enum<E>> boolean equalsAnyIgnoreCase(@Nullable CharSequence value,

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

@@ -17,8 +17,8 @@
 import java.util.concurrent.TimeUnit;
 
 /**
- * Interface that defines methods related to the external environment, for example getting the current time in
- * milliseconds, obtaining the process ID, and sleeping quietly for a specified time.
+ * Interface that defines methods related to the external environment, for example, getting the current time in
+ * milliseconds, getting the process ID, and sleeping quietly for a specified time.
  * <p>
  * The main advantage of this over simply using things like {@link System#currentTimeMillis()} is to allow for easier
  * testing. Since this is an interface, it can easily be replaced with a mock object in unit tests that deal with

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

@@ -24,7 +24,7 @@ public class KiwiIterators {
 
     /**
      * Returns a <em>thread-safe</em> iterator that cycles indefinitely over the elements of {@code iterable}, base
-     * on Guava's {@link com.google.common.collect.Iterables#cycle(Iterable)}. The differences from Guava is that the
+     * on Guava's {@link com.google.common.collect.Iterables#cycle(Iterable)}. The difference from Guava is that the
      * returned iterator provides thread-safety; makes an immutable copy of the provided iterable; and does not
      * support element removal regardless of whether the original iterable does.
      * <p>

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

@@ -25,7 +25,7 @@ public class KiwiLists {
      *
      * @param items the list
      * @param <T>   the type of items in the list
-     * @return {@code true} if list is null or empty; {@code false} otherwise
+     * @return {@code true} if {@code list} is null or empty; {@code false} otherwise
      */
     public static <T> boolean isNullOrEmpty(List<T> items) {
         return items == null || items.isEmpty();
@@ -47,7 +47,7 @@ public static <T> boolean isNotNullOrEmpty(List<T> items) {
      *
      * @param items the list
      * @param <T>   the type of items in the list
-     * @return {@code true} if list is non-null and has exactly one item; {@code false} otherwise
+     * @return {@code true} if {@code list} is non-null and has exactly one item; {@code false} otherwise
      */
     public static <T> boolean hasOneElement(List<T> items) {
         return nonNull(items) && items.size() == 1;
@@ -93,12 +93,12 @@ public static <T> T first(List<T> items) {
     }
 
     /**
-     * Returns an {@link Optional} containing the first element in specified list of items, or an empty optional
+     * Returns an {@link Optional} containing the first element in the specified list of items, or an empty optional
      * if the list is null or empty.
      *
      * @param items the list
      * @param <T>   the type of items in the list
-     * @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(List<T> items) {
         return isNotNullOrEmpty(items) ? Optional.of(first(items)) : Optional.empty();
@@ -199,7 +199,7 @@ public static <T> T last(List<T> items) {
     }
 
     /**
-     * Returns an {@link Optional} containing the last element in specified list of items, or an empty optional
+     * Returns an {@link Optional} containing the last element in the specified list of items, or an empty optional
      * if the list is null or empty.
      *
      * @param items the list
@@ -267,8 +267,8 @@ private static <T> List<T> distinctListFrom(Collection<T> collection) {
     }
 
     /**
-     * Returns a new list with the same elements and the same size as the original, however the initial position in the list
-     * is now the element specified by the "startOffset" and the list wraps around through the contents to end with "startOffset" - 1
+     * Returns a new list with the same elements and the same size as the original. However, the initial position in the list
+     * is now the element specified by the "startOffset" and the list wraps around through the contents to end with ("startOffset" - 1).
      *
      * @param input       the original list
      * @param startOffset the desired offset to start the new list

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

@@ -31,7 +31,7 @@ public class KiwiMaps {
      * @param map the map
      * @param <K> the type of the keys in the map
      * @param <V> the type of the values in the map
-     * @return {@code true} if map is null or empty; {@code false} otherwise
+     * @return {@code true} if {@code map} is null or empty; {@code false} otherwise
      */
     public static <K, V> boolean isNullOrEmpty(Map<K, V> map) {
         return map == null || map.isEmpty();
@@ -43,7 +43,7 @@ public static <K, V> boolean isNullOrEmpty(Map<K, V> map) {
      * @param map the map
      * @param <K> the type of the keys in the map
      * @param <V> the type of the values in the map
-     * @return {@code true} if map is neither null nor empty; {@code false} otherwise
+     * @return {@code true} if {@code map} is neither null nor empty; {@code false} otherwise
      */
     public static <K, V> boolean isNotNullOrEmpty(Map<K, V> map) {
         return !isNullOrEmpty(map);

src/main/java/org/kiwiproject/io/KiwiIO.java

@@ -39,7 +39,7 @@
  * <p>
  * The {@code closeQuietly} methods that accept {@link Closeable} were copied directly from Apache Commons I/O and
  * the deprecation warnings and annotations removed. While they should not be used often, sometimes they might come in
- * handy, so we want to keep them around for posterity. Slight style modifications were made (e.g. replace {@code obj != null}
+ * handy, so we want to keep them around for posterity. Slight style modifications were made (e.g., replace {@code obj != null}
  * checks with {@code nonNull(obj}, etc.) as well as adding logging. Did not bother copying all the {@code closeQuietly}
  * methods that took a specific class such as {@link java.io.Reader}, {@link java.io.Writer}, {@link java.net.Socket}, etc.
  * They all implement {@link Closeable} and were probably only there because those specific classes pre-dated Java 5 when
@@ -110,7 +110,7 @@ public static void closeQuietly(final Closeable closeable) {
      * <b>It should not be used to replace the close statement(s)
      * which should be present for the non-exceptional case.</b>
      * <br>
-     * It is only intended to simplify tidying up where normal processing has already failed
+     * It is only intended to simplify tidying up where normal processing has already failed,
      * and reporting close failure as well is not necessary or useful.
      * <p>
      * Example code:
@@ -572,7 +572,7 @@ public static Stream<String> streamLinesFromInputStreamOf(Process process, Chars
     }
 
     /**
-     * Return a {@link Stream} of {@link String}s from the given {@link InputStream} using the specified {@link Charset}
+     * Return a {@link Stream} of {@link String}s from the {@link InputStream} using the specified {@link Charset}
      * for the String encoding.
      *
      * @param stream  the stream

src/main/java/org/kiwiproject/jackson/KiwiJacksonDataFormats.java

@@ -21,7 +21,7 @@
  * jackson-core, jackson-dataformat-xml, jackson-dataformat-yaml dependencies are present at runtime.
  * <p>
  * WARNING: Before using, please make sure you understand how Jackson actually does its detection. Hint: it's not
- * magic, and may not be as robust as you might like. For example the YAML detector will only report YAML if the
+ * magic, and may not be as robust as you might like. For example, the YAML detector will only report YAML if the
  * content starts with the formal YAML preamble "---". Use the "@see" links below for links to the various Jackson
  * classes that perform data format detection. The main class is {@link DataFormatDetector}, to which you supply
  * one or more detectors, which are {@link JsonFactory} and its subclasses.
@@ -48,7 +48,7 @@ public class KiwiJacksonDataFormats {
      * Is the given text JSON using the default {@link Charset}?
      *
      * @param text the String value to check
-     * @return {@code true} if text is JSON; {@code false} otherwise
+     * @return {@code true} if {@code text} is JSON; {@code false} otherwise
      */
     public static boolean isJson(String text) {
         return isJson(text, DEFAULT_CHARSET);
@@ -58,7 +58,7 @@ public static boolean isJson(String text) {
      * Is the given text JSON using UTF-8 {@link Charset}?
      *
      * @param text the String value to check
-     * @return {@code true} if text is JSON; {@code false} otherwise
+     * @return {@code true} if {@code text} is JSON; {@code false} otherwise
      */
     public static boolean isJsonUtf8(String text) {
         return isJson(text, UTF_8);
@@ -69,7 +69,7 @@ public static boolean isJsonUtf8(String text) {
      *
      * @param text    the String value to check
      * @param charset the character set to use
-     * @return {@code true} if text is JSON; {@code false} otherwise
+     * @return {@code true} if {@code text} is JSON; {@code false} otherwise
      */
     public static boolean isJson(String text, Charset charset) {
         return isFormat(JacksonDataFormat.JSON, text, charset);
@@ -79,7 +79,7 @@ public static boolean isJson(String text, Charset charset) {
      * Is the given text XML using the default {@link Charset}?
      *
      * @param text the String value to check
-     * @return {@code true} if text is XML; {@code false} otherwise
+     * @return {@code true} if {@code text} is XML; {@code false} otherwise
      */
     public static boolean isXml(String text) {
         return isXml(text, DEFAULT_CHARSET);
@@ -89,7 +89,7 @@ public static boolean isXml(String text) {
      * Is the given text XML using UTF-8 {@link Charset}?
      *
      * @param text the String value to check
-     * @return {@code true} if text is XML; {@code false} otherwise
+     * @return {@code true} if {@code text} is XML; {@code false} otherwise
      */
     public static boolean isXmlUtf8(String text) {
         return isXml(text, UTF_8);
@@ -100,7 +100,7 @@ public static boolean isXmlUtf8(String text) {
      *
      * @param text    the String value to check
      * @param charset the character set to use
-     * @return {@code true} if text is XML; {@code false} otherwise
+     * @return {@code true} if {@code text} is XML; {@code false} otherwise
      */
     public static boolean isXml(String text, Charset charset) {
         return isFormat(JacksonDataFormat.XML, text, charset);
@@ -110,7 +110,7 @@ public static boolean isXml(String text, Charset charset) {
      * Is the given text YAML using the default {@link Charset}?
      *
      * @param text the String value to check
-     * @return {@code true} if text is YAML; {@code false} otherwise
+     * @return {@code true} if {@code text} is YAML; {@code false} otherwise
      * @implNote Jackson does NOT consider the content YAML without "---" at the top of the file!
      */
     public static boolean isYaml(String text) {
@@ -121,7 +121,7 @@ public static boolean isYaml(String text) {
      * Is the given text YAML using UTF-8 {@link Charset}?
      *
      * @param text the String value to check
-     * @return {@code true} if text is YAML; {@code false} otherwise
+     * @return {@code true} if {@code text} is YAML; {@code false} otherwise
      * @implNote Jackson does NOT consider the content YAML without "---" at the top of the file!
      */
     public static boolean isYamlUtf8(String text) {
@@ -133,7 +133,7 @@ public static boolean isYamlUtf8(String text) {
      *
      * @param text    the String value to check
      * @param charset the character set to use
-     * @return {@code true} if text is YAML; {@code false} otherwise
+     * @return {@code true} if {@code text} is YAML; {@code false} otherwise
      * @implNote Jackson does NOT consider the content YAML without "---" at the top of the file!
      */
     public static boolean isYaml(String text, Charset charset) {
@@ -146,7 +146,7 @@ public static boolean isYaml(String text, Charset charset) {
      * @param matchFormat the format to match against
      * @param text        the String value to check
      * @param charset     the character set to use
-     * @return {@code true} if text is equal to {@code matchFormat}; {@code false} otherwise
+     * @return {@code true} if {@code text} is equal to {@code matchFormat}; {@code false} otherwise
      */
     public static boolean isFormat(JacksonDataFormat matchFormat, String text, Charset charset) {
         return detectFormat(text, charset)
@@ -155,7 +155,7 @@ public static boolean isFormat(JacksonDataFormat matchFormat, String text, Chars
     }
 
     /**
-     * Detect data format of given text using the default {@link Charset}.
+     * Detect the data format of given text using the default {@link Charset}.
      *
      * @param text the String value to check
      * @return Optional containing detected format, or empty Optional if format was not
@@ -166,7 +166,7 @@ public static Optional<JacksonDataFormat> detectFormat(String text) {
     }
 
     /**
-     * Detect data format of given text using UTF-8 {@link Charset}.
+     * Detect the data format of given text using UTF-8 {@link Charset}.
      *
      * @param text the String value to check
      * @return Optional containing detected format, or empty Optional if format was not
@@ -177,7 +177,7 @@ public static Optional<JacksonDataFormat> detectFormatUtf8(String text) {
     }
 
     /**
-     * Detect data format of given text using the given {@link Charset}.
+     * Detect the data format of given text using the given {@link Charset}.
      *
      * @param text    the String value to check
      * @param charset the character set to use
@@ -193,7 +193,7 @@ public static Optional<JacksonDataFormat> detectFormat(String text, Charset char
     }
 
     /**
-     * Detect data format of given text using given {@link Charset} and {@link DataFormatDetector}.
+     * Detect the data format of given text using given {@link Charset} and {@link DataFormatDetector}.
      * <p>
      * This method is an "escape hatch"; it allows detection of formats not supported in {@link JacksonDataFormat}
      * since it accepts a {@link DataFormatDetector} and it returns a String. Thus, since the caller supplies its own

src/main/java/org/kiwiproject/jar/KiwiJars.java

@@ -126,8 +126,8 @@ public static Optional<String> readSingleValueFromJarManifest(ClassLoader classL
      * @param manifestEntryName The name of the property to resolve
      * @param manifestFilter    An optional filter that can be used to filter down manifest files if there are more than one.
      * @return an {@link Optional} containing the resolved value or {@code Optional.empty()} if not
-     * @implNote If this code is called from a "fat-jar" with single manifest file, then the filter predicate is not needed. The predicate filter is
-     * really only needed if there are multiple jars loaded in the classpath all containing manifest files.
+     * @implNote If this code is called from a "fat-jar" with a single manifest file, then the filter predicate is unnecessary.
+     * The predicate filter is really only necessary if there are multiple jars loaded in the classpath all containing manifest files.
      */
     @SuppressWarnings("java:S2259")
     public static Optional<String> readSingleValueFromJarManifest(ClassLoader classLoader, String manifestEntryName, Predicate<URL> manifestFilter) {
@@ -206,8 +206,8 @@ public static Map<String, String> readValuesFromJarManifest(ClassLoader classLoa
      * @param manifestFilter        a predicate filter used to limit which jar files to search for a manifest file
      * @param manifestEntryNames    an array of names to resolve from the manifest
      * @return a {@code Map<String,String>} of resolved entries
-     * @implNote If this code is called from a "fat-jar" with single manifest file, then the filter predicate is not needed. The predicate filter is
-     * really only needed if there are multiple jars loaded in the classpath all containing manifest files.
+     * @implNote If this code is called from a "fat-jar" with a single manifest file, then the filter predicate is unnecessary.
+     * The predicate filter is really only necessary if there are multiple jars loaded in the classpath all containing manifest files.
      */
     public static Map<String, String> readValuesFromJarManifest(ClassLoader classLoader, Predicate<URL> manifestFilter, String... manifestEntryNames) {
         var entries = new HashMap<String, String>();

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

@@ -63,8 +63,8 @@ public static <T> void assertValid(String id, T obj, Class<?>... groupClasses) {
 
     /**
      * Assert that the given object is valid using the default validation group and the specified property path
-     * map, which allows callers to translate property paths (e.g. firstName) to a human-readable
-     * names (e.g. First Name).
+     * map, which allows callers to translate property paths (e.g., firstName) to a human-readable
+     * names (e.g., First Name).
      *
      * @param id                   the unique identity or ID of the object being validated
      * @param obj                  the object to validate