ThrowsOr uses CheckedSupplier. Document checked interfaces.

src/main/java/com/rezzedup/util/exceptional/ThrowsOr.java

@@ -7,6 +7,7 @@
  */
 package com.rezzedup.util.exceptional;
 
+import com.rezzedup.util.exceptional.checked.CheckedSupplier;
 import pl.tlinkowski.annotation.basic.NullOr;
 
 import java.util.NoSuchElementException;
@@ -132,54 +133,30 @@ public static <V> ThrowsOr<V> raise(Supplier<Throwable> exceptionSupplier)
 
     /**
      * Creates a new {@code ThrowsOr} containing the
-     * supplied value or the runtime exception thrown
+     * supplied value or the exception thrown
      * when attempting to get it.
      *
      * <p>If the value is successfully supplied without
-     * interference from any runtime exceptions, the
-     * result is created by passing the value to
+     * interference from any exceptions, the result
+     * is created by passing the value to
      * {@link #maybe(Object)}.</p>
      *
-     * <p>Likewise, any thrown runtime exceptions are
+     * <p>Likewise, any thrown exceptions are
      * passed to {@link #raise(Throwable)}.</p>
      *
      * @param supplier  possibly exceptional value supplier
      * @param <V>       value type
      *
      * @return  a new instance containing the supplied
-     *          value or a runtime exception
+     *          value or an exception
      *
      * @throws NullPointerException     if supplier is {@code null}
      */
-    public static <V> ThrowsOr<V> result(Supplier<@NullOr V> supplier)
+    public static <V> ThrowsOr<V> result(CheckedSupplier<@NullOr V, ? extends Exception> supplier)
     {
         Objects.requireNonNull(supplier, "supplier");
         try { return maybe(supplier.get()); }
-        catch (RuntimeException e) { return raise(e); }
-    }
-
-    /**
-     * Converts from an {@code Optional} to a new
-     * {@code ThrowsOr} instance containing either
-     * the optional's value or the supplied exception
-     * if it's empty.
-     *
-     * @param optional              an optional
-     * @param exceptionSupplier     exception supplier
-     * @param <V>                   value type
-     *
-     * @return  a new instance containing the supplied
-     *          optional's value or the supplied exception
-     *
-     * @throws NullPointerException     if any arguments are {@code null} or
-     *                                  a {@code null} exception is supplied
-     */
-    @SuppressWarnings("OptionalUsedAsFieldOrParameterType")
-    public static <V> ThrowsOr<V> present(Optional<V> optional, Supplier<Throwable> exceptionSupplier)
-    {
-        Objects.requireNonNull(optional, "optional");
-        Objects.requireNonNull(exceptionSupplier, "exceptionSupplier");
-        return optional.map(ThrowsOr::value).orElseGet(() -> raise(exceptionSupplier));
+        catch (Exception e) { return raise(e); }
     }
 
     private final @NullOr V value;

src/main/java/com/rezzedup/util/exceptional/checked/CheckedBiConsumer.java

@@ -13,6 +13,7 @@
 import java.util.function.BiConsumer;
 
 /**
+ * {@code BiConsumer} that can throw checked exceptions.
  *
  * @param <T>   first argument type
  * @param <U>   second argument type
@@ -23,6 +24,17 @@
 @FunctionalInterface
 public interface CheckedBiConsumer<T, U, E extends Throwable>
 {
+    /**
+     * Converts a {@code CheckedBiConsumer} into a regular {@code BiConsumer}.
+     * Any caught exceptions will be rethrown with:
+     * {@link Rethrow#caught(Throwable)}
+     *
+     * @param consumer  the checked biconsumer
+     * @param <T>       first argument type
+     * @param <U>       second argument type
+     *
+     * @return  the CheckedBiConsumer wrapped by an unchecked BiConsumer
+     */
     static <T, U> BiConsumer<T, U> unchecked(CheckedBiConsumer<T, U, ? extends Exception> consumer)
     {
         Objects.requireNonNull(consumer, "consumer");
@@ -34,5 +46,12 @@ static <T, U> BiConsumer<T, U> unchecked(CheckedBiConsumer<T, U, ? extends Excep
         };
     }
 
+    /**
+     * Performs this operation on the given arguments.
+     *
+     * @param t     the first input argument
+     * @param u     the second input argument
+     * @throws E    a checked exception
+     */
     void accept(T t, U u) throws E;
 }

src/main/java/com/rezzedup/util/exceptional/checked/CheckedBiFunction.java

@@ -13,6 +13,7 @@
 import java.util.function.BiFunction;
 
 /**
+ * {@code BiFunction} that can throw checked exceptions.
  *
  * @param <T>   first argument type
  * @param <U>   second argument type
@@ -24,6 +25,18 @@
 @FunctionalInterface
 public interface CheckedBiFunction<T, U, R, E extends Throwable>
 {
+    /**
+     * Converts a {@code CheckedBiFunction} into a regular {@code BiFunction}.
+     * Any caught exceptions will be rethrown with:
+     * {@link Rethrow#caught(Throwable)}
+     *
+     * @param function  the checked bifunction
+     * @param <T>       first argument type
+     * @param <U>       second argument type
+     * @param <R>       return type
+     *
+     * @return  the CheckedBiFunction wrapped by an unchecked BiFunction
+     */
     static <T, U, R> BiFunction<T, U, R> unchecked(CheckedBiFunction<T, U, R, ? extends Exception> function)
     {
         Objects.requireNonNull(function, "function");
@@ -35,5 +48,13 @@ static <T, U, R> BiFunction<T, U, R> unchecked(CheckedBiFunction<T, U, R, ? exte
         };
     }
 
