--- jsr166/src/jsr166y/Phaser.java	2009/08/24 12:49:39	1.40
+++ jsr166/src/jsr166y/Phaser.java	2009/08/24 23:08:18	1.43
@@ -100,12 +100,11 @@ import java.util.concurrent.locks.LockSu
  * #getRegisteredParties} parties in total, of which {@link
  * #getArrivedParties} have arrived at the current phase ({@link
  * #getPhase}).  When the remaining ({@link #getUnarrivedParties})
- * parties arrive, the phase advances; thus, this value is always
- * greater than zero if there are any registered parties.  The values
- * returned by these methods may reflect transient states and so are
- * not in general useful for synchronization control.  Method {@link
- * #toString} returns snapshots of these state queries in a form
- * convenient for informal monitoring.
+ * parties arrive, the phase advances.  The values returned by these
+ * methods may reflect transient states and so are not in general
+ * useful for synchronization control.  Method {@link #toString}
+ * returns snapshots of these state queries in a form convenient for
+ * informal monitoring.
  *
  * <p><b>Sample usages:</b>
  *
@@ -250,7 +249,6 @@ public class Phaser {
      */
     private volatile long state;
 
-    private static final int ushortBits = 16;
     private static final int ushortMask = 0xffff;
     private static final int phaseMask  = 0x7fffffff;
 
@@ -764,13 +762,22 @@ public class Phaser {
     }
 
     /**
-     * Overridable method to perform an action upon phase advance, and
-     * to control termination. This method is invoked whenever the
-     * barrier is tripped (and thus all other waiting parties are
-     * dormant). If it 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.
+     * 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
+     * an implementation of {@code onAdvance} the values returned by
+     * methods such as {@code getPhase} may or may not reliably
+     * indicate the state to which this transition applies.)
      *
      * <p>The default version returns {@code true} when the number of
      * registered parties is zero. Normally, overrides that arrange
@@ -778,11 +785,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