changeset 7814:4a801290864f

Yet another Javadoc cleanup pass
author briangoetz
date Thu, 04 Apr 2013 14:20:42 -0400
parents 65f0db78e145
children 973a4c9b9935 1997e4b4c4dd
files src/share/classes/java/util/stream/AbstractPipeline.java src/share/classes/java/util/stream/BaseStream.java src/share/classes/java/util/stream/Collector.java src/share/classes/java/util/stream/Collectors.java src/share/classes/java/util/stream/DelegatingStream.java src/share/classes/java/util/stream/DistinctOps.java src/share/classes/java/util/stream/DoublePipeline.java src/share/classes/java/util/stream/FindOps.java src/share/classes/java/util/stream/FlatMapper.java src/share/classes/java/util/stream/ForEachOps.java src/share/classes/java/util/stream/IntPipeline.java src/share/classes/java/util/stream/LongPipeline.java src/share/classes/java/util/stream/MatchOps.java src/share/classes/java/util/stream/PipelineHelper.java src/share/classes/java/util/stream/ReduceOps.java src/share/classes/java/util/stream/ReferencePipeline.java src/share/classes/java/util/stream/SliceOps.java src/share/classes/java/util/stream/Tripwire.java
diffstat 18 files changed, 271 insertions(+), 71 deletions(-) [+]
line wrap: on
line diff
--- a/src/share/classes/java/util/stream/AbstractPipeline.java	Thu Apr 04 21:11:56 2013 +0800
+++ b/src/share/classes/java/util/stream/AbstractPipeline.java	Thu Apr 04 14:20:42 2013 -0400
@@ -35,15 +35,19 @@
  *
  * <p>An {@code AbstractPipeline} represents an initial portion of a stream
  * pipeline, encapsulating a stream source and zero or more intermediate
