8021417: Fix doclint issues in java.util.concurrent

Reviewed-by: chegar, lancea
Contributed-by: NDoug Lea <dl@cs.oswego.edu>

src/share/classes/java/util/concurrent/AbstractExecutorService.java

@@ -76,6 +76,7 @@ public abstract class AbstractExecutorService implements ExecutorService {
      *
      * @param runnable the runnable task being wrapped
      * @param value the default value for the returned future
+     * @param <T> the type of the given value
      * @return a {@code RunnableFuture} which, when run, will run the
      * underlying runnable and which, as a {@code Future}, will yield
      * the given value as its result and provide for cancellation of
@@ -90,6 +91,7 @@ public abstract class AbstractExecutorService implements ExecutorService {
      * Returns a {@code RunnableFuture} for the given callable task.
      *
      * @param callable the callable task being wrapped
+     * @param <T> the type of the callable's result
      * @return a {@code RunnableFuture} which, when run, will call the
      * underlying callable and which, as a {@code Future}, will yield
      * the callable's result as its result and provide for

src/share/classes/java/util/concurrent/ExecutorService.java

@@ -227,6 +227,7 @@ public interface ExecutorService extends Executor {
      * {@link Callable} form so they can be submitted.
      *
      * @param task the task to submit
+     * @param <T> the type of the task's result
      * @return a Future representing pending completion of the task
      * @throws RejectedExecutionException if the task cannot be
      *         scheduled for execution
@@ -241,6 +242,7 @@ public interface ExecutorService extends Executor {
      *
      * @param task the task to submit
      * @param result the result to return
+     * @param <T> the type of the result
      * @return a Future representing pending completion of the task
      * @throws RejectedExecutionException if the task cannot be
      *         scheduled for execution
@@ -272,6 +274,7 @@ public interface ExecutorService extends Executor {
      * collection is modified while this operation is in progress.
      *
      * @param tasks the collection of tasks
+     * @param <T> the type of the values returned from the tasks
      * @return a list of Futures representing the tasks, in the same
      *         sequential order as produced by the iterator for the
      *         given task list, each of which has completed
@@ -299,6 +302,7 @@ public interface ExecutorService extends Executor {
      * @param tasks the collection of tasks
      * @param timeout the maximum time to wait
      * @param unit the time unit of the timeout argument
+     * @param <T> the type of the values returned from the tasks
      * @return a list of Futures representing the tasks, in the same
      *         sequential order as produced by the iterator for the
      *         given task list. If the operation did not time out,
@@ -324,6 +328,7 @@ public interface ExecutorService extends Executor {
      * collection is modified while this operation is in progress.
      *
      * @param tasks the collection of tasks
+     * @param <T> the type of the values returned from the tasks
      * @return the result returned by one of the tasks
      * @throws InterruptedException if interrupted while waiting
      * @throws NullPointerException if tasks or any element task
@@ -348,6 +353,7 @@ public interface ExecutorService extends Executor {
      * @param tasks the collection of tasks
      * @param timeout the maximum time to wait
      * @param unit the time unit of the timeout argument
+     * @param <T> the type of the values returned from the tasks
      * @return the result returned by one of the tasks
      * @throws InterruptedException if interrupted while waiting
      * @throws NullPointerException if tasks, or unit, or any element

src/share/classes/java/util/concurrent/Executors.java

@@ -397,6 +397,7 @@ public class Executors {
      * {@code Callable} to an otherwise resultless action.
      * @param task the task to run
      * @param result the result to return
+     * @param <T> the type of the result
      * @return a callable object
      * @throws NullPointerException if task null
      */
@@ -458,6 +459,7 @@ public class Executors {
      * action; or if not possible, throw an associated {@link
      * AccessControlException}.
      * @param callable the underlying task
+     * @param <T> the type of the callable's result
      * @return a callable object
      * @throws NullPointerException if callable null
      */
@@ -480,6 +482,7 @@ public class Executors {
      * AccessControlException}.
      *
      * @param callable the underlying task
+     * @param <T> the type of the callable's result
      * @return a callable object
      * @throws NullPointerException if callable null
      * @throws AccessControlException if the current access control

src/share/classes/java/util/concurrent/ForkJoinPool.java

@@ -561,8 +561,8 @@ public class ForkJoinPool extends AbstractExecutorService {
          * Returns a new worker thread operating in the given pool.
          *
          * @param pool the pool this thread works in
-         * @throws NullPointerException if the pool is null
          * @return the new worker thread
+         * @throws NullPointerException if the pool is null
          */
         public ForkJoinWorkerThread newThread(ForkJoinPool pool);
     }
@@ -2497,6 +2497,7 @@ public class ForkJoinPool extends AbstractExecutorService {
      * minimally only the latter.
      *
      * @param task the task
+     * @param <T> the type of the task's result
      * @return the task's result
      * @throws NullPointerException if the task is null
      * @throws RejectedExecutionException if the task cannot be
@@ -2545,6 +2546,7 @@ public class ForkJoinPool extends AbstractExecutorService {
      * Submits a ForkJoinTask for execution.
      *
      * @param task the task to submit
+     * @param <T> the type of the task's result
      * @return the task
      * @throws NullPointerException if the task is null
      * @throws RejectedExecutionException if the task cannot be

src/share/classes/java/util/concurrent/ForkJoinTask.java

@@ -810,6 +810,7 @@ public abstract class ForkJoinTask<V> implements Future<V>, Serializable {
      * unprocessed.
      *
      * @param tasks the collection of tasks
+     * @param <T> the type of the values returned from the tasks
      * @return the tasks argument, to simplify usage
      * @throws NullPointerException if tasks or any element are null
      */
@@ -1472,6 +1473,7 @@ public abstract class ForkJoinTask<V> implements Future<V>, Serializable {
      *
      * @param runnable the runnable action
      * @param result the result upon completion
+     * @param <T> the type of the result
      * @return the task
      */
     public static <T> ForkJoinTask<T> adapt(Runnable runnable, T result) {
@@ -1485,6 +1487,7 @@ public abstract class ForkJoinTask<V> implements Future<V>, Serializable {
      * encountered into {@code RuntimeException}.
      *
      * @param callable the callable action
+     * @param <T> the type of the callable's result
      * @return the task
      */
     public static <T> ForkJoinTask<T> adapt(Callable<? extends T> callable) {
@@ -1498,6 +1501,8 @@ public abstract class ForkJoinTask<V> implements Future<V>, Serializable {
     /**
      * Saves this task to a stream (that is, serializes it).
      *
+     * @param s the stream
+     * @throws java.io.IOException if an I/O error occurs
      * @serialData the current run status and the exception thrown
      * during execution, or {@code null} if none
      */
@@ -1509,6 +1514,10 @@ public abstract class ForkJoinTask<V> implements Future<V>, Serializable {
 
     /**
      * Reconstitutes this task from a stream (that is, deserializes it).
+     * @param s the stream
+     * @throws ClassNotFoundException if the class of a serialized object
+     *         could not be found
+     * @throws java.io.IOException if an I/O error occurs
      */
     private void readObject(java.io.ObjectInputStream s)
         throws java.io.IOException, ClassNotFoundException {

src/share/classes/java/util/concurrent/ScheduledExecutorService.java

@@ -117,6 +117,7 @@ public interface ScheduledExecutorService extends ExecutorService {
      * @param callable the function to execute
      * @param delay the time from now to delay execution
      * @param unit the time unit of the delay parameter
+     * @param <V> the type of the callable's result
      * @return a ScheduledFuture that can be used to extract result or cancel
      * @throws RejectedExecutionException if the task cannot be
      *         scheduled for execution

src/share/classes/java/util/concurrent/ScheduledThreadPoolExecutor.java

@@ -392,6 +392,7 @@ public class ScheduledThreadPoolExecutor
      *
      * @param runnable the submitted Runnable
      * @param task the task created to execute the runnable
+     * @param <V> the type of the task's result
      * @return a task that can execute the runnable
      * @since 1.6
      */
@@ -408,6 +409,7 @@ public class ScheduledThreadPoolExecutor
      *
      * @param callable the submitted Callable
      * @param task the task created to execute the callable
+     * @param <V> the type of the task's result
      * @return a task that can execute the callable
      * @since 1.6
      */

src/share/classes/java/util/concurrent/TimeUnit.java

@@ -69,6 +69,9 @@ package java.util.concurrent;
  * @author Doug Lea
  */
 public enum TimeUnit {
+    /**
+     * Time unit representing one thousandth of a microsecond
+     */
     NANOSECONDS {
         public long toNanos(long d)   { return d; }
         public long toMicros(long d)  { return d/(C1/C0); }
@@ -80,6 +83,10 @@ public enum TimeUnit {
         public long convert(long d, TimeUnit u) { return u.toNanos(d); }
         int excessNanos(long d, long m) { return (int)(d - (m*C2)); }
     },
+
+    /**
+     * Time unit representing one thousandth of a millisecond
+     */
     MICROSECONDS {
         public long toNanos(long d)   { return x(d, C1/C0, MAX/(C1/C0)); }
         public long toMicros(long d)  { return d; }
@@ -91,6 +98,10 @@ public enum TimeUnit {
         public long convert(long d, TimeUnit u) { return u.toMicros(d); }
         int excessNanos(long d, long m) { return (int)((d*C1) - (m*C2)); }
     },
+
+    /**
+     * Time unit representing one thousandth of a second
+     */
     MILLISECONDS {
         public long toNanos(long d)   { return x(d, C2/C0, MAX/(C2/C0)); }
         public long toMicros(long d)  { return x(d, C2/C1, MAX/(C2/C1)); }
@@ -102,6 +113,10 @@ public enum TimeUnit {
         public long convert(long d, TimeUnit u) { return u.toMillis(d); }
         int excessNanos(long d, long m) { return 0; }
     },
+
+    /**
+     * Time unit representing one second
+     */
     SECONDS {
         public long toNanos(long d)   { return x(d, C3/C0, MAX/(C3/C0)); }
         public long toMicros(long d)  { return x(d, C3/C1, MAX/(C3/C1)); }
@@ -113,6 +128,10 @@ public enum TimeUnit {
         public long convert(long d, TimeUnit u) { return u.toSeconds(d); }
         int excessNanos(long d, long m) { return 0; }
     },
+
+    /**
+     * Time unit representing sixty seconds
+     */
     MINUTES {
         public long toNanos(long d)   { return x(d, C4/C0, MAX/(C4/C0)); }
         public long toMicros(long d)  { return x(d, C4/C1, MAX/(C4/C1)); }
@@ -124,6 +143,10 @@ public enum TimeUnit {
         public long convert(long d, TimeUnit u) { return u.toMinutes(d); }
         int excessNanos(long d, long m) { return 0; }
     },
+
+    /**
+     * Time unit representing sixty minutes
+     */
     HOURS {
         public long toNanos(long d)   { return x(d, C5/C0, MAX/(C5/C0)); }
         public long toMicros(long d)  { return x(d, C5/C1, MAX/(C5/C1)); }
@@ -135,6 +158,10 @@ public enum TimeUnit {
         public long convert(long d, TimeUnit u) { return u.toHours(d); }
         int excessNanos(long d, long m) { return 0; }
     },
+
+    /**
+     * Time unit representing twenty four hours
+     */
     DAYS {
         public long toNanos(long d)   { return x(d, C6/C0, MAX/(C6/C0)); }
         public long toMicros(long d)  { return x(d, C6/C1, MAX/(C6/C1)); }

src/share/classes/java/util/concurrent/atomic/AtomicIntegerFieldUpdater.java

@@ -71,6 +71,7 @@ public abstract class AtomicIntegerFieldUpdater<T> {
      *
      * @param tclass the class of the objects holding the field
      * @param fieldName the name of the field to be updated
+     * @param <U> the type of instances of tclass
      * @return the updater
      * @throws IllegalArgumentException if the field is not a
      * volatile integer type

src/share/classes/java/util/concurrent/atomic/AtomicLongFieldUpdater.java

@@ -71,6 +71,7 @@ public abstract class AtomicLongFieldUpdater<T> {
      *
      * @param tclass the class of the objects holding the field
      * @param fieldName the name of the field to be updated
+     * @param <U> the type of instances of tclass
      * @return the updater
      * @throws IllegalArgumentException if the field is not a
      * volatile long type

src/share/classes/java/util/concurrent/atomic/AtomicReferenceFieldUpdater.java

@@ -91,6 +91,8 @@ public abstract class AtomicReferenceFieldUpdater<T,V> {
      * @param tclass the class of the objects holding the field
      * @param vclass the class of the field
      * @param fieldName the name of the field to be updated
+     * @param <U> the type of instances of tclass
+     * @param <W> the type of instances of vclass
      * @return the updater
      * @throws ClassCastException if the field is of the wrong type
      * @throws IllegalArgumentException if the field is not volatile