--- jsr166/src/jsr166y/RecursiveAction.java	2009/07/31 16:25:40	1.9
+++ jsr166/src/jsr166y/RecursiveAction.java	2011/06/25 01:48:24	1.17
@@ -1,24 +1,24 @@
 /*
  * Written by Doug Lea with assistance from members of JCP JSR-166
  * Expert Group and released to the public domain, as explained at
- * http://creativecommons.org/licenses/publicdomain
+ * http://creativecommons.org/publicdomain/zero/1.0/
  */
 
 package jsr166y;
 
 /**
- * Recursive resultless ForkJoinTasks. This class establishes
- * conventions to parameterize resultless actions as {@code Void}
- * ForkJoinTasks. Because {@code null} is the only valid value of
- * type {@code Void}, methods such as join always return {@code null}
- * upon completion.
+ * A recursive resultless {@link ForkJoinTask}.  This class
+ * establishes conventions to parameterize resultless actions as
+ * {@code Void} {@code ForkJoinTask}s. Because {@code null} is the
+ * only valid value of type {@code Void}, methods such as {@code join}
+ * always return {@code null} upon completion.
  *
  * <p><b>Sample Usages.</b> Here is a sketch of a ForkJoin sort that
  * sorts a given {@code long[]} array:
  *
  *  <pre> {@code
  * class SortTask extends RecursiveAction {
- *   final long[] array; final int lo; final int hi;
+ *   final long[] array; final int lo, hi;
  *   SortTask(long[] array, int lo, int hi) {
  *     this.array = array; this.lo = lo; this.hi = hi;
  *   }
@@ -29,7 +29,7 @@ package jsr166y;
  *       int mid = (lo + hi) >>> 1;
  *       invokeAll(new SortTask(array, lo, mid),
  *                 new SortTask(array, mid, hi));
- *       merge(array, lo, hi);
+ *       merge(array, lo, mid, hi);
  *     }
  *   }
  * }}</pre>
@@ -40,7 +40,7 @@ package jsr166y;
  * task increments each element of an array:
  *  <pre> {@code
  * class IncrementTask extends RecursiveAction {
- *   final long[] array; final int lo; final int hi;
+ *   final long[] array; final int lo, hi;
  *   IncrementTask(long[] array, int lo, int hi) {
  *     this.array = array; this.lo = lo; this.hi = hi;
  *   }
@@ -64,30 +64,30 @@ package jsr166y;
  * of each element of a double array, by subdividing out only the
  * right-hand-sides of repeated divisions by two, and keeping track of
  * them with a chain of {@code next} references. It uses a dynamic
- * threshold based on method {@code surplus}, but counterbalances
- * potential excess partitioning by directly performing leaf actions
- * on unstolen tasks rather than further subdividing.
+ * threshold based on method {@code getSurplusQueuedTaskCount}, but
+ * counterbalances potential excess partitioning by directly
+ * performing leaf actions on unstolen tasks rather than further
+ * subdividing.
  *
  *  <pre> {@code
  * double sumOfSquares(ForkJoinPool pool, double[] array) {
  *   int n = array.length;
- *   int seqSize = 1 + n / (8 * pool.getParallelism());
- *   Applyer a = new Applyer(array, 0, n, seqSize, null);
+ *   Applyer a = new Applyer(array, 0, n, null);
  *   pool.invoke(a);
  *   return a.result;
  * }
  *
  * class Applyer extends RecursiveAction {
  *   final double[] array;
- *   final int lo, hi, seqSize;
+ *   final int lo, hi;
  *   double result;
  *   Applyer next; // keeps track of right-hand-side tasks
- *   Applyer(double[] array, int lo, int hi, int seqSize, Applyer next) {
+ *   Applyer(double[] array, int lo, int hi, Applyer next) {
  *     this.array = array; this.lo = lo; this.hi = hi;
- *     this.seqSize = seqSize; this.next = next;
+ *     this.next = next;
  *   }
  *
- *   double atLeaf(int l, int r) {
+ *   double atLeaf(int l, int h) {
  *     double sum = 0;
  *     for (int i = l; i < h; ++i) // perform leftmost base step
  *       sum += array[i] * array[i];
@@ -100,7 +100,7 @@ package jsr166y;
  *     Applyer right = null;
  *     while (h - l > 1 && getSurplusQueuedTaskCount() <= 3) {
  *        int mid = (l + h) >>> 1;
- *        right = new Applyer(array, mid, h, seqSize, right);
+ *        right = new Applyer(array, mid, h, right);
  *        right.fork();
  *        h = mid;
  *     }
@@ -109,7 +109,7 @@ package jsr166y;
  *        if (right.tryUnfork()) // directly calculate if not stolen
  *          sum += right.atLeaf(right.lo, right.hi);
  *       else {
- *          right.helpJoin();
+ *          right.join();
  *          sum += right.result;
  *        }
  *        right = right.next;
@@ -130,7 +130,9 @@ public abstract class RecursiveAction ex
     protected abstract void compute();
 
     /**
-     * Always returns null.
+     * Always returns {@code null}.
+     *
+     * @return {@code null} always
      */
     public final Void getRawResult() { return null; }