From 0918a9d9d5e1145af02c1d2c402783e5e7d67abb Mon Sep 17 00:00:00 2001
From: Jerry Lee <oldratlee@gmail.com>
Date: Sat, 17 Aug 2024 20:03:54 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20improve=20javadoc=20of=20`exceptionally?=
 =?UTF-8?q?*`=20methods,=20add=20best=20practice=20recommendation=20?=
 =?UTF-8?q?=F0=9F=92=A3=20=F0=9F=93=9A?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../src/main/java/io/foldright/cffu/Cffu.java | 30 +++++++++++++++++++
 .../cffu/CompletableFutureUtils.java          | 25 ++++++++++++++++
 2 files changed, 55 insertions(+)

diff --git a/cffu-core/src/main/java/io/foldright/cffu/Cffu.java b/cffu-core/src/main/java/io/foldright/cffu/Cffu.java
index d2618923..a80fad7e 100644
--- a/cffu-core/src/main/java/io/foldright/cffu/Cffu.java
+++ b/cffu-core/src/main/java/io/foldright/cffu/Cffu.java
@@ -1785,10 +1785,15 @@ public <X extends Throwable> Cffu<T> catchingAsync(
      * is executed with this stage's exception as the argument to the supplied function.
      * Otherwise, if this stage completes normally,
      * then the returned stage also completes normally with the same value.
+     * <p>
+     * Just as catching {@code Throwable} is not best practice in general, this method handles the {@code Throwable};
+     * <strong>Strong recommend</strong> using {@link #catching(Class, Function)}
+     * instead in your biz application.
      *
      * @param fn the function to use to compute the value of the returned Cffu
      *           if this Cffu completed exceptionally
      * @return the new Cffu
+     * @see #catching(Class, Function)
      */
     @Override
     public Cffu<T> exceptionally(Function<Throwable, ? extends T> fn) {
@@ -1801,10 +1806,15 @@ public Cffu<T> exceptionally(Function<Throwable, ? extends T> fn) {
      * using {@link #defaultExecutor()}.
      * Otherwise, if this stage completes normally,
      * then the returned stage also completes normally with the same value.
+     * <p>
+     * Just as catching {@code Throwable} is not best practice in general, this method handles the {@code Throwable};
+     * <strong>Strong recommend</strong> using {@link #catchingAsync(Class, Function)}
+     * instead in your biz application.
      *
      * @param fn the function to use to compute the value of the returned Cffu
      *           if this Cffu completed exceptionally
      * @return the new Cffu
+     * @see #catchingAsync(Class, Function)
      */
     @Override
     public Cffu<T> exceptionallyAsync(Function<Throwable, ? extends T> fn) {
@@ -1816,11 +1826,16 @@ public Cffu<T> exceptionallyAsync(Function<Throwable, ? extends T> fn) {
      * is executed with this stage's exception as the argument to the supplied function,
      * using the supplied Executor. Otherwise, if this stage completes normally,
      * then the returned stage also completes normally with the same value.
+     * <p>
+     * Just as catching {@code Throwable} is not best practice in general, this method handles the {@code Throwable};
+     * <strong>Strong recommend</strong> using {@link #catchingAsync(Class, Function, Executor)}
+     * instead in your biz application.
      *
      * @param fn       the function to use to compute the value of the returned Cffu
      *                 if this Cffu completed exceptionally
      * @param executor the executor to use for asynchronous execution
      * @return the new Cffu
+     * @see #catchingAsync(Class, Function, Executor)
      */
     @Override
     public Cffu<T> exceptionallyAsync(Function<Throwable, ? extends T> fn, Executor executor) {
@@ -2091,10 +2106,15 @@ public <X extends Throwable> Cffu<T> catchingComposeAsync(
     /**
      * Returns a new CompletionStage that, when this stage completes exceptionally,
      * is composed using the results of the supplied function applied to this stage's exception.
+     * <p>
+     * Just as catching {@code Throwable} is not best practice in general, this method handles the {@code Throwable};
+     * <strong>Strong recommend</strong> using {@link #catchingCompose(Class, Function)}
+     * instead in your biz application.
      *
      * @param fn the function to use to compute the returned CompletionStage
      *           if this CompletionStage completed exceptionally
      * @return the new CompletionStage
+     * @see #catchingCompose(Class, Function)
      */
     @Override
     public Cffu<T> exceptionallyCompose(Function<Throwable, ? extends CompletionStage<T>> fn) {
@@ -2105,10 +2125,15 @@ public Cffu<T> exceptionallyCompose(Function<Throwable, ? extends CompletionStag
      * Returns a new Cffu that, when this stage completes exceptionally,
      * is composed using the results of the supplied function applied to this stage's exception,
      * using {@link #defaultExecutor()}.
+     * <p>
+     * Just as catching {@code Throwable} is not best practice in general, this method handles the {@code Throwable};
+     * <strong>Strong recommend</strong> using {@link #catchingComposeAsync(Class, Function)}
+     * instead in your biz application.
      *
      * @param fn the function to use to compute the returned CompletionStage
      *           if this Cffu completed exceptionally
      * @return the new Cffu
+     * @see #catchingComposeAsync(Class, Function)
      */
     @Override
     public Cffu<T> exceptionallyComposeAsync(Function<Throwable, ? extends CompletionStage<T>> fn) {
@@ -2119,11 +2144,16 @@ public Cffu<T> exceptionallyComposeAsync(Function<Throwable, ? extends Completio
      * Returns a new Cffu that, when this stage completes exceptionally,
      * is composed using the results of the supplied function applied to this stage's exception,
      * using the supplied Executor.
+     * <p>
+     * Just as catching {@code Throwable} is not best practice in general, this method handles the {@code Throwable};
+     * <strong>Strong recommend</strong> using {@link #catchingComposeAsync(Class, Function, Executor)}
+     * instead in your biz application.
      *
      * @param fn       the function to use to compute the returned CompletionStage
      *                 if this Cffu completed exceptionally
      * @param executor the executor to use for asynchronous execution
      * @return the new Cffu
+     * @see #catchingComposeAsync(Class, Function, Executor)
      */
     @Override
     public Cffu<T> exceptionallyComposeAsync(
diff --git a/cffu-core/src/main/java/io/foldright/cffu/CompletableFutureUtils.java b/cffu-core/src/main/java/io/foldright/cffu/CompletableFutureUtils.java
index 40346696..199c941e 100644
--- a/cffu-core/src/main/java/io/foldright/cffu/CompletableFutureUtils.java
+++ b/cffu-core/src/main/java/io/foldright/cffu/CompletableFutureUtils.java
@@ -3634,10 +3634,15 @@ C catchingAsync(C cfThis, Class<X> exceptionType, Function<? super X, ? extends
      * stage's exception as the argument to the supplied function, using given stage's
      * default asynchronous execution facility. Otherwise, if given stage completes normally,
      * then the returned stage also completes normally with the same value.
+     * <p>
+     * Just as catching {@code Throwable} is not best practice in general, this method handles the {@code Throwable};
+     * <strong>Strong recommend</strong> using {@link #catchingAsync(CompletionStage, Class, Function)}
+     * instead in your biz application.
      *
      * @param fn the function to use to compute the value of the returned CompletableFuture
      *           if given CompletionStage completed exceptionally
      * @return the new CompletableFuture
+     * @see #catchingAsync(CompletionStage, Class, Function)
      */
     public static <T, C extends CompletionStage<? super T>>
     C exceptionallyAsync(C cfThis, Function<Throwable, ? extends T> fn) {
@@ -3648,11 +3653,16 @@ C exceptionallyAsync(C cfThis, Function<Throwable, ? extends T> fn) {
      * Returns a new CompletionStage that, when given stage completes exceptionally, is executed with given
      * stage's exception as the argument to the supplied function, using the supplied Executor. Otherwise,
      * if given stage completes normally, then the returned stage also completes normally with the same value.
+     * <p>
+     * Just as catching {@code Throwable} is not best practice in general, this method handles the {@code Throwable};
+     * <strong>Strong recommend</strong> using {@link #catchingAsync(CompletionStage, Class, Function, Executor)}
+     * instead in your biz application.
      *
      * @param fn       the function to use to compute the value of the returned CompletableFuture
      *                 if given CompletionStage completed exceptionally
      * @param executor the executor to use for asynchronous execution
      * @return the new CompletableFuture
+     * @see #catchingAsync(CompletionStage, Class, Function, Executor)
      */
     @SuppressWarnings("unchecked")
     public static <T, C extends CompletionStage<? super T>>
@@ -3940,10 +3950,15 @@ public static <T, X extends Throwable, C extends CompletionStage<? super T>> C c
     /**
      * Returns a new CompletableFuture that, when given CompletableFuture completes exceptionally,
      * is composed using the results of the supplied function applied to given stage's exception.
+     * <p>
+     * Just as catching {@code Throwable} is not best practice in general, this method handles the {@code Throwable};
+     * <strong>Strong recommend</strong> using {@link #catchingCompose(CompletionStage, Class, Function)}
+     * instead in your biz application.
      *
      * @param fn the function to use to compute the returned CompletableFuture
      *           if given CompletionStage completed exceptionally
      * @return the new CompletableFuture
+     * @see #catchingCompose(CompletionStage, Class, Function)
      */
     @SuppressWarnings({"unchecked", "rawtypes"})
     public static <T, C extends CompletionStage<? super T>>
@@ -3961,10 +3976,15 @@ C exceptionallyCompose(C cfThis, Function<Throwable, ? extends CompletionStage<T
      * Returns a new CompletableFuture that, when given CompletableFuture completes exceptionally,
      * is composed using the results of the supplied function applied to given stage's exception,
      * using given CompletableFuture's default asynchronous execution facility.
+     * <p>
+     * Just as catching {@code Throwable} is not best practice in general, this method handles the {@code Throwable};
+     * <strong>Strong recommend</strong> using {@link #catchingComposeAsync(CompletionStage, Class, Function)}
+     * instead in your biz application.
      *
      * @param fn the function to use to compute the returned CompletableFuture
      *           if given CompletionStage completed exceptionally
      * @return the new CompletableFuture
+     * @see #catchingComposeAsync(CompletionStage, Class, Function)
      */
     public static <T, C extends CompletionStage<? super T>>
     C exceptionallyComposeAsync(C cfThis, Function<Throwable, ? extends CompletionStage<T>> fn) {
@@ -3974,11 +3994,16 @@ C exceptionallyComposeAsync(C cfThis, Function<Throwable, ? extends CompletionSt
     /**
      * Returns a new CompletableFuture that, when given CompletableFuture completes exceptionally, is composed using
      * the results of the supplied function applied to given stage's exception, using the supplied Executor.
+     * <p>
+     * Just as catching {@code Throwable} is not best practice in general, this method handles the {@code Throwable};
+     * <strong>Strong recommend</strong> using {@link #catchingComposeAsync(CompletionStage, Class, Function, Executor)}
+     * instead in your biz application.
      *
      * @param fn       the function to use to compute the returned CompletableFuture
      *                 if given CompletionStage completed exceptionally
      * @param executor the executor to use for asynchronous execution
      * @return the new CompletableFuture
+     * @see #catchingComposeAsync(CompletionStage, Class, Function, Executor)
      */
     @SuppressWarnings({"unchecked", "rawtypes"})
     public static <T, C extends CompletionStage<? super T>>