+    /**
+     * Applies this function to the given arguments.
+     *
+     * @param t     the first argument
+     * @param u     the second argument
+     * @return      the function result
+     * @throws E    a checked exception
+     */
     R accept(T t, U u) throws E;
 }

src/main/java/com/rezzedup/util/exceptional/checked/CheckedConsumer.java

@@ -13,6 +13,7 @@
 import java.util.function.Consumer;
 
 /**
+ * {@code Consumer} that can throw checked exceptions.
  *
  * @param <T>   argument type
  * @param <E>   exception type
@@ -22,6 +23,16 @@
 @FunctionalInterface
 public interface CheckedConsumer<T, E extends Throwable>
 {
+    /**
+     * Converts a {@code CheckedConsumer} into a regular {@code Consumer}.
+     * Any caught exceptions will be rethrown with:
+     * {@link Rethrow#caught(Throwable)}
+     *
+     * @param consumer  the checked consumer
+     * @param <T>       argument type
+     *
+     * @return  the CheckedConsumer wrapped by an unchecked Consumer
+     */
     static <T> Consumer<T> unchecked(CheckedConsumer<T, ? extends Exception> consumer)
     {
         Objects.requireNonNull(consumer, "consumer");
@@ -33,5 +44,11 @@ static <T> Consumer<T> unchecked(CheckedConsumer<T, ? extends Exception> consume
         };
     }
 
+    /**
+     * Performs this operation on the given argument.
+     *
+     * @param t     the argument
+     * @throws E    a checked exception
+     */
     void accept(T t) throws E;
 }

src/main/java/com/rezzedup/util/exceptional/checked/CheckedFunction.java

@@ -13,6 +13,7 @@
 import java.util.function.Function;
 
 /**
+ * {@code Function} that can throw checked exceptions.
  *
  * @param <T>   argument type
  * @param <R>   return type
@@ -23,6 +24,17 @@
 @FunctionalInterface
 public interface CheckedFunction<T, R, E extends Throwable>
 {
+    /**
+     * Converts a {@code CheckedFunction} into a regular {@code Function}.
+     * Any caught exceptions will be rethrown with:
+     * {@link Rethrow#caught(Throwable)}
+     *
+     * @param function  the checked function
+     * @param <T>       argument type
+     * @param <R>       return type
+     *
+     * @return  the CheckedFunction wrapped by an unchecked Function
+     */
     static <T, R> Function<T, R> unchecked(CheckedFunction<T, R, ? extends Exception> function)
     {
         Objects.requireNonNull(function, "function");
@@ -34,5 +46,12 @@ static <T, R> Function<T, R> unchecked(CheckedFunction<T, R, ? extends Exception
         };
     }
 
+    /**
+     * Applies this function to the given argument.
+     *
+     * @param t     the function argument
+     * @return      the function result
+     * @throws E    a checked exception
+     */
     R apply(T t) throws E;
 }

src/main/java/com/rezzedup/util/exceptional/checked/CheckedRunnable.java

@@ -12,13 +12,24 @@
 import java.util.Objects;
 
 /**
+ * {@code Runnable} that can throw checked exceptions.
+ *
  * @param <E>   exception type
  *
  * @see Runnable
  */
 @FunctionalInterface
 public interface CheckedRunnable<E extends Throwable>
 {
+    /**
+     * Converts a {@code CheckedRunnable} into a regular {@code Runnable}.
+     * Any caught exceptions will be rethrown with:
+     * {@link Rethrow#caught(Throwable)}
+     *
+     * @param runnable  the checked runnable
+     *
+     * @return  the CheckedRunnable wrapped by an unchecked Runnable
+     */
     static Runnable unchecked(CheckedRunnable<? extends Exception> runnable)
     {
         Objects.requireNonNull(runnable, "runnable");
@@ -30,5 +41,10 @@ static Runnable unchecked(CheckedRunnable<? extends Exception> runnable)
         };
     }
 
+    /**
+     * Runs.
+     *
+     * @throws E    a checked exception
+     */
     void run() throws E;
 }

src/main/java/com/rezzedup/util/exceptional/checked/CheckedSupplier.java

@@ -13,6 +13,7 @@
 import java.util.function.Supplier;
 
 /**
+ * {@code Supplier} that can throw checked exceptions.
  *
  * @param <T>   return type
  * @param <E>   exception type
@@ -22,6 +23,16 @@
 @FunctionalInterface
 public interface CheckedSupplier<T, E extends Throwable>
 {
+    /**
+     * Converts a {@code CheckedSupplier} into a regular {@code Supplier}.
+     * Any caught exceptions will be rethrown with:
+     * {@link Rethrow#caught(Throwable)}
+     *
+     * @param supplier  the checked supplier
+     * @param <T>       return type
+     *
+     * @return  the CheckedSupplier wrapped by an unchecked Supplier
+     */
     static <T> Supplier<T> unchecked(CheckedSupplier<T, ? extends Exception> supplier)
     {
         Objects.requireNonNull(supplier, "supplier");
@@ -33,5 +44,11 @@ static <T> Supplier<T> unchecked(CheckedSupplier<T, ? extends Exception> supplie
         };
     }
 
+    /**
+     * Gets a result.
+     *
+     * @return      a result
+     * @throws E    a checked exception
+     */
     T get() throws E;
 }

src/main/java/com/rezzedup/util/exceptional/checked/package-info.java

@@ -5,6 +5,9 @@
  * License, v. 2.0. If a copy of the MPL was not distributed with this
  * file, You can obtain one at http://mozilla.org/MPL/2.0/.
  */
+/**
+ * Checked versions of common functional interfaces.
+ */
 @NonNullPackage
 package com.rezzedup.util.exceptional.checked;