Skip to content

Commit

Permalink
docs: improve apidoc 📚
Browse files Browse the repository at this point in the history
  • Loading branch information
@oldratlee
oldratlee committed Apr 24, 2024
1 parent cda112e commit d23ad7d
Show file tree
Hide file tree
Showing 5 changed files with 36 additions and 38 deletions.
12 changes: 6 additions & 6 deletions cffu-core/src/main/java/io/foldright/cffu/Cffu.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -1330,7 +1330,7 @@ public T join() {
* Waits if necessary for at most the given time for the computation to complete,
* and then retrieves its result value when complete, or throws an (unchecked) exception if completed exceptionally.
* <p>
* <b><i>NOTE:<br></i></b>
* <strong>NOTE:<br></strong>
* call this method
* <p>
* {@code result = cffu.join(timeout, unit);}
Expand All @@ -1342,7 +1342,7 @@ public T join() {
* .join();
* }</pre>
*
* <b><i>CAUTION:<br></i></b>
* <strong>CAUTION:<br></strong>
* if the wait timed out, this method throws an (unchecked) {@link CompletionException}
* with the {@link TimeoutException} as its cause;
* NOT throws a (checked) {@link TimeoutException} like {@link #get(long, TimeUnit)}.
Expand Down Expand Up @@ -1482,7 +1482,7 @@ public boolean isCancelled() {
* Returns the computation state, this method just invoke without java version compatibility logic,
* if you need this function backport into old {@code java 18-}, use {@link #cffuState()} instead.
* <p>
* <b><i>NOTE:<br></i></b>
* <strong>NOTE:<br></strong>
* {@link CompletableFuture#state} is new method since Java 19,
* this method should have compatibility logic for old Java version;
* But the return type {@link Future.State} is also added since Java 19,
Expand Down Expand Up @@ -1610,7 +1610,7 @@ public boolean cancel(boolean mayInterruptIfRunning) {
* If this CompletableFuture completes exceptionally, then the returned CompletionStage completes
* exceptionally with a CompletionException with this exception as cause.
* <p>
* <b><i>CAUTION:<br></i></b>
* <strong>CAUTION:<br></strong>
* if run on old Java 8, just return a Cffu with
* a *normal* underlying CompletableFuture which is NOT with a *minimal* CompletionStage.
* <p>
Expand Down Expand Up @@ -1839,11 +1839,11 @@ public void obtrudeException(Throwable ex) {
* Subclasses of CompletableFuture should normally override this method to return an instance of the same class
* as this CompletableFuture. The default implementation returns an instance of class CompletableFuture.
* <p>
* <b><i>NOTE:<br></i></b>
* <strong>NOTE:<br></strong>
* this method existed mainly for API compatibility to {@code CompletableFuture},
* prefer {@link CffuFactory#newIncompleteCffu()}.
* <p>
* <b><i>CAUTION:<br></i></b>
* <storng>CAUTION:<br></storng>
* for minimal stage instance({@link #isMinimalStage()}), if run on old Java 8,
* just return a Cffu with a *normal* underlying CompletableFuture which is NOT with a *minimal* CompletionStage.
*
Expand Down
6 changes: 3 additions & 3 deletions cffu-core/src/main/java/io/foldright/cffu/CffuFactory.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -92,7 +92,7 @@ public <T> Cffu<T> completedFuture(@Nullable T value) {
* Returns a new CompletionStage that is already completed with the given value
* and supports only those methods in interface {@link CompletionStage}.
* <p>
* <b><i>CAUTION:<br></i></b>
* <strong>CAUTION:<br></strong>
* if run on old Java 8, just return a Cffu with
* a *normal* underlying CompletableFuture which is NOT with a *minimal* CompletionStage.
*
Expand Down Expand Up @@ -124,7 +124,7 @@ public <T> Cffu<T> failedFuture(Throwable ex) {
* Returns a new CompletionStage that is already completed exceptionally
* with the given exception and supports only those methods in interface {@link CompletionStage}.
* <p>
* <b><i>CAUTION:<br></i></b>
* <strong>CAUTION:<br></strong>
* if run on old Java 8, just return a Cffu with
* a *normal* underlying CompletableFuture which is NOT with a *minimal* CompletionStage.
*
Expand Down Expand Up @@ -247,7 +247,7 @@ public <T> Cffu<T> newIncompleteCffu() {
* for {@link CompletableFuture} class instances,
* {@link Cffu#cffuUnwrap()} is the inverse operation to this method.
* <p>
* <b><i>NOTE</i></b>, keep input stage unchanged if possible when wrap:<br>
* <strong>NOTE</strong>, keep input stage unchanged if possible when wrap:<br>
* <ol>
* <li>if input stage is a {@link Cffu}, re-wrapped with the config of
* this {@link CffuFactory} from {@link CffuFactoryBuilder} by {@link Cffu#resetCffuFactory(CffuFactory)}.
Expand Down
20 changes: 10 additions & 10 deletions cffu-core/src/main/java/io/foldright/cffu/CompletableFutureUtils.java
View file
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@


/**
* This class contains the enhanced methods for {@link CompletableFuture}.
* This class contains the enhanced and backport methods for {@link CompletableFuture}.
*
* @author Jerry Lee (oldratlee at gmail dot com)
*/
Expand Down Expand Up @@ -462,8 +462,8 @@ public static <T1, T2, T3, T4, T5> CompletableFuture<Tuple5<T1, T2, T3, T4, T5>>
}

////////////////////////////////////////////////////////////////////////////////
//# Backport CF methods
// compatibility for low Java version
//# Backport CF static methods
// compatibility for low Java versions
////////////////////////////////////////////////////////////////////////////////

//# Factory methods
Expand All @@ -489,7 +489,7 @@ public static <T> CompletableFuture<T> failedFuture(Throwable ex) {
* Returns a new CompletionStage that is already completed with the given value
* and supports only those methods in interface {@link CompletionStage}.
* <p>
* <b><i>CAUTION:<br></i></b>
* <strong>CAUTION:<br></strong>
* if run on old Java 8, just return a *normal* CompletableFuture which is NOT with a *minimal* CompletionStage.
*
* @param value the value
Expand All @@ -508,7 +508,7 @@ public static <T> CompletionStage<T> completedStage(@Nullable T value) {
* Returns a new CompletionStage that is already completed exceptionally with
* the given exception and supports only those methods in interface {@link CompletionStage}.
* <p>
* <b><i>CAUTION:<br></i></b>
* <strong>CAUTION:<br></strong>
* if run on old Java 8, just return a *normal* CompletableFuture which is NOT with a *minimal* CompletionStage.
*
* @param ex the exception
Expand Down Expand Up @@ -562,7 +562,7 @@ public static Executor delayedExecutor(long delay, TimeUnit unit, Executor execu
}

////////////////////////////////////////
//# backport instance methods
//# Backport CF instance methods
////////////////////////////////////////

//# Error Handling methods of CompletionStage
Expand Down Expand Up @@ -718,7 +718,7 @@ public static <T> CompletableFuture<T> exceptionallyComposeAsync(
* Waits if necessary for at most the given time for the computation to complete,
* and then retrieves its result value when complete, or throws an (unchecked) exception if completed exceptionally.
* <p>
* <b><i>NOTE:<br></i></b>
* <strong>NOTE:<br></strong>
* call this method
* <p>
* {@code result = CompletableFutureUtils.join(cf, timeout, unit);}
Expand All @@ -730,7 +730,7 @@ public static <T> CompletableFuture<T> exceptionallyComposeAsync(
* .join();
* }</pre>
*
* <b><i>CAUTION:<br></i></b>
* <strong>CAUTION:<br></strong>
* if the wait timed out, this method throws an (unchecked) {@link CompletionException}
* with the {@link TimeoutException} as its cause;
* NOT throws a (checked) {@link TimeoutException} like {@link CompletableFuture#get(long, TimeUnit)}.
Expand Down Expand Up @@ -913,7 +913,7 @@ public static <T> CompletableFuture<T> completeAsync(
* If given CompletableFuture completes exceptionally, then the returned CompletionStage completes exceptionally
* with a CompletionException with given exception as cause.
* <p>
* <b><i>CAUTION:<br></i></b>
* <strong>CAUTION:<br></strong>
* if run on old Java 8, just return a *normal* CompletableFuture which is NOT with a *minimal* CompletionStage.
*
* @return the new CompletionStage
Expand Down Expand Up @@ -963,7 +963,7 @@ public static <T, U> CompletableFuture<U> newIncompleteFuture(CompletableFuture<
* Returns the default Executor used for async methods that do not specify an Executor.
* This class uses the {@link ForkJoinPool#commonPool()} if it supports more than one parallel thread,
* or else an Executor using one thread per async task.<br>
* <b><i>CAUTION:</i></b>This executor may be not suitable for common biz use(io intensive).
* <strong>CAUTION:</strong> This executor may be not suitable for common biz use(io intensive).
*
* @return the executor
*/
Expand Down
16 changes: 8 additions & 8 deletions cffu-kotlin/src/main/java/io/foldright/cffu/kotlin/CffuExtensions.kt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -64,7 +64,7 @@ private const val ERROR_MSG_FOR_COLL = "no cffuFactory argument provided when th
private const val ERROR_MSG_FOR_ARRAY = "no cffuFactory argument provided when this array is empty"

/**
* Returns a new Cffu with the results in the <strong>same order</strong> of all the given Cffus,
* Returns a new Cffu with the results in the **same order** of all the given Cffus,
* the new Cffu is completed when all the given Cffus complete.
* If any of the given Cffus complete exceptionally, then the returned Cffu
* also does so, with a CompletionException holding this exception as its cause.
Expand All @@ -86,7 +86,7 @@ fun <T> Collection<Cffu<out T>>.allResultsOfCffu(cffuFactory: CffuFactory = ABSE
}

/**
* Returns a new Cffu with the results in the <strong>same order</strong> of all the given Cffus,
* Returns a new Cffu with the results in the **same order** of all the given Cffus,
* the new Cffu is completed when all the given Cffus complete.
* If any of the given Cffus complete exceptionally, then the returned Cffu
* also does so, with a CompletionException holding this exception as its cause.
Expand All @@ -108,7 +108,7 @@ fun <T> Array<out Cffu<out T>>.allResultsOfCffu(cffuFactory: CffuFactory = ABSEN
}

/**
* Returns a new Cffu with the results in the <strong>same order</strong> of all the given CompletableFutures,
* Returns a new Cffu with the results in the **same order** of all the given CompletableFutures,
* the new Cffu is completed when all the given CompletableFutures complete.
* If any of the given CompletableFutures complete exceptionally, then the returned Cffu
* also does so, with a CompletionException holding this exception as its cause.
Expand All @@ -125,7 +125,7 @@ fun <T> Collection<CompletableFuture<out T>>.allResultsOfCffu(cffuFactory: CffuF
cffuFactory.allResultsOf(*this.toTypedArray())

/**
* Returns a new Cffu with the results in the <strong>same order</strong> of all the given CompletableFutures,
* Returns a new Cffu with the results in the **same order** of all the given CompletableFutures,
* the new Cffu is completed when all the given CompletableFutures complete.
* If any of the given CompletableFutures complete exceptionally, then the returned Cffu
* also does so, with a CompletionException holding this exception as its cause.
Expand Down Expand Up @@ -219,7 +219,7 @@ fun Array<out CompletableFuture<*>>.allOfCffu(cffuFactory: CffuFactory): Cffu<Vo
cffuFactory.allOf(*this)

/**
* Returns a new Cffu with the results in the <strong>same order</strong> of all the given Cffus,
* Returns a new Cffu with the results in the **same order** of all the given Cffus,
* the new Cffu success when all the given Cffus success.
* If any of the given Cffus complete exceptionally, then the returned Cffu
* also does so *without* waiting other incomplete given Cffus,
Expand All @@ -242,7 +242,7 @@ fun <T> Collection<Cffu<out T>>.allResultsOfFastFailCffu(cffuFactory: CffuFactor
}

/**
* Returns a new Cffu with the results in the <strong>same order</strong> of all the given Cffus,
* Returns a new Cffu with the results in the **same order** of all the given Cffus,
* the new Cffu success when all the given Cffus success.
* If any of the given Cffus complete exceptionally, then the returned Cffu
* also does so *without* waiting other incomplete given Cffus,
Expand All @@ -265,7 +265,7 @@ fun <T> Array<out Cffu<out T>>.allResultsOfFastFailCffu(cffuFactory: CffuFactory
}

/**
* Returns a new Cffu with the results in the <strong>same order</strong> of all the given CompletableFutures,
* Returns a new Cffu with the results in the **same order** of all the given CompletableFutures,
* the new Cffu success when all the given CompletableFutures success.
* If any of the given CompletableFutures complete exceptionally, then the returned Cffu
* also does so *without* waiting other incomplete given CompletableFutures,
Expand All @@ -283,7 +283,7 @@ fun <T> Collection<CompletableFuture<out T>>.allResultsOfFastFailCffu(cffuFactor
cffuFactory.allResultsOfFastFail(*this.toTypedArray())

/**
* Returns a new Cffu with the results in the <strong>same order</strong> of all the given CompletableFutures,
* Returns a new Cffu with the results in the **same order** of all the given CompletableFutures,
* the new Cffu success when all the given CompletableFutures success.
* If any of the given CompletableFutures complete exceptionally, then the returned Cffu
* also does so *without* waiting other incomplete given CompletableFutures,
Expand Down
20 changes: 9 additions & 11 deletions cffu-kotlin/src/main/java/io/foldright/cffu/kotlin/CompletableFutureExtensions.kt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,7 @@ import java.util.function.Supplier
////////////////////////////////////////

/**
* Returns a new CompletableFuture with the results in the <strong>same order</strong> of all the given
* Returns a new CompletableFuture with the results in the **same order** of all the given
* CompletableFutures, the returned new CompletableFuture is completed when all the given CompletableFutures complete.
* If any of the given CompletableFutures complete exceptionally, then the returned CompletableFuture
* also does so, with a CompletionException holding this exception as its cause.
Expand All @@ -48,7 +48,7 @@ fun <T> Collection<CompletableFuture<out T>>.allResultsOfCompletableFuture(): Co
CompletableFutureUtils.allResultsOf(*this.toTypedArray())

/**
* Returns a new CompletableFuture with the results in the <strong>same order</strong> of all the given
* Returns a new CompletableFuture with the results in the **same order** of all the given
* CompletableFutures, the returned new CompletableFuture is completed when all the given CompletableFutures complete.
* If any of the given CompletableFutures complete exceptionally, then the returned CompletableFuture
* also does so, with a CompletionException holding this exception as its cause.
Expand Down Expand Up @@ -109,7 +109,7 @@ fun Array<out CompletableFuture<*>>.allOfCompletableFuture(): CompletableFuture<
CompletableFuture.allOf(*this)

/**
* Returns a new CompletableFuture with the results in the <strong>same order</strong> of all the given
* Returns a new CompletableFuture with the results in the **same order** of all the given
* CompletableFutures, the new CompletableFuture success when all the given CompletableFutures success.
* If any of the given CompletableFutures complete exceptionally, then the returned CompletableFuture
* also does so *without* waiting other incomplete given CompletableFutures,
Expand All @@ -127,7 +127,7 @@ fun <T> Collection<CompletableFuture<out T>>.allResultsOfFastFailCompletableFutu
CompletableFutureUtils.allResultsOfFastFail(*this.toTypedArray())

/**
* Returns a new CompletableFuture with the results in the <strong>same order</strong> of all the given
* Returns a new CompletableFuture with the results in the **same order** of all the given
* CompletableFutures, the new CompletableFuture success when all the given CompletableFutures success.
* If any of the given CompletableFutures complete exceptionally, then the returned CompletableFuture
* also does so *without* waiting other incomplete given CompletableFutures,
Expand Down Expand Up @@ -491,9 +491,8 @@ fun <T> CompletableFuture<T>.exceptionallyComposeAsync(
/**
* Waits if necessary for at most the given time for the computation to complete,
* and then retrieves its result value when complete, or throws an (unchecked) exception if completed exceptionally.
* <p>
* <b><i>NOTE:<br></i></b>
* call this method
*
* **NOTE:** call this method
*
* `result = CompletableFutureUtils.join(cf, timeout, unit);`
*
Expand All @@ -506,8 +505,7 @@ fun <T> CompletableFuture<T>.exceptionallyComposeAsync(
* }
* ```
*
* <b><i>CAUTION:<br></i></b>
* if the wait timed out, this method throws an (unchecked) CompletionException with the TimeoutException as its cause;
* **CAUTION:** if the wait timed out, this method throws an (unchecked) CompletionException with the TimeoutException as its cause;
* NOT throws a (checked) TimeoutException like [CompletableFuture.get].
*
* @param timeout the maximum time to wait
Expand All @@ -521,7 +519,7 @@ fun <T> CompletableFuture<T>.join(timeout: Long, unit: TimeUnit): T =

/**
* Returns the computed result, without waiting.
* <p>
*
* This method is for cases where the caller knows that the task has already completed successfully,
* for example when filtering a stream of Future objects for the successful tasks
* and using a mapping operation to obtain a stream of results.
Expand All @@ -540,7 +538,7 @@ fun <T> CompletableFuture<T>.resultNow(): T =

/**
* Returns the exception thrown by the task, without waiting.
* <p>
*
* This method is for cases where the caller knows that the task has already completed with an exception.
*
* @return the exception thrown by the task
Expand Down

0 comments on commit d23ad7d

Please sign in to comment.