Fxing JavaDoc-s

Author: vsilaev

src/main/java/net/tascalate/concurrent/AbstractCompletableTask.java

@@ -45,6 +45,7 @@
  * @author vsilaev
  *
  * @param <T>
+ *   a type of the successfully executed task result   
  */
 abstract class AbstractCompletableTask<T> extends PromiseAdapter<T> implements Promise<T> {
 

src/main/java/net/tascalate/concurrent/AbstractDelegatingPromise.java

@@ -30,7 +30,9 @@
  * @author vsilaev
  *
  * @param <T>
+ *   a type of the successfully resolved promise value   
  * @param <D>
+ *   a type of the concrete {@link CompletionStage} subclass
  */
 abstract public class AbstractDelegatingPromise<T, D extends CompletionStage<T>> implements Promise<T> {
     final protected D completionStage;

src/main/java/net/tascalate/concurrent/CompletablePromise.java

@@ -30,6 +30,7 @@
  * @author vsilaev
  *
  * @param <T>
+ *   a type of the successfully resolved promise value   
  */
 public class CompletablePromise<T> extends AbstractDelegatingPromise<T, CompletableFuture<T>> implements Promise<T> {
 

src/main/java/net/tascalate/concurrent/CompletableTask.java

@@ -26,6 +26,7 @@
  * @author vsilaev
  *
  * @param <T>
+ *   a type of the successfully executed task result   
  */
 public class CompletableTask<T> extends AbstractCompletableTask<T> implements RunnableFuture<T> {
 
@@ -63,9 +64,11 @@ public void run() {
      *  </pre>
      * All of <code>myMapper</code>, <code>myTransformer</code>, <code>myConsumer</code>, <code>myActtion</code> will be executed using <code>myExecutor</code>
      * 
+     * @param <T>
+     *   a type of the successfully executed task result 
      * @param value
-     *   a resolved value of the promise
-     * @param executor
+     *   a task result
+     * @param defaultExecutor
      *   a default {@link Executor} to run functions passed to async composition methods 
      *   (like <code>thenApplyAsync</code> / <code>thenAcceptAsync</code> / <code>whenCompleteAsync</code> etc.)
      * @return

src/main/java/net/tascalate/concurrent/Promise.java

@@ -31,6 +31,7 @@
  * @author vsilaev
  *
  * @param <T>
+ *   a type of the successfully resolved promise value   
  */
 public interface Promise<T> extends Future<T>, CompletionStage<T> {
 

src/main/java/net/tascalate/concurrent/PromiseAdapter.java

@@ -35,6 +35,7 @@
  * @author vsilaev
  *
  * @param <T>
+ *   a type of the successfully resolved promise value   
  */
 abstract public class PromiseAdapter<T> implements Promise<T> {
     protected static final Executor SAME_THREAD_EXECUTOR = new Executor() {

src/main/java/net/tascalate/concurrent/Promises.java

@@ -35,6 +35,8 @@ public class Promises {
 
     /**
      * Method to create a successfully resolved {@link Promise} with a value provided 
+     * @param <T>
+     *   a type of the value
      * @param value
      *   a value to wrap
      * @return 
@@ -61,6 +63,8 @@ public static Promise<?> failure(Throwable exception) {
 
     /**
      * Adapts a stage passed to the {@link Promise} API
+     * @param <T>
+     *   a type of the value
      * @param stage
      *   a {@link CompletionStage} to be wrapped
      * @return
@@ -111,7 +115,9 @@ public boolean cancel(boolean mayInterruptIfRunning) {
      * if any promise completed exceptionally, then resulting promise is resolved faulty as well.
      * <p>The resolved result of this promise contains a list of the resolved results of the {@link CompletionStage}-s passed as an 
      * argument at corresponding positions.
-     * <p>When resulting promise is resolved faulty, any remaining {@link CompletionStage}-s is cancelled.  
+     * <p>When resulting promise is resolved faulty, all remaining incomplete {@link CompletionStage}-s are cancelled.  
+     * @param <T>
+     *   a common supertype of the resulting values
      * @param promises
      *   an array of {@link CompletionStage}-s to combine
      * @return
@@ -127,7 +133,10 @@ public static <T> Promise<List<T>> all(final CompletionStage<? extends T>... pro
      * if all promises completed exceptionally, then resulting promise is resolved faulty as well.
      * <p>The resolved result of this promise contains a value of the first resolved result of the {@link CompletionStage}-s passed as an 
      * argument.
-     * <p>When resulting promise is resolved successfully, any remaining {@link CompletionStage}-s is cancelled.
+     * <p>When resulting promise is resolved successfully, all remaining incomplete {@link CompletionStage}-s are cancelled.
+     * 
+     * @param <T>
+     *   a common supertype of the resulting values 
      * @param promises
      *   an array of {@link CompletionStage}-s to combine
      * @return
@@ -144,7 +153,9 @@ public static <T> Promise<T> any(final CompletionStage<? extends T>... promises)
      * (unlike non-Strict variant, where exceptions are ignored if result is available at all).
      * <p>The resolved result of this promise contains a value of the first resolved result of the {@link CompletionStage}-s passed as an 
      * argument.
-     * <p>When resulting promise is resolved either successfully or faulty, any remaining {@link CompletionStage}-s is cancelled. 
+     * <p>When resulting promise is resolved either successfully or faulty, all remaining incomplete {@link CompletionStage}-s are cancelled. 
+     * @param <T>
+     *   a common supertype of the resulting values 
      * @param promises
      *   an array of {@link CompletionStage}-s to combine
      * @return
@@ -162,8 +173,10 @@ public static <T> Promise<T> anyStrict(final CompletionStage<? extends T>... pro
      * is resolved faulty.
      * <p>The resolved result of this promise contains a list of the resolved results of the {@link CompletionStage}-s passed as an 
      * argument at corresponding positions. Non-completed or completed exceptionally promises have <code>null</code> values.
-     * <p>When resulting promise is resolved successfully, any remaining {@link CompletionStage}-s is cancelled. 
+     * <p>When resulting promise is resolved successfully, all remaining incomplete {@link CompletionStage}-s are cancelled. 
      * 
+     * @param <T>
+     *   a common supertype of the resulting values 
      * @param minResultsCount
      *   a minimum number of promises that should be completed normally to resolve resulting promise successfully 
      * @param promises
@@ -184,8 +197,10 @@ public static <T> Promise<List<T>> atLeast(final int minResultsCount, final Comp
      * resulting promise is resolved faulty as well. 
      * <p>The resolved result of this promise contains a list of the resolved results of the {@link CompletionStage}-s passed as an 
      * argument at corresponding positions. Non-completed promises have <code>null</code> values.
-     * <p>When resulting promise is resolved either successfully or faulty, any remaining {@link CompletionStage}-s is cancelled. 
-     * 
+     * <p>When resulting promise is resolved either successfully or faulty, all remaining incomplete {@link CompletionStage}-s are cancelled.
+     *  
+     * @param <T>
+     *   a common supertype of the resulting values 
      * @param minResultsCount
      *   a minimum number of promises that should be completed normally to resolve resulting promise successfully 
      * @param promises
@@ -198,6 +213,32 @@ public static <T> Promise<List<T>> atLeastStrict(final int minResultsCount, fina
         return atLeast(minResultsCount, 0, true, promises);
     }
 
+    /**
+     * <p>General method to combine several {@link CompletionStage}-s passed as arguments into single promise.</p>
+     * <p>The resulting promise is resolved successfully when at least <code>minResultCount</code> of {@link CompletionStage}-s passed as parameters 
+     * are completed normally (race is possible).
+     * <p>If less than <code>minResultCount</code> of promises completed normally, then resulting promise is resolved faulty. 
+     * <p>If <code>maxErrorsCount</code> of promises completed exceptionally <em>before</em> <code>minResultCount</code> of results are available, then 
+     * resulting promise is resolved faulty as well. 
+     * <p>The resolved result of this promise contains a list of the resolved results of the {@link CompletionStage}-s passed as an 
+     * argument at corresponding positions. Non-completed promises and promises completed exceptionally have <code>null</code> values.
+     * <p>When resulting promise is resolved either successfully or faulty, all remaining incomplete {@link CompletionStage}-s are cancelled <em>if</em>
+     * <code>cancelRemaining</code> parameter is <code>true</code>. 
+     * 
+     * @param <T>
+     *   a common supertype of the resulting values 
+     * @param minResultsCount
+     *   a minimum number of promises that should be completed normally to resolve resulting promise successfully
+     * @param maxErrorsCount
+     *   a maximum number of promises that may be completed exceptionally before resolving resulting promise faulty
+     * @param cancelRemaining
+     *   a flag that indicates (if true) whether or not all remaining incomplete {@link CompletionStage}-s should be cancelled
+     *   once a resulting promise outcome is known. 
+     * @param promises
+     *   an array of {@link CompletionStage}-s to combine 
+     * @return
+     *   a combined promise 
+     */    
     @SafeVarargs
     public static <T> Promise<List<T>> atLeast(final int minResultsCount, final int maxErrorsCount, final boolean cancelRemaining, 
                                                final CompletionStage<? extends T>... promises) {

src/main/java/net/tascalate/concurrent/TaskExecutors.java

@@ -30,6 +30,12 @@
 import java.util.concurrent.TimeUnit;
 import java.util.concurrent.TimeoutException;
 
+/**
+ * The drop-in replacement for {@link Executors} utility class that returns various useful implementations
+ * of {@link TaskExecutorService} instead of standard {@link ExecutorService}.
+ * @author vsilaev
+ *
+ */
 public class TaskExecutors {
     /**
      * Creates a thread pool that reuses a fixed number of threads operating off