- * operations.  Methods in this class fall into one of three categories:
- * support for creating new streams by chaining an additional intermediate
- * operation; support for evaluating streams by executing a terminal operation;
- * and support for gaining additional information about the stream pipeline,
- * such as {@link #getStreamFlags()}.  After chaining a new intermediate
- * operation, the stream is considered to be in the @{code LINKED} state,
- * meaning that no more intermediate or terminal operations are permitted
- * on this stream instance.  After executing a terminal operation, the
- * source is considered to be consumed and no more intermediate or terminal
+ * operations.  The individual {@code AbstractPipeline} objects are often
+ * referred to as <em>stages</em>, where each stage describes either the stream
+ * source or an intermediate operation.
+ *
+ * <p>A concrete stage is built from an {@code AbstractPipeline}, a shape-specific pipeline class
+ * (e.g., {@code IntPipeline} which is also abstract, and an operation-specific concrete class.
+ * {@code AbstractPipeline} contains most of the mechanics of evaluating the pipeline,
+ * and implements methods that will be used by the operation; the shape-specific classes
+ * add helper methods for dealing with collection of results into the appropriate
+ * containers.
+ *
+ * <p>After chaining a new intermediate operation, or executing a terminal operation,
+ * the stream is considered to be consumed, and no more intermediate or terminal
  * operations are permitted on this stream instance.
  *
  * <p>{@code AbstractPipeline} implements a number of methods that are
@@ -51,6 +55,7 @@
  * {@code BaseStream} directly.  Subclasses of {@code AbstractPipeline}
  * will generally implement {@code BaseStream}.
  *
+ * @implNote
  * <p>For sequential streams, and parallel streams without
  * <a href="package-summary.html#StreamOps">stateful intermediate
  * operations</a>, parallel streams, pipeline evaluation is done in a single
@@ -149,9 +154,10 @@
     }
 
     /**
-     * Constructor for appending an intermediate operation onto an existing pipeline.
+     * Constructor for appending an intermediate operation stage onto an existing pipeline.
      *
-     * @param previousStage the upstream element source.
+     * @param previousStage the upstream pipeline stage
+     * @param opFlags the operation flags for the new stage, described in {@link StreamOpFlag}
      */
     AbstractPipeline(AbstractPipeline<?, E_IN, ?> previousStage,
                      int opFlags) {
@@ -170,8 +176,8 @@
     }
 
     /**
-     * Prepare the pipeline for evaluation.
-     * @param terminalFlags
+     * Prepares the pipeline for evaluation.
+     * @param terminalFlags The terminal operation flags, described in {@link StreamOpFlag}
      */
     private void prepare(int terminalFlags) {
         if (isParallel()) {
@@ -245,10 +251,10 @@
     }
 
     /**
-     * Collect the elements output from the pipeline.
+     * Collect the elements output from the pipeline stage.
      *
      * @param generator the array generator to be used to create array instances.
-     * @return a node that holds the collected output elements.
+     * @return a Node that holds the collected output elements.
      */
     final Node<E_OUT> evaluateToArrayNode(IntFunction<E_OUT[]> generator) {
         if (linkedOrConsumed)
@@ -267,9 +273,7 @@
         }
     }
 
-
-    // BaseStream
-
+    /** Implements {@link BaseStream#sequential()} */
     public final S sequential() {
         if (StreamOpFlag.PARALLEL.isKnown(sourceStage.combinedFlags)) {
             sourceStage.sourceAnyParChange = true;
@@ -279,6 +283,7 @@
         return (S) this;
     }
 
+    /** Implements {@link BaseStream#parallel()} */
     public final S parallel() {
         if (!StreamOpFlag.PARALLEL.isKnown(sourceStage.combinedFlags)) {
             sourceStage.sourceAnyParChange = true;
@@ -289,6 +294,7 @@
     }
 
     // Primitive specialization use co-variant overrides, hence is not final
+    /** Implements {@link BaseStream#spliterator()} */
     public Spliterator<E_OUT> spliterator() {
         if (linkedOrConsumed)
             throw new IllegalStateException("stream has already been operated upon");
@@ -315,13 +321,11 @@
         }
     }
 
+    /** Implements {@link BaseStream#isParallel()} */
     public final boolean isParallel() {
         return StreamOpFlag.PARALLEL.isKnown(sourceStage.combinedFlags);
     }
 
-
-    //
-
     /**
      * Returns the composition of stream flags of the stream source and all
      * intermediate operations.
@@ -338,7 +342,10 @@
     }
 
     /**
-     * Get the source spliterator for this pipeline stage
+     * Get the source spliterator for this pipeline stage.  For a sequential or stateless
+     * parallel pipeline, this is the source spliterator.  For a stateful parallel pipeline,
+     * this is a spliterator describing the results of all computations up to and including
+     * the most recent stateful operation.
      */
     private Spliterator<?> sourceSpliterator() {
         // Get the source spliterator of the pipeline
@@ -371,7 +378,6 @@
         return spliterator;
     }
 
-
     // PipelineHelper
 
     @Override
@@ -442,7 +448,7 @@
     }
 
 
-    // Shape-specific abstract methods
+    // Shape-specific abstract methods, implemented by XxxPipeline classes
 
     /**
      * Get the output shape of the pipeline.
@@ -515,7 +521,7 @@
                                                  IntFunction<E_OUT[]> generator);
 
 
-    // Op-specific abstract methods
+    // Op-specific abstract methods, implemented by the operation class
 
     /**
      * Returns whether this operation is stateful or not.  If it is stateful,
--- a/src/share/classes/java/util/stream/BaseStream.java	Thu Apr 04 21:11:56 2013 +0800
+++ b/src/share/classes/java/util/stream/BaseStream.java	Thu Apr 04 14:20:42 2013 -0400
@@ -29,9 +29,12 @@
 
 /**
  * Base interface for stream types such as {@link Stream}, {@link IntStream},
- * etc.  Contains methods common to all stream types.
+ * etc.  Contains methods common to all stream types.  Many of these methods
+ * are implemented by {@link AbstractPipeline}, even though {@code AbstractPipeline}
+ * does not directly implement {@code BaseStream}.
  *
  * @param <T> Type of stream elements.
+ * @param <S> Type of stream implementing {@code BaseStream}.
  * @since 1.8
  */
 interface BaseStream<T, S extends BaseStream<T, S>> {
@@ -54,11 +57,13 @@
     Spliterator<T> spliterator();
 
     /**
-     * Returns whether this stream, when executed, will execute in parallel.  Calling this
-     * method after invoking an intermediate or terminal stream operation method may yield
-     * unpredictable results.
+     * Returns whether this stream, when executed, would execute in parallel (assuming
+     * no further modification of the stream, such as appending further intermediate
+     * operations or changing its parallelism).  Calling this method after invoking
+     * an intermediate or terminal stream operation method may yield unpredictable results.
      *
-     * @return whether this stream will execute in parallel
+     * @return whether this stream would execute in parallel if executed without further
+     * modification
      */
     boolean isParallel();
 
--- a/src/share/classes/java/util/stream/Collector.java	Thu Apr 04 21:11:56 2013 +0800
+++ b/src/share/classes/java/util/stream/Collector.java	Thu Apr 04 14:20:42 2013 -0400
@@ -162,6 +162,10 @@
         return Collections.emptySet();
     }
 
+    /**
+     * Characteristics indicating properties of a {@code Collector}, which can be used
+     * to optimize reduction implementations.
+     */
     enum Characteristics {
         /**
          * Indicates that this collector is <em>concurrent</em>, meaning that the result
--- a/src/share/classes/java/util/stream/Collectors.java	Thu Apr 04 21:11:56 2013 +0800
+++ b/src/share/classes/java/util/stream/Collectors.java	Thu Apr 04 14:20:42 2013 -0400
@@ -54,8 +54,9 @@
 import java.util.function.ToLongFunction;
 
 /**
- * Implementations of {@link Collector} that implement various useful reduction operations, such as accumulating
- * elements into collections, summarizing elements according to various criteria, etc.
+ * Implementations of {@link Collector} that implement various useful reduction operations,
+ * such as accumulating elements into collections, summarizing elements according to various
+ * criteria, etc.
  *
  * @since 1.8
  */
--- a/src/share/classes/java/util/stream/DelegatingStream.java	Thu Apr 04 21:11:56 2013 +0800
+++ b/src/share/classes/java/util/stream/DelegatingStream.java	Thu Apr 04 14:20:42 2013 -0400
@@ -56,7 +56,8 @@
      * Construct a {@code Stream} that delegates operations to another {@code
      * Stream}.
      *
-     * @param delegate The {@link Stream} that actually performs the operation
+     * @param delegate The underlying {@link Stream} to which we delegate all
+     *                 {@code Stream} methods
      * @throws NullPointerException if the delegate is null
      */
     public DelegatingStream(Stream<T> delegate) {
@@ -65,10 +66,12 @@
 
     // -- BaseStream methods --
 
+    @Override
     public Spliterator<T> spliterator() {
         return delegate.spliterator();
     }
 
+    @Override
     public boolean isParallel() {
         return delegate.isParallel();
     }
@@ -80,58 +83,72 @@
 
     // -- Stream methods --
 
+    @Override
     public Stream<T> filter(Predicate<? super T> predicate) {
         return delegate.filter(predicate);
     }
 
+    @Override
     public <R> Stream<R> map(Function<? super T, ? extends R> mapper) {
         return delegate.map(mapper);
     }
 
+    @Override
     public IntStream mapToInt(ToIntFunction<? super T> mapper) {
         return delegate.mapToInt(mapper);
     }
 
+    @Override
     public LongStream mapToLong(ToLongFunction<? super T> mapper) {
         return delegate.mapToLong(mapper);
     }
 
+    @Override
     public DoubleStream mapToDouble(ToDoubleFunction<? super T> mapper) {
         return delegate.mapToDouble(mapper);
     }
 
+    @Override
     public <R> Stream<R> flatMap(Function<T, Stream<? extends R>> mapper) {
         return delegate.flatMap(mapper);
     }
 
+    @Override
     public <R> Stream<R> flatMap(FlatMapper<? super T, R> mapper) {
         return delegate.flatMap(mapper);
     }
 
+    @Override
     public IntStream flatMapToInt(FlatMapper.ToInt<? super T> mapper) {
         return delegate.flatMapToInt(mapper);
     }
 
+    @Override
     public LongStream flatMapToLong(FlatMapper.ToLong<? super T> mapper) {
         return delegate.flatMapToLong(mapper);
     }
 
+    @Override
     public DoubleStream flatMapToDouble(FlatMapper.ToDouble<? super T> mapper) {
         return delegate.flatMapToDouble(mapper);
     }
 
+    @Override
     public Stream<T> distinct() {
         return delegate.distinct();
     }
 
+    @Override
     public Stream<T> sorted() {
         return delegate.sorted();
     }
 
+    @Override
     public Stream<T> sorted(Comparator<? super T> comparator) {
         return delegate.sorted(comparator);
     }
 
+    @Override
     public void forEach(Consumer<? super T> consumer) {
         delegate.forEach(consumer);
     }
@@ -141,22 +158,27 @@
         delegate.forEachOrdered(consumer);
     }
 
+    @Override
     public Stream<T> peek(Consumer<? super T> consumer) {
         return delegate.peek(consumer);
     }
 
+    @Override
     public Stream<T> limit(long maxSize) {
         return delegate.limit(maxSize);
     }
 
+    @Override
     public Stream<T> substream(long startingOffset) {
         return delegate.substream(startingOffset);
     }
 
+    @Override
     public Stream<T> substream(long startingOffset, long endingOffset) {
         return delegate.substream(startingOffset, endingOffset);
     }
 
+    @Override
     public <A> A[] toArray(IntFunction<A[]> generator) {
         return delegate.toArray(generator);
     }
@@ -166,70 +188,86 @@
         return delegate.toArray();
     }
 
+    @Override
     public T reduce(T identity, BinaryOperator<T> accumulator) {
         return delegate.reduce(identity, accumulator);
     }
 
+    @Override
     public Optional<T> reduce(BinaryOperator<T> accumulator) {
         return delegate.reduce(accumulator);
     }
 
+    @Override
     public <U> U reduce(U identity, BiFunction<U, ? super T, U> accumulator,
                         BinaryOperator<U> combiner) {
         return delegate.reduce(identity, accumulator, combiner);
     }
 
+    @Override
     public <R> R collect(Supplier<R> resultFactory,
                          BiConsumer<R, ? super T> accumulator,
                          BiConsumer<R, R> combiner) {
         return delegate.collect(resultFactory, accumulator, combiner);
     }
 
+    @Override
     public <R> R collect(Collector<? super T, R> collector) {
         return delegate.collect(collector);
     }
 
+    @Override
     public <R> R collectUnordered(Collector<? super T, R> collector) {
         return delegate.collectUnordered(collector);
     }
 
+    @Override
     public Optional<T> max(Comparator<? super T> comparator) {
         return delegate.max(comparator);
     }
 
+    @Override
     public Optional<T> min(Comparator<? super T> comparator) {
         return delegate.min(comparator);
     }
 
+    @Override
     public long count() {
         return delegate.count();
     }
 
+    @Override
     public boolean anyMatch(Predicate<? super T> predicate) {
         return delegate.anyMatch(predicate);
     }
 
+    @Override
     public boolean allMatch(Predicate<? super T> predicate) {
         return delegate.allMatch(predicate);
     }
 
+    @Override
     public boolean noneMatch(Predicate<? super T> predicate) {
         return delegate.noneMatch(predicate);
     }
 
+    @Override
     public Optional<T> findFirst() {
         return delegate.findFirst();
     }
 
+    @Override
     public Optional<T> findAny() {
         return delegate.findAny();
     }
 
+    @Override
     public Stream<T> sequential() {
         return delegate.sequential();
     }
 
+    @Override
     public Stream<T> parallel() {
         return delegate.parallel();
     }
-}
\ No newline at end of file
+}
--- a/src/share/classes/java/util/stream/DistinctOps.java	Thu Apr 04 21:11:56 2013 +0800
+++ b/src/share/classes/java/util/stream/DistinctOps.java	Thu Apr 04 14:20:42 2013 -0400
@@ -34,7 +34,9 @@
 import java.util.function.IntFunction;
 
 /**
- * Factory methods for transforming streams into duplicate-free streams.
+ * Factory methods for transforming streams into duplicate-free streams, using
+ * {@link Object#equals(Object)} to determine equality.
+ *
  * @since 1.8
  */
 final class DistinctOps {
@@ -42,16 +44,19 @@
     private DistinctOps() { }
 
     /**
-     * Appends a "distinct" operation to the provided stream.
+     * Appends a "distinct" operation to the provided stream, and returns the new stream.
      *
      * @param <T> The type of both input and output elements
      * @param upstream A reference stream with element type T
+     * @return the new stream
      */
     static<T> ReferencePipeline<T, T> makeRef(AbstractPipeline<?, T, ?> upstream) {
         return new ReferencePipeline.StatefulOp<T, T>(upstream, StreamShape.REFERENCE,
                                                       StreamOpFlag.IS_DISTINCT | StreamOpFlag.NOT_SIZED) {
             @Override
-            <P_IN> Node<T> opEvaluateParallel(PipelineHelper<T> helper, Spliterator<P_IN> spliterator, IntFunction<T[]> generator) {
+            <P_IN> Node<T> opEvaluateParallel(PipelineHelper<T> helper,
+                                              Spliterator<P_IN> spliterator,
+                                              IntFunction<T[]> generator) {
                 if (StreamOpFlag.DISTINCT.isKnown(helper.getStreamAndOpFlags())) {
                     // No-op
                     return helper.evaluate(spliterator, false, generator);
@@ -80,6 +85,7 @@
                     // and add null
                     Set<T> keys = map.keySet();
                     if (seenNull.get()) {
+                        // TODO Implement a more efficient set-union view, rather than copying
                         keys = new HashSet<>(keys);
                         keys.add(null);
                     }
--- a/src/share/classes/java/util/stream/DoublePipeline.java	Thu Apr 04 21:11:56 2013 +0800
+++ b/src/share/classes/java/util/stream/DoublePipeline.java	Thu Apr 04 14:20:42 2013 -0400
@@ -82,6 +82,7 @@
         super(upstream, opFlags);
     }
 
+    /** Adapt a Sink<Double> to a DoubleConsumer, ideally simply by casting */
     private static DoubleConsumer adapt(Sink<Double> sink) {
         if (sink instanceof DoubleConsumer) {
             return (DoubleConsumer) sink;
@@ -93,6 +94,12 @@
         }
     }
 
+    /** Adapt a Spliterator<Double> to a Spliterator.OfDouble.
+     *
+     * @implNote
+     * The implementation attempts to cast to a Spliterator.OfDouble, and throws an
+     * exception if this cast is not possible.
+     */
     private static Spliterator.OfDouble adapt(Spliterator<Double> s) {
         if (s instanceof Spliterator.OfDouble) {
             return (Spliterator.OfDouble) s;
@@ -291,15 +298,11 @@
 
     // Stateful intermediate ops from DoubleStream
 
-    private DoubleStream slice(long skip, long limit) {
-        return SliceOps.makeDouble(this, skip, limit);
-    }
-
     @Override
     public final DoubleStream limit(long maxSize) {
         if (maxSize < 0)
             throw new IllegalArgumentException(Long.toString(maxSize));
-        return slice(0, maxSize);
+        return SliceOps.makeDouble(this, (long) 0, maxSize);
     }
 
     @Override
@@ -308,15 +311,17 @@
             throw new IllegalArgumentException(Long.toString(startingOffset));
         if (startingOffset == 0)
             return this;
-        else
-            return slice(startingOffset, -1);
+        else {
+            long limit = -1;
+            return SliceOps.makeDouble(this, startingOffset, limit);
+        }
     }
 
     @Override
     public final DoubleStream substream(long startingOffset, long endingOffset) {
         if (startingOffset < 0 || endingOffset < startingOffset)
             throw new IllegalArgumentException(String.format("substream(%d, %d)", startingOffset, endingOffset));
-        return slice(startingOffset, endingOffset - startingOffset);
+        return SliceOps.makeDouble(this, startingOffset, endingOffset - startingOffset);
     }
 
     @Override
@@ -345,7 +350,7 @@
 
     @Override
     public final double sum() {
-        // better algorithm to compensate for errors ?
+        // TODO: better algorithm to compensate for errors
         return reduce(0.0, Double::sum);
     }
 
@@ -432,14 +437,26 @@
         return ((Node.OfDouble) evaluateToArrayNode(Double[]::new)).asDoubleArray();
     }
 
-
     //
 
+    /** Source stage of a DoubleStream */
     static class Head<E_IN> extends DoublePipeline<E_IN> {
+        /**
+         * Constructor for the source stage of a DoubleStream.
+         *
+         * @param source {@code Supplier<Spliterator>} describing the stream source
+         * @param sourceFlags The source flags for the stream source, described in {@link StreamOpFlag}
+         */
         Head(Supplier<? extends Spliterator<Double>> source, int sourceFlags) {
             super(source, sourceFlags);
         }
 
+        /**
+         * Constructor for the source stage of a DoubleStream.
+         *
+         * @param source {@code Spliterator} describing the stream source
+         * @param sourceFlags The source flags for the stream source, described in {@link StreamOpFlag}
+         */
         Head(Spliterator<Double> source, int sourceFlags) {
             super(source, sourceFlags);
         }
@@ -455,7 +472,15 @@
         }
     }
 
+    /** Base class for a stateless intermediate stage of a DoubleStream */
     abstract static class StatelessOp<E_IN> extends DoublePipeline<E_IN> {
+        /**
+         * Construct a new DoubleStream by appending a stateless intermediate operation to
+         * an existing stream.
+         * @param upstream The upstream pipeline stage
+         * @param inputShape The stream shape for the upstream pipeline stage
+         * @param opFlags Operation flags for the new stage
+         */
         StatelessOp(AbstractPipeline<?, E_IN, ?> upstream,
                     StreamShape inputShape,
                     int opFlags) {
@@ -469,7 +494,15 @@
         }
     }
 
+    /** Base class for a stateful intermediate stage of a DoubleStream */
     abstract static class StatefulOp<E_IN> extends DoublePipeline<E_IN> {
+        /**
+         * Construct a new DoubleStream by appending a stateful intermediate operation to
+         * an existing stream.
+         * @param upstream The upstream pipeline stage
+         * @param inputShape The stream shape for the upstream pipeline stage
+         * @param opFlags Operation flags for the new stage
+         */
         StatefulOp(AbstractPipeline<?, E_IN, ?> upstream,
                    StreamShape inputShape,
                    int opFlags) {
--- a/src/share/classes/java/util/stream/FindOps.java	Thu Apr 04 21:11:56 2013 +0800
+++ b/src/share/classes/java/util/stream/FindOps.java	Thu Apr 04 14:20:42 2013 -0400
@@ -30,7 +30,7 @@
 import java.util.function.Supplier;
 
 /**
- * A factory for creating instances of a short-circuiting {@code TerminalOp}
+ * Factory for creating instances of a short-circuiting {@code TerminalOp}
  * that searches for an element in a stream pipeline, and terminates when it
  * finds one.  The search supports find-first (find the first element in the
  * encounter order) and find-any (find any element, may not be the first in
--- a/src/share/classes/java/util/stream/FlatMapper.java	Thu Apr 04 21:11:56 2013 +0800
+++ b/src/share/classes/java/util/stream/FlatMapper.java	Thu Apr 04 14:20:42 2013 -0400
@@ -34,27 +34,30 @@
  *
  * @apiNote
  * Rather than representing the result as a {@code Collection} or array, the results are
- * emitted directly into a {@link Consumer}, to avoid the overhead of creating and iterating the (possibly empty
- * or small) intermediate data structure.
+ * emitted directly into a {@link Consumer}, to avoid the overhead of creating and iterating
+ * the (possibly empty or small) intermediate data structure.
  * @since 1.8
  */
 @FunctionalInterface
 public interface FlatMapper<T, U> {
     /**
-     * Accept an input element and emit zero or more output elements into the provided {@code Consumer}
+     * Accept an input element and emit zero or more output elements into the provided
+     * {@code Consumer}
      * @param element The input element
      * @param sink A {@code Consumer} to receive the output elements
      */
     void flattenInto(T element, Consumer<U> sink);
 
     /**
-     * An operation that maps an element of type {@code T} to zero or more elements of type {@code int}.
+     * An operation that maps an element of type {@code T} to zero or more elements of type
+     * {@code int}.
      * This is the int-bearing specialization of {@code FlatMapper}.
      */
     @FunctionalInterface
     interface ToInt<T> {
         /**
-         * Accept an input element and emit zero or more output elements into the provided {@code IntConsumer}
+         * Accept an input element and emit zero or more output elements into the provided
+         * {@code IntConsumer}
          * @param element The input element
          * @param sink A {@code IntConsumer} to receive the output elements
          */
@@ -62,13 +65,15 @@
     }
 
     /**
-     * An operation that maps an element of type {@code T} to zero or more elements of type {@code long}.
+     * An operation that maps an element of type {@code T} to zero or more elements of type
+     * {@code long}.
      * This is the long-bearing specialization of {@code FlatMapper}.
      */
     @FunctionalInterface
     interface ToLong<T> {
         /**
-         * Accept an input element and emit zero or more output elements into the provided {@code LongConsumer}
+         * Accept an input element and emit zero or more output elements into the provided
+         * {@code LongConsumer}
          * @param element The input element
          * @param sink A {@code LongConsumer} to receive the output elements
          */
@@ -76,13 +81,15 @@
     }
 
     /**
-     * An operation that maps an element of type {@code T} to zero or more elements of type {@code double}.
+     * An operation that maps an element of type {@code T} to zero or more elements of type
+     * {@code double}.
      * This is the double-bearing specialization of {@code FlatMapper}.
      */
     @FunctionalInterface
     interface ToDouble<T> {
         /**
-         * Accept an input element and emit zero or more output elements into the provided {@code DoubleConsumer}
+         * Accept an input element and emit zero or more output elements into the provided
+         * {@code DoubleConsumer}
          * @param element The input element
          * @param sink A {@code DoubleConsumer} to receive the output elements
          */
@@ -90,13 +97,15 @@
     }
 
     /**
-     * An operation that maps an element of type {@code int} to zero or more elements of type {@code int}.
+     * An operation that maps an element of type {@code int} to zero or more elements of type
+     * {@code int}.
      * This is the int-to-int specialization of {@code FlatMapper}.
      */
     @FunctionalInterface
     interface OfIntToInt {
         /**
-         * Accept an input element and emit zero or more output elements into the provided {@code IntConsumer}
+         * Accept an input element and emit zero or more output elements into the provided
+         * {@code IntConsumer}
          * @param element The input element
          * @param sink A {@code IntConsumer} to receive the output elements
          */
@@ -104,13 +113,15 @@
     }
 
     /**
-     * An operation that maps an element of type {@code long} to zero or more elements of type {@code long}.
+     * An operation that maps an element of type {@code long} to zero or more elements of type
+     * {@code long}.
      * This is the long-to-long specialization of {@code FlatMapper}.
      */
     @FunctionalInterface
     interface OfLongToLong {
         /**
-         * Accept an input element and emit zero or more output elements into the provided {@code LongConsumer}
+         * Accept an input element and emit zero or more output elements into the provided
+         * {@code LongConsumer}
          * @param element The input element
          * @param sink A {@code LongConsumer} to receive the output elements
          */
@@ -118,13 +129,15 @@
     }
 
     /**
-     * An operation that maps an element of type {@code double} to zero or more elements of type {@code double}.
+     * An operation that maps an element of type {@code double} to zero or more elements of type
+     * {@code double}.
      * This is the double-to-double specialization of {@code FlatMapper}.
      */
     @FunctionalInterface
     interface OfDoubleToDouble {
         /**
-         * Accept an input element and emit zero or more output elements into the provided {@code DoubleConsumer}
+         * Accept an input element and emit zero or more output elements into the provided
+         * {@code DoubleConsumer}
          * @param element The input element
          * @param sink A {@code DoubleConsumer} to receive the output elements
          */
--- a/src/share/classes/java/util/stream/ForEachOps.java	Thu Apr 04 21:11:56 2013 +0800
+++ b/src/share/classes/java/util/stream/ForEachOps.java	Thu Apr 04 14:20:42 2013 -0400
@@ -34,7 +34,7 @@
 import java.util.Objects;
 
 /**
- * A factory for creating instances of {@code TerminalOp} that implement
+ * Factory for creating instances of {@code TerminalOp} that implement
  * {@code forEach} traversal over elements of a stream.
  *
  * <p>{@code forEach} traverses all elements of a stream and sends those
--- a/src/share/classes/java/util/stream/IntPipeline.java	Thu Apr 04 21:11:56 2013 +0800
+++ b/src/share/classes/java/util/stream/IntPipeline.java	Thu Apr 04 14:20:42 2013 -0400
@@ -467,11 +467,24 @@
 
     //
 
+    /** Source stage of an IntStream */
     static class Head<E_IN> extends IntPipeline<E_IN> {
+        /**
+         * Constructor for the source stage of an IntStream.
+         *
+         * @param source {@code Supplier<Spliterator>} describing the stream source
+         * @param sourceFlags The source flags for the stream source, described in {@link StreamOpFlag}
+         */
         Head(Supplier<? extends Spliterator<Integer>> source, int sourceFlags) {
             super(source, sourceFlags);
         }
 
+        /**
+         * Constructor for the source stage of an IntStream.
+         *
+         * @param source {@code Spliterator} describing the stream source
+         * @param sourceFlags The source flags for the stream source, described in {@link StreamOpFlag}
+         */
         Head(Spliterator<Integer> source, int sourceFlags) {
             super(source, sourceFlags);
         }
@@ -487,7 +500,15 @@
         }
     }
 
+    /** Base class for a stateless intermediate stage of an IntStream */
     abstract static class StatelessOp<E_IN> extends IntPipeline<E_IN> {
+        /**
+         * Construct a new IntStream by appending a stateless intermediate operation to
+         * an existing stream.
+         * @param upstream The upstream pipeline stage
+         * @param inputShape The stream shape for the upstream pipeline stage
+         * @param opFlags Operation flags for the new stage
+         */
         StatelessOp(AbstractPipeline<?, E_IN, ?> upstream,
                     StreamShape inputShape,
                     int opFlags) {
@@ -501,7 +522,15 @@
         }
     }
 
+    /** Base class for a stateful intermediate stage of an IntStream */
     abstract static class StatefulOp<E_IN> extends IntPipeline<E_IN> {
+        /**
+         * Construct a new IntStream by appending a stateful intermediate operation to
+         * an existing stream.
+         * @param upstream The upstream pipeline stage
+         * @param inputShape The stream shape for the upstream pipeline stage
+         * @param opFlags Operation flags for the new stage
+         */
         StatefulOp(AbstractPipeline<?, E_IN, ?> upstream,
                    StreamShape inputShape,
                    int opFlags) {
--- a/src/share/classes/java/util/stream/LongPipeline.java	Thu Apr 04 21:11:56 2013 +0800
+++ b/src/share/classes/java/util/stream/LongPipeline.java	Thu Apr 04 14:20:42 2013 -0400
@@ -450,11 +450,24 @@
 
     //
 
+    /** Source stage of a LongPipeline */
     static class Head<E_IN> extends LongPipeline<E_IN> {
+        /**
+         * Constructor for the source stage of a LongStream.
+         *
+         * @param source {@code Supplier<Spliterator>} describing the stream source
+         * @param sourceFlags The source flags for the stream source, described in {@link StreamOpFlag}
+         */
         Head(Supplier<? extends Spliterator<Long>> source, int sourceFlags) {
             super(source, sourceFlags);
         }
 
+        /**
+         * Constructor for the source stage of a LongStream.
+         *
+         * @param source {@code Spliterator} describing the stream source
+         * @param sourceFlags The source flags for the stream source, described in {@link StreamOpFlag}
+         */
         Head(Spliterator<Long> source, int sourceFlags) {
             super(source, sourceFlags);
         }
@@ -470,7 +483,15 @@
         }
     }
 
+    /** Base class for a stateless intermediate stage of a LongStream */
     abstract static class StatelessOp<E_IN> extends LongPipeline<E_IN> {
+        /**
+         * Construct a new LongStream by appending a stateless intermediate operation to
+         * an existing stream.
+         * @param upstream The upstream pipeline stage
+         * @param inputShape The stream shape for the upstream pipeline stage
+         * @param opFlags Operation flags for the new stage
+         */
         StatelessOp(AbstractPipeline<?, E_IN, ?> upstream,
                     StreamShape inputShape,
                     int opFlags) {
@@ -484,7 +505,15 @@
         }
     }
 
+    /** Base class for a stateful intermediate stage of a LongStream */
     abstract static class StatefulOp<E_IN> extends LongPipeline<E_IN> {
+        /**
+         * Construct a new LongStream by appending a stateful intermediate operation to
+         * an existing stream.
+         * @param upstream The upstream pipeline stage
+         * @param inputShape The stream shape for the upstream pipeline stage
+         * @param opFlags Operation flags for the new stage
+         */
         StatefulOp(AbstractPipeline<?, E_IN, ?> upstream,
                    StreamShape inputShape,
                    int opFlags) {
--- a/src/share/classes/java/util/stream/MatchOps.java	Thu Apr 04 21:11:56 2013 +0800
+++ b/src/share/classes/java/util/stream/MatchOps.java	Thu Apr 04 14:20:42 2013 -0400
@@ -33,7 +33,7 @@
 import java.util.function.Supplier;
 
 /**
- * A factory for creating instances of a short-circuiting {@code TerminalOp}
+ * Factory for creating instances of a short-circuiting {@code TerminalOp}
  * that evaluates a predicate on the elements of a stream and determines whether
  * all, any or none of those elements match the predicate.
  *
--- a/src/share/classes/java/util/stream/PipelineHelper.java	Thu Apr 04 21:11:56 2013 +0800
+++ b/src/share/classes/java/util/stream/PipelineHelper.java	Thu Apr 04 14:20:42 2013 -0400
@@ -43,10 +43,10 @@
  * by this {@code PipelineHelper}.  The {@code PipelineHelper} is passed to the
  * {@link TerminalOp#evaluateParallel(PipelineHelper, java.util.Spliterator)},
  * {@link TerminalOp#evaluateSequential(PipelineHelper, java.util.Spliterator)}, and
- * {@link AbstractPipeline#opEvaluateParallel(PipelineHelper, java.util.Spliterator, java.util.function.IntFunction)},
- * methods, which can use the {@code PipelineHelper} to access the source
- * {@code Spliterator} for the pipeline, information about the pipeline such as
- * input shape, output shape, stream flags, and size, and use the helper methods
+ * {@link AbstractPipeline#opEvaluateParallel(PipelineHelper, java.util.Spliterator,
+ * java.util.function.IntFunction)}, methods, which can use the {@code PipelineHelper}
+ * to access the source {@code Spliterator} for the pipeline, information about the pipeline
+ * such as input shape, output shape, stream flags, and size, and use the helper methods
  * such as {@link #wrapAndCopyInto(Sink, Spliterator)}, {@link #copyInto(Sink, Spliterator)},
  * and {@link #wrapSink(Sink)} to execute pipeline operations.
  *
--- a/src/share/classes/java/util/stream/ReduceOps.java	Thu Apr 04 21:11:56 2013 +0800
+++ b/src/share/classes/java/util/stream/ReduceOps.java	Thu Apr 04 14:20:42 2013 -0400
@@ -43,7 +43,7 @@
 import java.util.function.Supplier;
 
 /**
- * A factory for the creating instances of {@code TerminalOp) that implement
+ * Factory for the creating instances of {@code TerminalOp) that implement
  * reductions.
  *
  * @since 1.8
--- a/src/share/classes/java/util/stream/ReferencePipeline.java	Thu Apr 04 21:11:56 2013 +0800
+++ b/src/share/classes/java/util/stream/ReferencePipeline.java	Thu Apr 04 14:20:42 2013 -0400
@@ -470,11 +470,24 @@
 
     //
 
+    /** Source stage of a ReferencePipeline */
     static class Head<E_IN, E_OUT> extends ReferencePipeline<E_IN, E_OUT> {
+        /**
+         * Constructor for the source stage of a Stream.
+         *
+         * @param source {@code Supplier<Spliterator>} describing the stream source
+         * @param sourceFlags The source flags for the stream source, described in {@link StreamOpFlag}
+         */
         Head(Supplier<? extends Spliterator<?>> source, int sourceFlags) {
             super(source, sourceFlags);
         }
 
+        /**
+         * Constructor for the source stage of a Stream.
+         *
+         * @param source {@code Spliterator} describing the stream source
+         * @param sourceFlags The source flags for the stream source, described in {@link StreamOpFlag}
+         */
         Head(Spliterator<?> source, int sourceFlags) {
             super(source, sourceFlags);
         }
@@ -490,7 +503,15 @@
         }
     }
 
+    /** Base class for a stateless intermediate stage of a Stream */
     abstract static class StatelessOp<E_IN, E_OUT> extends ReferencePipeline<E_IN, E_OUT> {
+        /**
+         * Construct a new Stream by appending a stateless intermediate operation to
+         * an existing stream.
+         * @param upstream The upstream pipeline stage
+         * @param inputShape The stream shape for the upstream pipeline stage
+         * @param opFlags Operation flags for the new stage
+         */
         StatelessOp(AbstractPipeline<?, E_IN, ?> upstream,
                     StreamShape inputShape,
                     int opFlags) {
@@ -504,7 +525,15 @@
         }
     }
 
+    /** Base class for a stateful intermediate stage of a Stream */
     abstract static class StatefulOp<E_IN, E_OUT> extends ReferencePipeline<E_IN, E_OUT> {
+        /**
+         * Construct a new Stream by appending a stateful intermediate operation to
+         * an existing stream.
+         * @param upstream The upstream pipeline stage
+         * @param inputShape The stream shape for the upstream pipeline stage
+         * @param opFlags Operation flags for the new stage
+         */
         StatefulOp(AbstractPipeline<?, E_IN, ?> upstream,
                    StreamShape inputShape,
                    int opFlags) {
--- a/src/share/classes/java/util/stream/SliceOps.java	Thu Apr 04 21:11:56 2013 +0800
+++ b/src/share/classes/java/util/stream/SliceOps.java	Thu Apr 04 14:20:42 2013 -0400
@@ -32,10 +32,12 @@
 
 /**
  * Factory methods for transforming a stream into a subsequence of itself.
+ *
  * @since 1.8
  */
 final class SliceOps {
 
+    // No instances
     private SliceOps() { }
 
     /**
@@ -354,6 +356,7 @@
             // Don't call super.onCompletion(), we don't look at the child nodes until farther up the tree
         }
 
+        /** Compute the cumulative size of the longest leading prefix of completed children */
         private long leftSize() {
             if (completed)
                 return thisNodeSize;
@@ -397,6 +400,10 @@
             }
         }
 
+        /**
+         * Return a new node describing the reslut of truncating an existing Node
+         * at the left and/or right
+         */
         private Node<T> truncateNode(Node<T> input, long skipLeft, long skipRight) {
             if (skipLeft == 0 && skipRight == 0)
                 return input;
--- a/src/share/classes/java/util/stream/Tripwire.java	Thu Apr 04 21:11:56 2013 +0800
+++ b/src/share/classes/java/util/stream/Tripwire.java	Thu Apr 04 14:20:42 2013 -0400
@@ -37,7 +37,7 @@
  * @apiNote
  * Typical usage would be for boxing code to do:
  * <pre>{@code
- *     if (Tripwire.enabled)
+ *     if (Tripwire.ENABLED)
  *         Tripwire.trip(getClass(), "{0} calling Sink.OfInt.accept(Integer)");
  * }</pre>
  *