support checked exceptions; javadocs and cleanup by @jacopo-cavallarin

try-monad/pom.xml

@@ -6,7 +6,7 @@
 
     <groupId>io.github.anbonifacio</groupId>
     <artifactId>try-monad</artifactId>
-    <version>1.0.0</version>
+    <version>1.0.1</version>
 
     <name>Java Try monad</name>
     <url>https://github.com/anbonifacio/java-try-monad</url>

try-monad/src/main/java/io/github/anbonifacio/try_monad/Failure.java

@@ -23,19 +23,19 @@
 import static java.util.concurrent.CompletableFuture.failedStage;
 
 /**
- * The type Failure.
+ * The failed result of some operation. In this context, <em>failure</em> means that the operation
+ * threw an exception.
  *
- * @param <T>  the type parameter
+ * @implNote this record can never contain a <b>fatal</b> exception;
+ * see {@link Failure#isFatal(Throwable)} for more information.
+ *
+ * @param cause the exception that was caught while executing the operation (never {@code null})
+ * @param <T> the return type of the operation (or {@link Void} if the operation is {@code void})
  */
 public record Failure<T>(Throwable cause) implements Try<T>, Serializable {
     @Serial
     private static final long serialVersionUID = 1L;
 
-    /**
-     * Instantiates a new Failure.
-     *
-     * @param cause the cause
-     */
     public Failure {
         Objects.requireNonNull(cause, "cause is null");
         if (isFatal(cause)) {
@@ -76,11 +76,6 @@ public Optional<T> getSuccess() {
         return Optional.empty();
     }
 
-    @Override
-    public Optional<T> toOptional() {
-        return Optional.empty();
-    }
-
     @Override
     public CompletionStage<T> toCompletionStage() {
         return failedStage(cause);
@@ -120,12 +115,19 @@ public Try<T> recoverWith(Function<? super Throwable, Try<T>> fn) {
         }
     }
 
+    /**
+     * @return {@code true} if {@code throwable} is fatal and should never be caught,
+     * {@code false} otherwise
+     */
     private static boolean isFatal(Throwable throwable) {
         return throwable instanceof InterruptedException
                 || throwable instanceof LinkageError
                 || throwable instanceof VirtualMachineError;
     }
 
+    /**
+     * Throws a checked exception as if it were unchecked by tricking the compiler
+     */
     @SuppressWarnings("unchecked")
     private static <T extends Throwable> void sneakyThrow(Throwable t) throws T {
         throw (T) t;

try-monad/src/main/java/io/github/anbonifacio/try_monad/Success.java

@@ -23,9 +23,11 @@
 import static java.util.concurrent.CompletableFuture.completedStage;
 
 /**
- * The type Success.
+ * The successful result of some operation. In this context, <em>success</em> means that the operation
+ * completed without throwing any exception.
  *
- * @param <T>  the type parameter
+ * @param value the result of the operation (or {@code null} if the operation is {@code void})
+ * @param <T> the type of the result (or {@link Void} if the operation is {@code void})
  */
 public record Success<T>(T value) implements Try<T>, Serializable {
     @Serial
@@ -71,11 +73,6 @@ public Optional<T> getSuccess() {
         return Optional.of(value);
     }
 
-    @Override
-    public Optional<T> toOptional() {
-        return Optional.of(value);
-    }
-
     @Override
     public CompletionStage<T> toCompletionStage() {
         return completedStage(value);