Update method and parameter descriptions for clarity

Improvements were made on method and parameter descriptions for better understanding. These changes involve mainly renaming and better explaining function purposes and their returned objects. In addition, a new enum, DigestAlgorithm, was created to represent various digest algorithm types for MessageDigest.

src/main/java/art/cutils/collection/ListPartition.java

@@ -67,11 +67,11 @@ private ListPartition(final List<? extends T> list) {
   }
 
   /**
-   * Method to receive the list to be partitioned.
+   * Creates a new instance of ListPartition by partitioning the given list into sublists.
    *
-   * @param list List to be partitioned.
-   * @param <T> List type
-   * @return instance of {@link ListPartition}
+   * @param list The list to be partitioned. Cannot be null.
+   * @param <T> The type of elements in the list.
+   * @return A new instance of ListPartition.
    */
   @Contract("_ -> new")
   public static <T> @NotNull ListPartition<T> of(final List<? extends T> list) {
@@ -80,11 +80,12 @@ private ListPartition(final List<? extends T> list) {
   }
 
   /**
-   * Method to receive the array to be partitioned.
+   * This method creates a new instance of ListPartition by partitioning the given array into
+   * sublists of the specified size.
    *
-   * @param array Array to be partitioned.
-   * @param <T> Array type
-   * @return instance of {@link ListPartition}
+   * @param array The array to be partitioned. Cannot be null.
+   * @param <T> The type of elements in the array.
+   * @return A new instance of ListPartition.
    */
   @SafeVarargs
   @Contract("_ -> new")
@@ -94,10 +95,10 @@ private ListPartition(final List<? extends T> list) {
   }
 
   /**
-   * Method used to get partition size.
+   * Partitions the list into sublists of the specified size.
    *
-   * @param sublistSize The sub-list/ListPartition size.
-   * @return current instance of {@link ListPartition}
+   * @param sublistSize The size of each sublist. Must be greater than 0.
+   * @return The ListPartition instance.
    */
   @Contract(value = "_ -> this", mutates = "this")
   public ListPartition<T> into(final int sublistSize) {
@@ -106,8 +107,9 @@ public ListPartition<T> into(final int sublistSize) {
     return this;
   }
 
-  @Contract(pure = true)
+  /** {@inheritDoc} */
   @Override
+  @Contract(pure = true)
   public @NotNull List<T> get(final int index) {
     final int start = index * this.sublistSize;
     final int end = Math.min(start + this.sublistSize, this.list.size());
@@ -118,6 +120,7 @@ public ListPartition<T> into(final int sublistSize) {
     return new ArrayList<>(this.list.subList(start, end));
   }
 
+  /** {@inheritDoc} */
   @Override
   public int size() {
     return (int) Math.ceil((double) this.list.size() / (double) this.sublistSize);

src/main/java/art/cutils/function/Accepter.java

@@ -72,10 +72,10 @@ default Accepter<T> andThen(final Accepter<? super T> after) {
   }
 
   /**
-   * Performs this operation on the given argument.
+   * This method accepts a value of type T and executes the specified Accepter on it.
    *
-   * @param t the input argument.
-   * @throws Exception throws accepter exception
+   * @param t the value to accept
+   * @throws Exception if the Accepter throws an exception
    */
   void accept(T t) throws Exception;
 }

src/main/java/art/cutils/function/Dealer.java

@@ -46,10 +46,11 @@
 public interface Dealer<T> {
 
   /**
-   * Gets a result.
+   * Executes the dealer operation, which may throw an exception, and returns the result.
    *
-   * @return a result
-   * @throws Exception operation exception thrown
+   * @return the result of the dealer operation
+   * @throws Exception if the dealer operation throws an exception
+   * @see Dealer
    */
   T deal() throws Exception;
 }

src/main/java/art/cutils/function/Executable.java

@@ -35,9 +35,9 @@
 public interface Executable {
 
   /**
-   * Execute the operation that may likely throw and Exception.
+   * Executes the operation represented by this Executable.
    *
-   * @throws Exception that is thrown when operation executes.
+   * @throws Exception if an exception occurs during execution
    */
   void execute() throws Exception;
 }

src/main/java/art/cutils/function/Generator.java

@@ -39,10 +39,11 @@
 public interface Generator<T> {
 
   /**
-   * Generates values.
+   * Generates a value each time it is called.
    *
-   * @return return generate values of T type.
-   * @since 1.0
+   * @param <T> the type of value to generate
+   * @return a unique value of type T
+   * @see Generator
    */
   T generate();
 }

src/main/java/art/cutils/function/Idler.java

@@ -71,36 +71,69 @@ private Idler(final Supplier<T> supplier) {
   }
 
   /**
-   * Sealed constructor takes the dealer.
+   * Private constructor for the Idler class.
    *
-   * @param dealer instance of {@link Dealer}
+   * @param dealer the dealer used by the Idler instance
+   * @param <T> the type of results supplied by the dealer
    */
   private Idler(final Dealer<T> dealer) {
     this.dealer = dealer;
   }
 
+  /**
+   * Creates an instance of Idler with the given dealer and supplier.
+   *
+   * @param dealer an instance of Dealer interface
+   * @param supplier an instance of Supplier interface
+   */
   private Idler(final Dealer<T> dealer, final Supplier<T> supplier) {
     this.dealer = dealer;
     this.supplier = supplier;
   }
 
+  /**
+   * Creates an instance of Idler with the given dealer and supplier.
+   *
+   * @param dealer an instance of Dealer interface
+   * @param supplier an instance of Supplier interface
+   * @param <T> the type of results supplied by the dealer
+   * @return a new instance of Idler
+   * @throws NullPointerException if either the dealer or supplier is null
+   */
   @Contract("_, _ -> new")
   public static <T> @NotNull Idler<T> of(final Dealer<T> dealer, final Supplier<T> supplier) {
     return Idler.of(supplier, dealer);
   }
 
-  @Contract("_, _ -> new")
-  public static <T> @NotNull Idler<T> of(final Dealer<T> dealer) {
-    return new Idler<>(dealer);
-  }
-
+  /**
+   * Creates an instance of Idler with the given supplier and dealer.
+   *
+   * @param supplier an instance of Supplier interface
+   * @param dealer an instance of Dealer interface
+   * @param <T> the type of results supplied by the dealer
+   * @return a new instance of Idler
+   * @throws NullPointerException if either the dealer or supplier is null
+   */
   @Contract("_, _ -> new")
   public static <T> @NotNull Idler<T> of(final Supplier<T> supplier, final Dealer<T> dealer) {
     requireNonNull(dealer, "dealer cannot be null");
     requireNonNull(supplier, "supplier cannot be null");
     return new Idler<>(dealer, supplier);
   }
 
+  /**
+   * Creates a new instance of {@link Idler} with the given dealer.
+   *
+   * @param dealer the dealer used by the Idler instance
+   * @param <T> the type of results supplied by the dealer
+   * @return a new instance of Idler
+   * @throws NullPointerException if the dealer is null
+   */
+  @Contract("_, _ -> new")
+  public static <T> @NotNull Idler<T> of(final Dealer<T> dealer) {
+    return new Idler<>(dealer);
+  }
+
   /**
    * Supply take an instance of {@link Supplier} as parameter..
    *
@@ -115,11 +148,12 @@ private Idler(final Dealer<T> dealer, final Supplier<T> supplier) {
   }
 
   /**
-   * Supply take an instance of {@link Dealer} as parameter..
+   * Creates a new instance of {@link Idler} with the given dealer.
    *
-   * @param <T> the type parameter
-   * @param dealer the supplier, an instance of {@link Dealer}
-   * @return the supplier, an instance of {@link Dealer}
+   * @param dealer the dealer used by the Idler instance
+   * @param <T> the type of results supplied by the dealer
+   * @return a new instance of Idler
+   * @throws NullPointerException if the dealer is null
    */
   @Contract("_ -> new")
   public static <T> @NotNull Dealer<T> deal(final Dealer<T> dealer) {
@@ -128,10 +162,11 @@ private Idler(final Dealer<T> dealer, final Supplier<T> supplier) {
   }
 
   /**
-   * Gets a result for dealer operation.
+   * Executes the deal operation and returns the second value of the pair, which represents the
+   * result of the dealer operation.
    *
-   * @return a dealer result
-   * @see Dealer#deal
+   * @return the second value
+   * @throws Exception if the dealer operation throws an exception
    */
   @Override
   public T deal() throws Exception {
@@ -142,10 +177,11 @@ public T deal() throws Exception {
   }
 
   /**
-   * Gets a result for supplier operation.
+   * Returns the value held by this instance of Idler. If the supplier is not null and the first
+   * value in the pair is null, the supplier will be invoked and the result will be set as the first
+   * value in the pair. Otherwise, it returns the first value in the pair.
    *
-   * @return a supplier result
-   * @see Supplier#get
+   * @return the value held by this instance of Idler
    */
   @Override
   public T get() {

src/main/java/art/cutils/function/LazyFunction.java

@@ -66,12 +66,13 @@ private LazyFunction(final Function<? super T, ? extends R> function) {
   }
 
   /**
-   * Take the function operation of {@link Function} type.
+   * Creates a new lazy function from the given function.
    *
-   * @param <T>      the type parameter
-   * @param <R>      the return type parameter
-   * @param function the function, of {@link Function} type
-   * @return the function, an instance of {@link Function} type.
+   * @param function the function to create a lazy function from
+   * @param <T> the type of the input to the function
+   * @param <R> the type of the result of the function
+   * @return a new lazy function
+   * @throws NullPointerException if the function is null
    */
   @Contract("_ -> new")
   public static <T, R> @NotNull Function<T, R> of(final Function<? super T, ? extends R> function) {
@@ -80,10 +81,12 @@ private LazyFunction(final Function<? super T, ? extends R> function) {
   }
 
   /**
-   * Applies this function to the given argument.
+   * Applies the function to the given argument. If the argument is already present in the store,
+   * the stored value is returned. Otherwise, the function is applied to the argument , the result
+   * is stored in the store, and then returned.
    *
-   * @param t the function argument
-   * @return the function result
+   * @param t the argument to apply the function to
+   * @return the result of applying the function to the argument
    */
   @Override
   public R apply(final T t) {

src/main/java/art/cutils/function/LazyUnaryOperator.java

@@ -59,11 +59,14 @@ private LazyUnaryOperator(final UnaryOperator<T> operator) {
   }
 
   /**
-   * Take the operator argument of {@link UnaryOperator} type.
+   * Creates a new instance of {@link UnaryOperator} that lazily applies the given {@link
+   * UnaryOperator}.
    *
-   * @param <T> the type parameter
-   * @param operator the function, of {@link UnaryOperator} type
-   * @return the function, an instance of {@link Function} type.
+   * @param operator the {@link UnaryOperator} to be applied lazily
+   * @param <T> the type of the argument and result of the {@link UnaryOperator}
+   * @return a new instance of {@link UnaryOperator} that applies the given {@link UnaryOperator}
+   *     lazily
+   * @throws NullPointerException if the {@code operator} is null
    */
   @Contract("_ -> new")
   public static <T> @NotNull UnaryOperator<T> of(final UnaryOperator<T> operator) {
@@ -72,10 +75,11 @@ private LazyUnaryOperator(final UnaryOperator<T> operator) {
   }
 
   /**
-   * Applies this function to the given argument.
+   * Applies the function to the given argument.
    *
-   * @param t the function argument
-   * @return the function result
+   * @param t the argument to apply the function to
+   * @return the result of applying the function to the argument
+   * @throws NullPointerException if the argument is null
    */
   @Override
   public T apply(final T t) {

src/main/java/art/cutils/function/ThrowingFunction.java

@@ -63,26 +63,26 @@ public interface ThrowingFunction<T, R> {
   }
 
   /**
-   * Applies this function to the given argument.
+   * Throws a given exception without requiring it to be declared in the method signature.
    *
-   * @param t the function argument if Type T
-   * @return the function result
-   * @throws Exception any exception thrown when applying function
-   */
-  R apply(T t) throws Exception;
-
-  /**
-   * Sneak exception on function execution.
-   *
-   * @param ex exception throw on operation
-   * @param <T> arg type
-   * @param <R> return type
-   * @return an exception
-   * @throws T arg type exception
+   * @param ex the exception to throw
+   * @param <T> the specific type of exception to throw
+   * @param <R> the return type of the method
+   * @return does not actually return a value (throws an exception instead)
+   * @throws T the given exception, cast to the specific type
    */
   @SuppressWarnings("unchecked")
   @Contract(value = "_ -> fail", pure = true)
   static <T extends Exception, R> R sneakyThrow(final Exception ex) throws T {
     throw (T) ex;
   }
+
+  /**
+   * Applies the function to the given input.
+   *
+   * @param t the input to the function
+   * @return the result of applying the function to the input
+   * @throws Exception if an error occurs during function execution
+   */
+  R apply(T t) throws Exception;
 }