--- jsr166/src/jsr166y/Phaser.java	2009/08/24 18:37:15	1.42
+++ jsr166/src/jsr166y/Phaser.java	2009/08/25 16:32:28	1.44
@@ -188,19 +188,16 @@ import java.util.concurrent.locks.LockSu
  * Task class with a constructor accepting a phaser that
  * it registers for upon construction:
  *  <pre> {@code
- * void build(Task[] actions, int lo, int hi, Phaser b) {
- *   int step = (hi - lo) / TASKS_PER_PHASER;
- *   if (step > 1) {
- *     int i = lo;
- *     while (i < hi) {
- *       int r = Math.min(i + step, hi);
- *       build(actions, i, r, new Phaser(b));
- *       i = r;
+ * void build(Task[] actions, int lo, int hi, Phaser ph) {
+ *   if (hi - lo > TASKS_PER_PHASER) {
+ *     for (int i = lo; i < hi; i += TASKS_PER_PHASER) {
+ *       int j = Math.min(i + TASKS_PER_PHASER, hi);
+ *       build(actions, i, j, new Phaser(ph));
  *     }
  *   } else {
  *     for (int i = lo; i < hi; ++i)
- *       actions[i] = new Task(b);
- *       // assumes new Task(b) performs b.register()
+ *       actions[i] = new Task(ph);
+ *       // assumes new Task(ph) performs ph.register()
  *   }
  * }
  * // .. initially called, for n tasks via
@@ -762,16 +759,16 @@ public class Phaser {
     }
 
     /**
-     * Overridable method to perform an action upon phase advance, and
-     * to control termination. This method is invoked upon arrival of
-     * the party tripping the barrier (when all other waiting parties
-     * are dormant).  If this method returns {@code true}, then,
-     * rather than advance the phase number, this barrier will be set
-     * to a final termination state, and subsequent calls to {@link
-     * #isTerminated} will return true. Any (unchecked) Exception or
-     * Error thrown by an invocation of this method is propagated to
-     * the party attempting to trip the barrier, in which case no
-     * advance occurs.
+     * Overridable method to perform an action upon impending phase
+     * advance, and to control termination. This method is invoked
+     * upon arrival of the party tripping the barrier (when all other
+     * waiting parties are dormant).  If this method returns {@code
+     * true}, then, rather than advance the phase number, this barrier
+     * will be set to a final termination state, and subsequent calls
+     * to {@link #isTerminated} will return true. Any (unchecked)
+     * Exception or Error thrown by an invocation of this method is
+     * propagated to the party attempting to trip the barrier, in
+     * which case no advance occurs.
      *
      * <p>The arguments to this method provide the state of the phaser
      * prevailing for the current transition. (When called from within
@@ -785,11 +782,12 @@ public class Phaser {
      * property.
      *
      * <p>You may override this method to perform an action with side
-     * effects visible to participating tasks, but it is in general
-     * only sensible to do so in designs where all parties register
-     * before any arrive, and all {@link #awaitAdvance} at each phase.
-     * Otherwise, you cannot ensure lack of interference from other
-     * parties during the invocation of this method.
+     * effects visible to participating tasks, but doing so requires
+     * care: Method {@code onAdvance} may be invoked more than once
+     * per transition.  Further, unless all parties register before
+     * any arrive, and all {@link #awaitAdvance} at each phase, then
+     * you cannot ensure lack of interference from other parties
+     * during the invocation of this method.
      *
      * @param phase the phase number on entering the barrier
      * @param registeredParties the current number of registered parties