--- jsr166/src/jsr166y/Phaser.java	2009/08/24 23:08:18	1.43
+++ jsr166/src/jsr166y/Phaser.java	2009/08/30 11:08:25	1.46
@@ -142,14 +142,14 @@ import java.util.concurrent.locks.LockSu
  *     }
  *   };
  *   phaser.register();
- *   for (Runnable task : tasks) {
+ *   for (final Runnable task : tasks) {
  *     phaser.register();
  *     new Thread() {
  *       public void run() {
  *         do {
  *           task.run();
  *           phaser.arriveAndAwaitAdvance();
- *         } while(!phaser.isTerminated();
+ *         } while (!phaser.isTerminated());
  *       }
  *     }.start();
  *   }
@@ -158,49 +158,45 @@ import java.util.concurrent.locks.LockSu
  *
  * If the main task must later await termination, it
  * may re-register and then execute a similar loop:
- * <pre> {@code
+ *  <pre> {@code
  *   // ...
  *   phaser.register();
  *   while (!phaser.isTerminated())
- *     phaser.arriveAndAwaitAdvance();
- * }</pre>
+ *     phaser.arriveAndAwaitAdvance();}</pre>
  *
- * Related constructions may be used to await particular phase numbers
+ * <p>Related constructions may be used to await particular phase numbers
  * in contexts where you are sure that the phase will never wrap around
  * {@code Integer.MAX_VALUE}. For example:
  *
- * <pre> {@code
- *   void awaitPhase(Phaser phaser, int phase) {
- *     int p = phaser.register(); // assumes caller not already registered
- *     while (p < phase) {
- *       if (phaser.isTerminated())
- *         // ... deal with unexpected termination
- *       else
- *         p = phaser.arriveAndAwaitAdvance();
- *     }
- *     phaser.arriveAndDeregister();
+ *  <pre> {@code
+ * void awaitPhase(Phaser phaser, int phase) {
+ *   int p = phaser.register(); // assumes caller not already registered
+ *   while (p < phase) {
+ *     if (phaser.isTerminated())
+ *       // ... deal with unexpected termination
+ *     else
+ *       p = phaser.arriveAndAwaitAdvance();
  *   }
- * }</pre>
+ *   phaser.arriveAndDeregister();
+ * }}</pre>
  *
  *
  * <p>To create a set of tasks using a tree of phasers,
  * you could use code of the following form, assuming a
  * 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
@@ -785,12 +781,13 @@ public class Phaser {
      * property.
      *
      * <p>You may override this method to perform an action with side
-     * 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.
+     * effects visible to participating tasks, but it is 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. Additionally,
+     * method {@code onAdvance} may be invoked more than once per
+     * transition if registrations are intermixed with arrivals.
      *
      * @param phase the phase number on entering the barrier
      * @param registeredParties the current number of registered parties