--- a/src/share/classes/java/util/streams/AbstractPipeline.java	Mon Nov 05 14:28:29 2012 +0100
+++ b/src/share/classes/java/util/streams/AbstractPipeline.java	Mon Nov 05 15:05:16 2012 +0100
@@ -31,10 +31,48 @@
 
 /**
  * AbstractPipeline
+ * <p>
+ * Evaluation works in two modes:
+ * <ol>
+ * <li>Sequential; and</li>
+ * <li>Parallel.</li>
+ * </ol>
+ * </p>
+ * <p>
+ * Sequential evaluation is performed when the {@link StreamOpFlags#PARALLEL} flag is not set on the stream source
+ * flags or when it is not possible to obtain a {@link Spliterator} and split because some part of the pipeline has
+ * already been pulled due to a call to {@link #iterator()}.
+ * </p>
+ * <p>
+ * Parallel evaluation slices up the pipeline into a list of intermediate slices and a terminal slice.
+ * An intermediate slice consists of zero or more stateless intermediate operations and then
+ * one stateful intermediate operation at the end.
+ * The terminal slice consists of zero or more stateless intermediate operations and then
+ * one terminal operation at the end. The terminal operation is responsible for producing a result.
+ * </p>
+ * <p>
+ * Each intermediate slice is evaluated, in order, and in parallel to produce an intermediate list of elements
+ * that is held by a {@link Node}.
+ * That Node is converted to a {@link Spliterator} which becomes the source (or input) into the next intermediate
+ * or terminal slice.
+ * The process repeats until the terminal slice is processed to produce a result.
+ * </p>
+ * <p>
+ * If an intermediate result is produced and the combined stream and operation flags output with that result
+ * clears the {@link StreamOpFlags#PARALLEL} flag then all the remaining operations in the pipeline
+ * (the next operation after the stateful operation in the slice and up to and including the terminal operation)
+ * are evaluated sequentially to produce a result.
+ * </p>
+ * <p>
+ * Combined stream and operation flags are calculated for each slice of the pipeline. When a {@link Spliterator} for
+ * a {@link Node} is created the resultant source and operation flags produced from the intermediate stateful operation
+ * are utilized to create the source flags for that {@link Spliterator}.
+ * This ensures stream properties are preserved and propagated for the next intermediate or terminal evaluation.
+ * In addition the {@link StreamOpFlags#SIZED} flag will be explicitly set, since the {@link Node} knows it's size.
+ * </p>
  *
- * @param <E_IN> Type of input elements.
+ * @param <E_IN>  Type of input elements.
  * @param <E_OUT> Type of output elements.
- *
  * @author Brian Goetz
  */
 public abstract class AbstractPipeline<E_IN, E_OUT> {
@@ -46,38 +84,6 @@
     protected final StreamShape shape;
 
     /**
-     * Evaluation works in two modes:
-     *
-     * 1) Sequential; and
-     * 2) Parallel.
-     *
-     * Sequential evaluation is performed when a spliterator does not support splitting or when splitting is no
-     * longer possible because some part of the pipeline has already been pulled.
-     *
-     * Parallel evaluation slices up the pipeline into a list of intermediate slices and a terminal slice.
-     * An intermediate slice consists of zero or more stateless intermediate operations and then
-     * one stateful intermediate operation at the end.
-     * The terminal slice consists of zero or more stateless intermediate operations and then
-     * one terminal operation at the end. The terminal operation is responsible for producing a result.
-     *
-     * Each intermediate slice is evaluated, in order, and in parallel to produce an intermediate list of elements
-     * that is held by a Node.
-     * That Node is converted to a Spliterator which becomes is the source or input into the next intermediate
-     * or terminal slice.
-     * The process repeats until the terminal slice is processed to produce a result.
-     *
-     * If an intermediate result is a Node that when converted to a Spliterator does not support splitting then all
-     * the remaining operations in the pipeline (the next operation after the stateful operation in the slice and
-     * up to and including the terminal operation) are evaluated sequentially.
-     *
-     * Combined stream and operation flags are calculated for each slice of the pipeline. When a spliterator for
-     * a Node is created the resultant source and operation flags produced from the intermediate stateful operation
-     * are utilized to create the source flags for that spliterator. This ensures stream properties are preserved and
-     * propagated for the next intermediate evaluation. In addition the SIZED property will be explicitly set, since
-     * the Node knows it's size.
-     */
-
-    /**
      * If non-{@code null} then we are in sequential iteration mode.
      */
     private Iterator<E_OUT> iterator;