Update several utility classes and modules

The update includes several refinements throughout the utility module, such as additional comments for the module-info java files, clarifying method return descriptions, and including class type parameters in relevant methods. A few classes, particularly in data manipulation and math geometry files, have been revised to improve code integrity. The adjustments offer better code clarity and enhanced utility function performance.

utility-logging/src/main/java/module-info.java

@@ -3,6 +3,17 @@
 // This software is released under the MIT License.
 // https://opensource.org/licenses/MIT
 
+/**
+ * The com.dua3.utility.logging module is responsible for providing utilities related to logging.
+ * It exports the com.dua3.utility.logging package which contains classes and interfaces related to logging.
+ * <p>
+ * The module requires the com.dua3.cabe.annotations package at compile time.
+ * <p>
+ * It uses the com.dua3.utility.logging.ILogEntryDispatcherFactory service to obtain an instance of the
+ * LogEntryDispatcher.
+ * <p>
+ * The module also requires the org.apache.logging.log4j and com.dua3.utility packages at runtime.
+ */
 open module com.dua3.utility.logging {
     exports com.dua3.utility.logging;
 

utility-logging/utility-logging-log4j/src/main/java/module-info.java

@@ -6,6 +6,9 @@
 import com.dua3.utility.logging.ILogEntryDispatcherFactory;
 import com.dua3.utility.logging.log4j.LogEntryDispatcherFactoryLog4j;
 
+/**
+ * This module provides logging functionality using Log4j.
+ */
 open module com.dua3.utility.logging.log4j {
     exports com.dua3.utility.logging.log4j;
 

utility-logging/utility-logging-slf4j/src/main/java/module-info.java

@@ -8,6 +8,9 @@
 import com.dua3.utility.logging.slf4j.LoggingServiceProviderSlf4j;
 import org.slf4j.spi.SLF4JServiceProvider;
 
+/**
+ * This module provides SLF4J logging functionality and integration with the Logging utility module.
+ */
 open module com.dua3.utility.logging.slf4j {
     exports com.dua3.utility.logging.slf4j;
     provides SLF4JServiceProvider with LoggingServiceProviderSlf4j;

utility-samples/utility-samples-log4j/src/main/java/module-info.java

@@ -3,6 +3,9 @@
 // This software is released under the MIT License.
 // https://opensource.org/licenses/MIT
 
+/**
+ * This module contains the classes for the sample applications using Log4J.
+ */
 open module com.dua3.utility.samples.log4j {
     exports com.dua3.utility.samples.log4j;
 

utility-samples/utility-samples-slf4j/src/main/java/module-info.java

@@ -3,6 +3,9 @@
 // This software is released under the MIT License.
 // https://opensource.org/licenses/MIT
 
+/**
+ * This module contains the classes for the sample applications using SLF4J.
+ */
 open module com.dua3.utility.samples.slf4j {
     exports com.dua3.utility.samples.slf4j;
 

utility-swing/src/main/java/module-info.java

@@ -3,6 +3,14 @@
 // This software is released under the MIT License.
 // https://opensource.org/licenses/MIT
 
+/**
+ * This module provides utilities related to Swing-based GUI applications.
+ * <p>
+ * The module provides implementations of the FontUtil and ImageUtil interfaces.
+ * These implementations are automatically chosen at runtime:
+ * - com.dua3.utility.swing.SwingFontUtil is the implementation of FontUtil
+ * - com.dua3.utility.swing.SwingImageUtil is the implementation of ImageUtil
+ */
 open module com.dua3.utility.swing {
     exports com.dua3.utility.swing;
 

utility/src/main/java/com/dua3/utility/data/FilterIterator.java

@@ -30,11 +30,12 @@ public class FilterIterator<T> implements Iterator<T> {
     public FilterIterator(Iterator<T> iterator, Predicate<T> predicate) {
         this.iterator = Objects.requireNonNull(iterator);
         this.predicate = Objects.requireNonNull(predicate);
+        this.done = false;
         findNext();
     }
 
     /**
-     * Move internal iterator to the next item that matches the predicate.
+     * Move the internal iterator to the next item that matches the predicate.
      */
     private void findNext() {
         if (done) {

utility/src/main/java/com/dua3/utility/data/PeekIterator.java

@@ -25,6 +25,7 @@ public class PeekIterator<T> implements Iterator<T> {
      */
     public PeekIterator(Iterator<T> iterator) {
         this.iterator = Objects.requireNonNull(iterator);
+        this.done = false;
         move();
     }
 

utility/src/main/java/com/dua3/utility/io/IoUtil.java

@@ -787,7 +787,7 @@ public static Stream<Path> glob(Path base, String pattern) throws IOException {
      * Returned path should be created the same as the relative path resolved by base.
      * @param base the base path
      * @param p the path
-     * @return
+     * @return the normalized path
      */
     private static Path normalizePath(Path base, Path p) {
         // When a fixed path prefix was extracted in glob, p and base have different root

utility/src/main/java/com/dua3/utility/math/geometry/PathBuilder2f.java

@@ -79,7 +79,7 @@ public PathBuilder2f moveTo(Vector2f v) {
      * Add a line from the current position to a new position.
      *
      * @param v the new position
-     * @return
+     * @return this instance
      */
     public PathBuilder2f lineTo(Vector2f v) {
         if (!open) {
@@ -100,7 +100,7 @@ public PathBuilder2f lineTo(Vector2f v) {
      * @param p1 second control point
      * @param p2 third control point
      * @param p3 fourth control point
-     * @return
+     * @return this instance
      */
     public PathBuilder2f curveTo(Vector2f p1, Vector2f p2, Vector2f p3) {
         if (!open) {
@@ -125,7 +125,7 @@ public PathBuilder2f curveTo(Vector2f p1, Vector2f p2, Vector2f p3) {
      *     <li> the path is reset when new segments are added to it after calling this method
      * </ul>
      *
-     * @return
+     * @return this instance
      */
     public PathBuilder2f closePath() {
         if (open) {
@@ -145,7 +145,7 @@ public PathBuilder2f closePath() {
      *     <li> the path is reset when new segments are added to it after calling this method
      * </ul>
      *
-     * @return
+     * @return this instance
      */
     public PathBuilder2f endPath() {
         if (open) {

utility/src/main/java/com/dua3/utility/options/ArgumentsParser.java

@@ -24,15 +24,15 @@ public class ArgumentsParser {
 
     private final Map<String, Option<?>> options;
 
-    int minPositionalArgs;
+    final int minPositionalArgs;
 
-    int maxPositionalArgs;
+    final int maxPositionalArgs;
 
-    private String positionalArgDisplayName;
+    private final String positionalArgDisplayName;
 
-    private String name;
+    private final String name;
 
-    private String description;
+    private final String description;
 
     /**
      * Returns a new instance of ArgumentsParserBuilder.
@@ -64,7 +64,7 @@ public static ArgumentsParserBuilder builder() {
     }
 
     /**
-     * Parses command line arguments and returns an instance of Arguments.
+     * Parse the command line arguments and return an instance of {@link Arguments}.
      *
      * @param args the command line arguments to parse
      * @return an instance of Arguments containing the parsed options and positional arguments

utility/src/main/java/com/dua3/utility/options/ArgumentsParserBuilder.java

@@ -91,6 +91,7 @@ public Flag flag(String... names) {
      * Creates a SimpleOption with the given mapper function and names.
      *
      * @param <T>    the option's argument type.
+     * @param type   {@link Class} instance of the option's argument type
      * @param names  the names for the option, at least one
      * @return the created SimpleOption
      */
@@ -126,6 +127,7 @@ public <E extends Enum<E>> ChoiceOption<E> choiceOption(Class<? extends E> enumC
      * Adds a standard option to the ArgumentsParserBuilder instance being built.
      *
      * @param <T>    the option's argument type.
+     * @param type   {@link Class} instance of the option's argument type
      * @param names  the names for the option, at least one.
      * @return the created StandardOption.
      */

utility/src/main/java/com/dua3/utility/text/RichTextBuilder.java

@@ -257,7 +257,7 @@ public RichTextBuilder push(String name, Object value) {
      * Pop attribute that has been set using {@link #push(String, Object)}.
      *
      * @param name attribute name
-     * @return
+     * @return this instance
      */
     public RichTextBuilder pop(String name) {
         AttributeChange change = openedAttributes.pop();
@@ -275,6 +275,7 @@ public RichTextBuilder pop(String name) {
      * Push style. Remove the style again by calling {@link #pop(Style)}.
      *
      * @param style the {@link Style} to push
+     * @return this instance
      */
     @SuppressWarnings("unchecked")
     public RichTextBuilder push(Style style) {
@@ -290,6 +291,7 @@ public RichTextBuilder push(Style style) {
      * Pop style that has been set using {@link #push(Style)}.
      *
      * @param style the style
+     * @return this instance
      */
     public RichTextBuilder pop(Style style) {
         return pop(RichText.ATTRIBUTE_NAME_STYLE_LIST);

utility/src/main/java/module-info.java

@@ -3,6 +3,36 @@
 // This software is released under the MIT License.
 // https://opensource.org/licenses/MIT
 
+/**
+ * The com.dua3.utility module provides utility classes for various purposes, such as
+ * concurrent programming, data manipulation, I/O operations, language utilities,
+ * mathematical operations, options handling, text manipulation, and XML processing.
+ * <p>
+ * This module exports the following packages:
+ * <ul>
+ * <li>com.dua3.utility.concurrent: Utility classes for concurrent programming.
+ * <li>com.dua3.utility.data: Utility classes for data manipulation.
+ * <li>com.dua3.utility.io: Utility classes for I/O operations.
+ * <li>com.dua3.utility.lang: Utility classes for language utilities.
+ * <li>com.dua3.utility.math: Utility classes for mathematical operations.
+ * <li>com.dua3.utility.math.geometry: Utility classes for geometric operations.
+ * <li>com.dua3.utility.options: Utility classes for handling options.
+ * <li>com.dua3.utility.text: Utility classes for text manipulation.
+ * <li>com.dua3.utility.xml: Utility classes for XML processing.
+ * </ul>
+ * This module requires the following modules:
+ * <ul>
+ * <li>requires static com.dua3.cabe.annotations: A static requirement for the com.dua3.cabe.annotations module.
+ * <li>requires java.xml: A requirement for the java.xml module.
+ * <li>requires org.apache.logging.log4j: A requirement for the org.apache.logging.log4j module.
+ * </ul>
+ * This module uses the following services:
+ * <ul>
+ * <li>com.dua3.utility.text.FontUtil: A service used by the TextUtil class for font handling.
+ * <li>com.dua3.utility.io.FileType: A service used for file type handling.
+ * <li>com.dua3.utility.data.ImageUtil: A service used for image manipulation.
+ * </ul>
+ */
 open module com.dua3.utility {
     exports com.dua3.utility.concurrent;
     exports com.dua3.utility.data;