19577_post-espresso-merge-cleanup (#7)

* stuff

* cleanup

* clean up

Author: caustin-ziro

src/main/java/com/ziro/espresso/collections/MoreLists.java

@@ -5,6 +5,29 @@
 import java.util.List;
 import java.util.Set;
 
+/**
+ * Utility class providing additional list operations beyond those available in the Java Collections Framework.
+ * This class includes methods for performing set operations (union, intersection) on lists while maintaining
+ * collection properties such as uniqueness of elements.
+ *
+ * <p>All operations in this class:
+ * <ul>
+ *     <li>Return new list instances, never modifying the input collections
+ *     <li>Rely on {@code hashCode()} and {@code equals()} for element comparison
+ *     <li>Do not guarantee any specific ordering of elements in the result
+ *     <li>Ensure no duplicate elements in the result
+ * </ul>
+ *
+ * <p>Example usage:
+ * <pre>{@code
+ * List<String> list1 = Arrays.asList("a", "b", "c");
+ * List<String> list2 = Arrays.asList("b", "c", "d");
+ * List<List<String>> lists = Arrays.asList(list1, list2);
+ *
+ * List<String> union = MoreLists.union(lists);        // [a, b, c, d]
+ * List<String> intersection = MoreLists.intersection(lists);  // [b, c]
+ * }</pre>
+ */
 public class MoreLists {
 
     private MoreLists() {}

src/main/java/com/ziro/espresso/collections/package-info.java

@@ -0,0 +1,4 @@
+@NonNullByDefault
+package com.ziro.espresso.collections;
+
+import com.ziro.espresso.javax.annotation.extensions.NonNullByDefault;

src/main/java/com/ziro/espresso/fluent/exceptions/AbstractFluentExceptionSupport.java

@@ -8,7 +8,12 @@
 import java.util.function.Supplier;
 
 /**
- * Provides fluent support to any type of throwable.
+ * Abstract base class providing a fluent builder pattern for creating and configuring exceptions.
+ * This class implements a two-stage builder pattern for creating exceptions with customizable
+ * messages and causes.
+ *
+ * <p>This class serves as the foundation for implementing custom exceptions with fluent APIs.
+ * It provides methods for setting messages, causes, and creating exceptions in a type-safe manner.
  */
 @NonNullByDefault
 public abstract class AbstractFluentExceptionSupport<T extends Throwable> implements ExceptionDetailsStage<T> {
@@ -23,42 +28,118 @@ public abstract class AbstractFluentExceptionSupport<T extends Throwable> implem
     @Nullable
     private Throwable cause;
 
+    /**
+     * Creates a new exception builder with a default message of "Something went wrong."
+     */
     protected AbstractFluentExceptionSupport() {
         this.defaultMessage = FALLBACK_DEFAULT_MESSAGE;
     }
 
+    /**
+     * Creates a new exception builder with the specified default message.
+     * This message will be used when no specific message is provided through
+     * the builder methods.
+     *
+     * @param defaultMessage the message to use when no specific message is set
+     */
     protected AbstractFluentExceptionSupport(String defaultMessage) {
         this.defaultMessage = defaultMessage;
     }
 
-    // Generic factory methods - to be used by concrete exception classes
+    /**
+     * Creates a new exception builder that wraps an existing throwable as its cause.
+     * This factory method is intended to be used by concrete exception implementations
+     * to provide their fluent API.
+     *
+     * @param <T> the type of exception to create
+     * @param cause the underlying cause of the exception
+     * @param builderFactory supplier for creating new builder instances
+     * @return a builder stage for constructing the exception with additional details
+     */
     public static <T extends Throwable> ExceptionDetailsStage<T> withCause(
             Throwable cause, Supplier<AbstractFluentExceptionSupport<T>> builderFactory) {
         AbstractFluentExceptionSupport<T> builder = builderFactory.get();
         builder.setCause(cause);
         return builder;
     }
 
+    /**
+     * Creates a new exception builder for exceptions that represent a root cause
+     * (with no underlying cause).
+     *
+     * @param <T> the type of exception to create
+     * @param builderFactory supplier for creating new builder instances
+     * @return a builder stage for constructing the exception with additional details
+     */
     public static <T extends Throwable> ExceptionDetailsStage<T> asRootCause(
             Supplier<AbstractFluentExceptionSupport<T>> builderFactory) {
         return builderFactory.get();
     }
 
+    /**
+     * Returns the currently set exception message.
+     *
+     * <p>The message is optional and may return an empty Optional if no message has been set.
+     * In such cases, when the exception is created, it will use the default message specified
+     * in the constructor.
+     *
+     * <p>This is a protected method intended for use by subclasses that need to access
+     * the raw message value during exception creation.
+     *
+     * @return an Optional containing the current exception message, or an empty Optional if no message is set
+     */
     protected Optional<String> message() {
         return Optional.ofNullable(message);
     }
 
-    // @deprecated Use withCause(Throwable) or asRootCause() instead
+    /**
+     * Sets the cause for this exception.
+     *
+     * @deprecated Use {@link withCause(Throwable)} to create exceptions with a cause, or {@link #asRootCause()}
+     * for exceptions without a cause. These methods provide a clearer and more structured approach to exception creation.
+     *
+     * <p>Example of preferred usage:
+     * <pre>{@code
+     * // Instead of:
+     * MyException.fluent().cause(e).message("Failed").exception();
+     *
+     * // Use:
+     * MyException.withCause(e).message("Failed").exception();
+     * }</pre>
+     *
+     * @param cause the throwable that caused this exception
+     * @return this builder instance for method chaining
+     */
     @Deprecated
     public AbstractFluentExceptionSupport<T> cause(Throwable cause) {
         this.cause = cause;
         return this;
     }
 
+    /**
+     * Returns the currently set cause of the exception.
+     *
+     * <p>The cause is optional and may return an empty Optional if no cause has been set.
+     * This typically occurs when the exception is created using {@link #asRootCause()}.
+     *
+     * <p>This is a protected method intended for use by subclasses that need to access
+     * the cause during exception creation.
+     *
+     * @return an Optional containing the current exception cause, or an empty Optional if no cause is set
+     */
     protected Optional<Throwable> cause() {
         return Optional.ofNullable(cause);
     }
 
+    /**
+     * Sets the exception message with optional formatting arguments.
+     * If formatting arguments are provided, they will be applied using
+     * {@link String#format(String, Object...)}.
+     *
+     * @param message the message template
+     * @param messageArgs optional formatting arguments
+     * @return this builder instance for method chaining
+     */
     @Override
     public ExceptionDetailsStage<T> message(String message, Object... messageArgs) {
         if (messageArgs.length > 0) {
@@ -69,22 +150,39 @@ public ExceptionDetailsStage<T> message(String message, Object... messageArgs) {
         return this;
     }
 
+    /**
+     * Sets the exception message using a supplier.
+     * The supplier will be evaluated immediately to get the message.
+     *
+     * @param messageSupplier supplier that provides the exception message
+     * @return this builder instance for method chaining
+     */
     @Override
     public ExceptionDetailsStage<T> message(Supplier<String> messageSupplier) {
         this.message = messageSupplier.get();
         return this;
     }
 
-    // Throws exception if condition not satisfied.
-    // Note: IntelliJ understands that this throws an exception but may need extra null checks for null checking
-    // conditions.
+    /**
+     * Throws the configured exception if the specified condition is true.
+     * This is a convenience method for conditional exception throwing.
+     *
+     * @param condition the condition to evaluate
+     * @throws T the configured exception if the condition is true
+     */
     @Override
     public void throwIf(boolean condition) throws T {
         if (condition) {
             throw exception();
         }
     }
 
+    /**
+     * Creates and returns the exception instance with all configured properties.
+     * If no message was set, uses the default message.
+     *
+     * @return the configured exception instance
+     */
     @Override
     public T exception() {
         String exceptionMessage = message().orElse(defaultMessage);
@@ -122,9 +220,25 @@ private static String ensureEndsWithPeriod(String exceptionMessage) {
         return exceptionMessage.endsWith(".") ? exceptionMessage : exceptionMessage + ".";
     }
 
-    // The following abstract methods are the reason why we had to go abstract on this
+    /**
+     * Creates an exception instance with the specified message.
+     * This method must be implemented by concrete subclasses to create
+     * their specific exception type.
+     *
+     * @param message the exception message
+     * @return a new exception instance
+     */
     protected abstract T createExceptionWith(String message);
 
+    /**
+     * Creates an exception instance with the specified message and cause.
+     * This method must be implemented by concrete subclasses to create
+     * their specific exception type.
+     *
+     * @param message the exception message
+     * @param cause the underlying cause of the exception
+     * @return a new exception instance
+     */
     protected abstract T createExceptionWith(String message, Throwable cause);
 
     // Used by the concrete exception classes

src/main/java/com/ziro/espresso/fluent/exceptions/SystemUnhandledException.java

@@ -3,6 +3,34 @@
 import com.ziro.espresso.javax.annotation.extensions.NonNullByDefault;
 import jakarta.annotation.Nonnull;
 
+/**
+ * A runtime exception that represents unrecoverable system-level errors in the ZIRO application.
+ * This exception provides a fluent builder pattern for creating detailed error messages and
+ * handling exception chains.
+ *
+ * <p>The exception can be created either as a root cause or by wrapping another exception.
+ * It supports a fluent interface for building exception instances with custom messages and
+ * causes.
+ *
+ * <p>Example usage:
+ * <pre>{@code
+ * // Creating with a cause
+ * throw SystemUnhandledException.withCause(originalException)
+ *     .message("Failed to process request: %s", requestId)
+ *     .exception();
+ *
+ * // Creating as root cause
+ * throw SystemUnhandledException.asRootCause()
+ *     .message("Configuration is invalid")
+ *     .exception();
+ * }</pre>
+ *
+ * <p>By default, if no custom message is provided, the exception uses the message:
+ * "{@value #DEFAULT_MESSAGE}"
+ *
+ * @see ExceptionDetailsStage
+ * @see AbstractFluentExceptionSupport
+ */
 @NonNullByDefault
 public class SystemUnhandledException extends RuntimeException {
 
@@ -16,17 +44,49 @@ private SystemUnhandledException(String message, Throwable cause) {
         super(message, cause);
     }
 
-    // Creates a new exception builder that will wrap the given cause.
+    /**
+     * Creates a new exception builder that wraps an existing throwable as its cause.
+     * This method is the preferred way to create an exception instance when there is
+     * an underlying cause.
+     *
+     * <p>Example usage:
+     * <pre>{@code
+     * throw SystemUnhandledException.withCause(originalException)
+     *     .message("Failed to process: %s", id)
+     *     .exception();
+     * }</pre>
+     *
+     * @param cause the underlying throwable that caused this exception
+     * @return a builder stage for constructing the exception with additional details
+     */
     public static ExceptionDetailsStage<SystemUnhandledException> withCause(Throwable cause) {
         return AbstractFluentExceptionSupport.withCause(cause, SystemUnhandledExceptionBuilder::new);
     }
 
-    // Creates a new exception builder that will be a root cause (no wrapped exception).
+    /**
+     * Creates a new exception builder for exceptions that represent a root cause
+     * (with no underlying cause). Use this method when the exception is the original
+     * source of the error.
+     *
+     * <p>Example usage:
+     * <pre>{@code
+     * throw SystemUnhandledException.asRootCause()
+     *     .message("Invalid system configuration")
+     *     .exception();
+     * }</pre>
+     *
+     * @return a builder stage for constructing the exception with additional details
+     */
     public static ExceptionDetailsStage<SystemUnhandledException> asRootCause() {
         return AbstractFluentExceptionSupport.asRootCause(SystemUnhandledExceptionBuilder::new);
     }
 
-    // @deprecated Use withCause(Throwable) or asRootCause() instead
+    /**
+     * @deprecated Use {@link #withCause(Throwable)} or {@link #asRootCause()} instead
+     * for more explicit exception creation.
+     *
+     * @return a fluent exception support instance for building the exception
+     */
     @Deprecated
     public static AbstractFluentExceptionSupport<SystemUnhandledException> fluent() {
         return new SystemUnhandledExceptionBuilder();

src/main/java/com/ziro/espresso/formatters/MaxLengthFormatter.java

@@ -2,30 +2,59 @@
 
 import com.google.common.base.Preconditions;
 import com.ziro.espresso.javax.annotation.extensions.NonNullByDefault;
-import org.slf4j.Logger;
-import org.slf4j.LoggerFactory;
+import lombok.extern.slf4j.Slf4j;
 
+/**
+ * A utility class that formats strings by ensuring they don't exceed a specified maximum length.
+ * If a string exceeds the maximum length, it will be truncated and trimmed.
+ *
+ * <p>This formatter is immutable and thread-safe. The maximum length is set during construction
+ * and cannot be changed afterwards.
+ *
+ * <p>Example usage:
+ * <pre>{@code
+ * MaxLengthFormatter formatter = MaxLengthFormatter.of(10);
+ * String result = formatter.format("This is a long text"); // Returns "This is a"
+ * }</pre>
+ */
+@Slf4j
 @NonNullByDefault
 public class MaxLengthFormatter {
 
-    private static final Logger LOGGER = LoggerFactory.getLogger(MaxLengthFormatter.class);
-
     private final int maxLength;
 
     private MaxLengthFormatter(int maxLength) {
         Preconditions.checkArgument(maxLength > 0, "Max length must be > 0");
         this.maxLength = maxLength;
     }
 
+    /**
+     * Creates a new MaxLengthFormatter with the specified maximum length.
+     *
+     * @param maxLength the maximum length allowed for formatted strings. Must be greater than 0.
+     * @return a new MaxLengthFormatter instance
+     * @throws IllegalArgumentException if maxLength is 0 or negative
+     */
     public static MaxLengthFormatter of(int maxLength) {
         return new MaxLengthFormatter(maxLength);
     }
 
+    /**
+     * Formats the input string by ensuring it doesn't exceed the maximum length.
+     * If the input string is longer than the maximum length, it will be truncated
+     * and trimmed of trailing whitespace.
+     *
+     * <p>If the input string is already within the maximum length, it will be
+     * returned unchanged.
+     *
+     * @param value the string to format
+     * @return the formatted string, truncated and trimmed if necessary
+     */
     public String format(String value) {
         if (value.length() > maxLength) {
-            LOGGER.debug("Formatting value [{}]", value);
+            log.debug("Formatting value [{}]", value);
             String truncatedValue = value.substring(0, maxLength).trim();
-            LOGGER.debug("Truncated [{}] to [{}]", value, truncatedValue);
+            log.debug("Truncated [{}] to [{}]", value, truncatedValue);
             return truncatedValue;
         }
         return value;