changeset 7572:f4f14310067f

Correct tense.
author psandoz
date Thu, 07 Mar 2013 13:58:43 +0100
parents 93d85abe032b
children ec95dfc8b12c
files src/share/classes/java/util/Tripwire.java src/share/classes/java/util/stream/AbstractShortCircuitTask.java src/share/classes/java/util/stream/AbstractTask.java src/share/classes/java/util/stream/BaseStream.java src/share/classes/java/util/stream/FindOps.java src/share/classes/java/util/stream/IntermediateOp.java src/share/classes/java/util/stream/MatchOps.java src/share/classes/java/util/stream/Node.java src/share/classes/java/util/stream/PipelineHelper.java src/share/classes/java/util/stream/Sink.java src/share/classes/java/util/stream/StatefulOp.java src/share/classes/java/util/stream/StreamOpFlag.java src/share/classes/java/util/stream/TerminalOp.java src/share/classes/java/util/stream/Tripwire.java
diffstat 14 files changed, 110 insertions(+), 99 deletions(-) [+]
line wrap: on
line diff
--- a/src/share/classes/java/util/Tripwire.java	Thu Mar 07 13:13:44 2013 +0100
+++ b/src/share/classes/java/util/Tripwire.java	Thu Mar 07 13:58:43 2013 +0100
@@ -53,7 +53,7 @@
     private Tripwire() { }
 
     /**
-     * Produce a log warning, using {@code Logger.getLogger(className)}, using
+     * Produces a log warning, using {@code Logger.getLogger(className)}, using
      * the supplied message.  The class name of {@code trippingClass} will be
      * used as the first parameter to the message.
      *
--- a/src/share/classes/java/util/stream/AbstractShortCircuitTask.java	Thu Mar 07 13:13:44 2013 +0100
+++ b/src/share/classes/java/util/stream/AbstractShortCircuitTask.java	Thu Mar 07 13:58:43 2013 +0100
@@ -68,7 +68,7 @@
     }
 
     /**
-     * Return the value indicating the computation completed with no task
+     * Returns the value indicating the computation completed with no task
      * finding a short-circuitable result.  For example, for a "find" operation,
      * this might be null or an empty {@code Optional}.
      */
@@ -91,7 +91,7 @@
     }
 
     /**
-     * Declare that a globally valid result has been found.  If another task has
+     * Declares that a globally valid result has been found.  If another task has
      * not already found the answer, the result is installed in
      * {@code sharedResult}.  The {@code compute()} method will check
      * {@code sharedResult} before proceeding with computation, so this causes
@@ -103,7 +103,7 @@
     }
 
     /**
-     * Set a local result for this task.  If this task is the root, set the
+     * Sets a local result for this task.  If this task is the root, set the
      * shared result instead (if not already set).
      */
     @Override
@@ -116,14 +116,14 @@
             super.setLocalResult(localResult);
     }
 
-    /** Retrieve the local result for this task */
+    /** Retrieves the local result for this task */
     @Override
     public R getRawResult() {
         return getLocalResult();
     }
 
     /**
-     * Retrieve the local result for this task.  If this task is the root,
+     * Retrieves the local result for this task.  If this task is the root,
      * retrieves the shared result instead.
      */
     @Override
@@ -142,7 +142,7 @@
     }
 
     /**
-     * Query whether this task is canceled.  A task is considered canceled if it
+     * Queries whether this task is canceled.  A task is considered canceled if it
      * or any of its parents have been canceled.
      */
     protected boolean taskCanceled() {
@@ -154,7 +154,7 @@
     }
 
     /**
-     * Cancel all tasks which succeed this one in the encounter order.  This
+     * Cancels all tasks which succeed this one in the encounter order.  This
      * includes canceling all the current task's later siblings, as well as the
      * later siblings of all its parents.
      */
--- a/src/share/classes/java/util/stream/AbstractTask.java	Thu Mar 07 13:13:44 2013 +0100
+++ b/src/share/classes/java/util/stream/AbstractTask.java	Thu Mar 07 13:58:43 2013 +0100
@@ -133,26 +133,26 @@
     }
 
     /**
-     * Construct a new node of type T whose parent is the receiver; must call
+     * Constructs a new node of type T whose parent is the receiver; must call
      * the AbstractTask(T, Spliterator) constructor with the receiver and the
      * provided Spliterator.
      */
     protected abstract T makeChild(Spliterator<P_IN> spliterator);
 
     /**
-     * Compute the result associated with a leaf node.  Will be called by
+     * Computes the result associated with a leaf node.  Will be called by
      * {@code compute()} and the result passed to @{code setLocalResult()}
      */
     protected abstract R doLeaf();
 
-    /** Suggest a target leaf size based on the initial size estimate */
+    /** Suggests a target leaf size based on the initial size estimate */
     public static long suggestTargetSize(long sizeEstimate) {
         long est = sizeEstimate / (ForkJoinPool.getCommonPoolParallelism() << 3);
         return est > 0L ? est : 1L; // slack of 3; at least one
     }
 
     /**
-     * Suggest whether it is adviseable to split the provided spliterator based
+     * Suggests whether it is adviseable to split the provided spliterator based
      * on target size and other considerations, such as pool state
      */
     public static<P_IN, P_OUT> boolean suggestSplit(PipelineHelper<P_IN, P_OUT> helper,
@@ -164,7 +164,7 @@
     }
 
     /**
-     * Suggest whether it is adviseable to split this task based on target size
+     * Suggests whether it is adviseable to split this task based on target size
      * and other considerations
      */
     public boolean suggestSplit() {
@@ -185,14 +185,14 @@
     }
 
     /**
-     * Retrieve a result previously stored with {@link #setLocalResult}
+     * Retrieves a result previously stored with {@link #setLocalResult}
      */
     protected R getLocalResult() {
         return localResult;
     }
 
     /**
-     * Associate the result with the task, can be retrieved with
+     * Associates the result with the task, can be retrieved with
      * {@link #getLocalResult}
      */
     protected void setLocalResult(R localResult) {
@@ -200,7 +200,7 @@
     }
 
     /**
-     * Is this task a leaf node?  (Only valid after {@link #compute} has been
+     * Determines if this this task a leaf node.  (Only valid after {@link #compute} has been
      * called on this node).  If the node is not a leaf node, then children will
      * be non-null and numChildren will be positive.
      */
@@ -208,13 +208,15 @@
         return children == null;
     }
 
-    /** Is this task the root node? */
+    /**
+     * Determines if this task is a root node
+     */
     protected boolean isRoot() {
         return getParent() == null;
     }
 
     /**
-     * Return the parent of this task, or null if this task is the root
+     * Returns the parent of this task, or null if this task is the root
      */
     @SuppressWarnings("unchecked")
     protected T getParent() {
@@ -222,7 +224,7 @@
     }
 
     /**
-     * Decide whether or not to split this task further or compute it directly.
+     * Decides whether or not to split this task further or compute it directly.
      * If computing directly, call {@code doLeaf} and pass the result to
      * {@code setRawResult}.  If splitting, set up the child-related fields,
      * create the child tasks, fork the leftmost (prefix) child task,
@@ -239,7 +241,7 @@
     }
 
     /**
-     * Decide whether or not to split a task further or compute it directly. If
+     * Decides whether or not to split a task further or compute it directly. If
      * computing directly, call {@code doLeaf} and pass the result to
      * {@code setRawResult}.  If splitting, set up the child-related fields,
      * create the child tasks, fork the leftmost (prefix) child tasks, and
@@ -293,7 +295,7 @@
     }
 
     /**
-     * Determine if the task can be computed.
+     * Determines if the task can be computed.
      *
      * @return true if this task can be computed to either calculate the leaf
      *         via {@link #doLeaf()} or split, otherwise false if this task
--- a/src/share/classes/java/util/stream/BaseStream.java	Thu Mar 07 13:13:44 2013 +0100
+++ b/src/share/classes/java/util/stream/BaseStream.java	Thu Mar 07 13:58:43 2013 +0100
@@ -36,7 +36,7 @@
  */
 interface BaseStream<T, S extends BaseStream<T, S>> {
     /**
-     * Return an iterator for the elements of this stream.  This is
+     * Returns an iterator for the elements of this stream.  This is
      * a <a href="package-summary.html#StreamOps">terminal operation</a>.
      *
      * @return the element iterator for this stream
@@ -44,7 +44,7 @@
     Iterator<T> iterator();
 
     /**
-     * Return a spliterator for the elements of this stream.  This is
+     * Returns a spliterator for the elements of this stream.  This is
      * a <a href="package-summary.html#StreamOps">terminal operation</a>.
      *
      * @return the element spliterator for this stream
@@ -59,7 +59,7 @@
     boolean isParallel();
 
     /**
-     * Return the composition of stream flags of the stream source and all
+     * Returns the composition of stream flags of the stream source and all
      * intermediate operations.
      *
      * @return the composition of stream flags of the stream source and all
@@ -69,7 +69,7 @@
     int getStreamFlags();
 
     /**
-     * Produce a stream which has the same contents as this stream, but is a
+     * Produces a stream which has the same contents as this stream, but is a
      * sequential stream.  If this stream is already sequential, may return
      * itself.  This is a
      * <a href="package-summary.html#StreamOps">stateful intermediate operation</a>.
@@ -79,7 +79,7 @@
     S sequential();
 
     /**
-     * Produce a stream which has the same contents as this stream, but is a
+     * Produces a stream which has the same contents as this stream, but is a
      * parallel stream.  If this stream is already parallel, may return itself.
      * This is a
      * <a href="package-summary.html#StreamOps">stateful intermediate operation</a>.
--- a/src/share/classes/java/util/stream/FindOps.java	Thu Mar 07 13:13:44 2013 +0100
+++ b/src/share/classes/java/util/stream/FindOps.java	Thu Mar 07 13:58:43 2013 +0100
@@ -43,7 +43,7 @@
     private FindOps() { }
 
     /**
-     * Construct a {@code TerminalOp} for streams of objects
+     * Constructs a {@code TerminalOp} for streams of objects
      *
      * @param mustFindFirst Whether the {@code TerminalOp} must produce the
      *        first element in the encounter order
@@ -56,7 +56,7 @@
     }
 
     /**
-     * Construct a {@code TerminalOp} for streams of ints
+     * Constructs a {@code TerminalOp} for streams of ints
      *
      * @param mustFindFirst Whether the {@code TerminalOp} must produce the
      *        first element in the encounter order
@@ -68,7 +68,7 @@
     }
 
     /**
-     * Construct a {@code TerminalOp} for streams of longs
+     * Constructs a {@code TerminalOp} for streams of longs
      *
      * @param mustFindFirst Whether the {@code TerminalOp} must produce the
      *        first element in the encounter order
@@ -80,7 +80,7 @@
     }
 
     /**
-     * Construct a {@code TerminalOp} for streams of doubles
+     * Constructs a {@code TerminalOp} for streams of doubles
      *
      * @param mustFindFirst Whether the {@code TerminalOp} must produce the
      *        first element in the encounter order
@@ -109,7 +109,7 @@
         final Supplier<TerminalSink<T, O>> sinkSupplier;
 
         /**
-         * Construct a {@code FindOp}
+         * Constructs a {@code FindOp}
          *
          * @param mustFindFirst If true, must find the first element in
          *        encounter order, otherwise can find any element
--- a/src/share/classes/java/util/stream/IntermediateOp.java	Thu Mar 07 13:13:44 2013 +0100
+++ b/src/share/classes/java/util/stream/IntermediateOp.java	Thu Mar 07 13:58:43 2013 +0100
@@ -91,7 +91,7 @@
 interface IntermediateOp<E_IN, E_OUT> {
 
     /**
-     * Get the shape of the input type of this operation
+     * Gets the shape of the input type of this operation
      *
      * @implSpec The default returns {@code StreamShape.REFERENCE}
      * @return Shape of the input type of this operation
@@ -99,7 +99,7 @@
     default StreamShape inputShape() { return StreamShape.REFERENCE; }
 
     /**
-     * Get the shape of the output type of this operation
+     * Gets the shape of the output type of this operation
      *
      * @implSpec The default returns {@code StreamShape.REFERENCE}
      * @return Shape of the output type of this operation
@@ -107,7 +107,7 @@
     default StreamShape outputShape() { return StreamShape.REFERENCE; }
 
     /**
-     * Get the operation flags of this operation.
+     * Gets the operation flags of this operation.
      *
      * @implSpec The default returns {@code 0}
      * @return a bitmap describing the operation flags of this operation
@@ -116,7 +116,7 @@
     default int getOpFlags() { return 0; }
 
     /**
-     * Return whether this operation is stateful or not.  If it is stateful,
+     * Returns whether this operation is stateful or not.  If it is stateful,
      * then the method {@link #evaluateParallel(PipelineHelper)} must be
      * overridden.
      *
@@ -126,7 +126,7 @@
     default boolean isStateful() { return false; }
 
     /**
-     * Accept a {@code Sink} which will receive the results of this operation,
+     * Accepts a {@code Sink} which will receive the results of this operation,
      * and return a {@code Sink} which accepts elements of the input type of
      * this operation and which performs the operation, passing the results to
      * the provided {@code Sink}.
@@ -146,7 +146,7 @@
     Sink<E_IN> wrapSink(int flags, Sink<E_OUT> sink);
 
     /**
-     * Perform a parallel evaluation of the operation using the specified
+     * Performs a parallel evaluation of the operation using the specified
      * {@code PipelineHelper}, which describes the stream source and upstream
      * intermediate operations.  Only called on stateful operations.  If
      * {@link #isStateful()} returns true then implementations must override the
--- a/src/share/classes/java/util/stream/MatchOps.java	Thu Mar 07 13:13:44 2013 +0100
+++ b/src/share/classes/java/util/stream/MatchOps.java	Thu Mar 07 13:58:43 2013 +0100
@@ -67,7 +67,7 @@
     }
 
     /**
-     * Construct a {@code TerminalOp} for the given predicate and quantified
+     * Constructs a {@code TerminalOp} for the given predicate and quantified
      * match criteria
      *
      * @param predicate The {@code Predicate} to apply to stream elements
@@ -104,7 +104,7 @@
     }
 
     /**
-     * Construct a {@code TerminalOp} for the given predicate and quantified
+     * Constructs a {@code TerminalOp} for the given predicate and quantified
      * match criteria for an {@code IntStream}
      *
      * @param predicate The {@code Predicate} to apply to stream elements
@@ -137,7 +137,7 @@
     }
 
     /**
-     * Construct a {@code TerminalOp} for the given predicate and quantified
+     * Constructs a {@code TerminalOp} for the given predicate and quantified
      * match criteria for a {@code LongStream}
      *
      * @param predicate The {@code Predicate} to apply to stream elements
@@ -171,7 +171,7 @@
     }
 
     /**
-     * Construct a {@code TerminalOp} for the given predicate and quantified
+     * Constructs a {@code TerminalOp} for the given predicate and quantified
      * match criteria for a {@code DoubleStream}
      *
      * @param predicate The {@code Predicate} to apply to stream elements
@@ -217,7 +217,7 @@
         final Supplier<BooleanTerminalSink<T>> sinkSupplier;
 
         /**
-         * Construct a {@code MatchOp}
+         * Constructs a {@code MatchOp}
          *
          * @param shape The output shape of the stream pipeline
          * @param matchKind The kind of quantified match (all, any, none)
--- a/src/share/classes/java/util/stream/Node.java	Thu Mar 07 13:13:44 2013 +0100
+++ b/src/share/classes/java/util/stream/Node.java	Thu Mar 07 13:58:43 2013 +0100
@@ -61,7 +61,7 @@
 interface Node<T> {
 
     /**
-     * Return a {@link Spliterator} describing the elements contained in this
+     * Returns a {@link Spliterator} describing the elements contained in this
      * {@code Node}.
      *
      * @return a {@code Spliterator describing the elements contained in this
@@ -70,7 +70,7 @@
     Spliterator<T> spliterator();
 
     /**
-     * Traverse the elements of this node, and invoke the provided
+     * Traverses the elements of this node, and invoke the provided
      * {@code Consumer} with each element.
      *
      * @param consumer A {@code Consumer} that is to be invoked with each
@@ -79,7 +79,7 @@
     void forEach(Consumer<? super T> consumer);
 
     /**
-     * Return the number of child nodes of this node.
+     * Returns the number of child nodes of this node.
      *
      * @implSpec The default implementation returns zero
      * @return the number of child nodes
@@ -89,7 +89,7 @@
     }
 
     /**
-     * Retrieve the child {@code Node} at a given index.
+     * Retrieves the child {@code Node} at a given index.
      *
      * @implSpec The default implementation throws
      * {@code IndexOutOfBoundsException}
@@ -104,7 +104,7 @@
     }
 
     /**
-     * View this node as an array.
+     * Views this node as an array.
      *
      * <p>Depending on the underlying implementation this may return a reference
      * to an internal array rather than a copy.  It is the callers
@@ -116,7 +116,7 @@
     T[] asArray(IntFunction<T[]> generator);
 
     /**
-     * Copy the content of this {@code Node} into an array, starting at a given
+     * Copies the content of this {@code Node} into an array, starting at a given
      * offset into the array.  It is the caller's responsibility to ensure there
      * is sufficient room in the array.
      *
@@ -130,7 +130,7 @@
     void copyInto(T[] array, int offset);
 
     /**
-     * Get the {@code StreamShape} associated with this {@code Node}.
+     * Gets the {@code StreamShape} associated with this {@code Node}.
      *
      * @implSpec The default in {@code Node} returns
      * {@code StreamShape.REFERENCE}
@@ -141,7 +141,7 @@
     }
 
     /**
-     * Return the number of elements contained in this node
+     * Returns the number of elements contained in this node
      *
      * @return the number of elements contained in this node
      */
@@ -155,7 +155,7 @@
     interface Builder<T> extends Sink<T> {
 
         /**
-         * Build the node.  Should be called after all elements have been pushed
+         * Builds the node.  Should be called after all elements have been pushed
          * and signalled with an invocation of {@link Sink#end()}.
          *
          * @return the resulting {@code Node}
@@ -212,7 +212,7 @@
         }
 
         /**
-         * Traverse the elements of this node, and invoke the provided
+         * Traverses the elements of this node, and invoke the provided
          * {@code IntConsumer} with each element.
          *
          * @param consumer A {@code IntConsumer} that is to be invoked with each
@@ -259,7 +259,7 @@
         }
 
         /**
-         * View this node as an int[] array.
+         * Views this node as an int[] array.
          *
          * <p>Depending on the underlying implementation this may return a
          * reference to an internal array rather than a copy.  It is the callers
@@ -271,7 +271,7 @@
         int[] asIntArray();
 
         /**
-         * Copy the content of this {@code Node} into an int[] array, starting
+         * Copies the content of this {@code Node} into an int[] array, starting
          * at a given offset into the array.  It is the caller's responsibility
          * to ensure there is sufficient room in the array.
          *
@@ -324,7 +324,7 @@
         }
 
         /**
-         * Traverse the elements of this node, and invoke the provided
+         * Traverses the elements of this node, and invoke the provided
          * {@code LongConsumer} with each element.
          *
          * @param consumer A {@code LongConsumer} that is to be invoked with
@@ -371,7 +371,7 @@
         }
 
         /**
-         * View this node as a long[] array.
+         * Views this node as a long[] array.
          *
          * <p>Depending on the underlying implementation this may return a
          * reference to an internal array rather than a copy. It is the callers
@@ -383,7 +383,7 @@
         long[] asLongArray();
 
         /**
-         * Copy the content of this {@code Node} into a long[] array, starting
+         * Copies the content of this {@code Node} into a long[] array, starting
          * at a given offset into the array.  It is the caller's responsibility
          * to ensure there is sufficient room in the array.
          *
@@ -437,7 +437,7 @@
         }
 
         /**
-         * Traverse the elements of this node, and invoke the provided
+         * Traverses the elements of this node, and invoke the provided
          * {@code DoubleConsumer} with each element.
          *
          * @param consumer A {@code DoubleConsumer} that is to be invoked with
@@ -486,7 +486,7 @@
         }
 
         /**
-         * View this node as a double[] array.
+         * Views this node as a double[] array.
          *
          * <p>Depending on the underlying implementation this may return a
          * reference to an internal array rather than a copy.  It is the callers
@@ -498,7 +498,7 @@
         double[] asDoubleArray();
 
         /**
-         * Copy the content of this {@code Node} into a double[] array, starting
+         * Copies the content of this {@code Node} into a double[] array, starting
          * at a given offset into the array.  It is the caller's responsibility
          * to ensure there is sufficient room in the array.
          *
--- a/src/share/classes/java/util/stream/PipelineHelper.java	Thu Mar 07 13:13:44 2013 +0100
+++ b/src/share/classes/java/util/stream/PipelineHelper.java	Thu Mar 07 13:58:43 2013 +0100
@@ -57,19 +57,19 @@
 interface PipelineHelper<P_IN, P_OUT> {
 
     /**
-     * Get the {@code StreamShape} describing the input shape of the pipeline
+     * Gets the {@code StreamShape} describing the input shape of the pipeline
      * @return The input shape of the pipeline
      */
     StreamShape getInputShape();
 
     /**
-     * Get the {@code StreamShape} describing the output shape of the pipeline
+     * Gets the {@code StreamShape} describing the output shape of the pipeline
      * @return The output shape of the pipeline
      */
     StreamShape getOutputShape();
 
     /**
-     * Get the combined stream and operation flags for the output of the
+     * Gets the combined stream and operation flags for the output of the
      * pipeline.  This will incorporate stream flags from the stream source, all
      * the intermediate operations and the terminal operation.
      *
@@ -80,7 +80,7 @@
     int getStreamAndOpFlags();
 
     /**
-     * Get the operation flags for the terminal operation.
+     * Gets the operation flags for the terminal operation.
      *
      * @return the operation flags for the terminal operation.
      * @see StreamOpFlag
@@ -98,7 +98,7 @@
     boolean isParallel();
 
     /**
-     * Get the {@code Spliterator} for the source of the pipeline.  This
+     * Gets the {@code Spliterator} for the source of the pipeline.  This
      * {@code Spliterator} reflects only the source elements, not the actions of
      * any of the intermediate stages.
      *
@@ -126,8 +126,8 @@
     long exactOutputSizeIfKnown(Spliterator<P_IN> spliterator);
 
     /**
-     * Apply the pipeline stages described by this {@code PipelineHelper} to the
-     * provided {@code Spliterator} and send the results to the provided
+     * Applies the pipeline stages described by this {@code PipelineHelper} to
+     * the provided {@code Spliterator} and send the results to the provided
      * {@code Sink}.
      *
      * @implSpec
@@ -143,7 +143,7 @@
     <S extends Sink<P_OUT>> S into(S sink, Spliterator<P_IN> spliterator);
 
     /**
-     * Push elements obtained from the {@code Spliterator} into the provided
+     * Pushes elements obtained from the {@code Spliterator} into the provided
      * {@code Sink}.  If the stream pipeline is known to have short-circuiting
      * stages in it (see {@link StreamOpFlag#SHORT_CIRCUIT}), then the elements
      * are delivered as per {@link #intoWrappedWithCancel(Sink, Spliterator)}.
@@ -159,7 +159,7 @@
     void intoWrapped(Sink<P_IN> wrappedSink, Spliterator<P_IN> spliterator);
 
     /**
-     * Push elements obtained from the {@code Spliterator} into the provided
+     * Pushes elements obtained from the {@code Spliterator} into the provided
      * {@code Sink}, checking {@link Sink#cancellationRequested()} after each
      * element, and stopping if cancellation is requested.
      *
@@ -175,7 +175,7 @@
     void intoWrappedWithCancel(Sink<P_IN> wrappedSink, Spliterator<P_IN> spliterator);
 
     /**
-     * Take a {@code Sink} that accepts elements of the output type of the
+     * Takes a {@code Sink} that accepts elements of the output type of the
      * {@code PipelineHelper}, and wrap it with a {@code Sink} that accepts
      * elements of the input type and implements all the intermediate operations
      * described by this {@code PipelineHelper}, delivering the result into the
@@ -188,8 +188,8 @@
     Sink<P_IN> wrapSink(Sink<P_OUT> sink);
 
     /**
-     * Construct a @{link Node.Builder} compatible with the output shape of this
-     * {@code PipelineHelper}
+     * Constructs a @{link Node.Builder} compatible with the output shape of
+     * this {@code PipelineHelper}
      *
      * @param exactSizeIfKnown if >=0 then a builder will be created that has a
      *        fixed capacity of exactly sizeIfKnown elements; if < 0 then the
@@ -201,7 +201,7 @@
     Node.Builder<P_OUT> makeNodeBuilder(long exactSizeIfKnown);
 
     /**
-     * Collect all output elements resulting from applying the pipeline stages
+     * Collects all output elements resulting from applying the pipeline stages
      * to the source {@code Spliterator} into a {@code Node}.
      *
      * @implSpec
@@ -223,14 +223,14 @@
     Node<P_OUT> collectOutput(boolean flatten);
 
     /**
-     * Get an array factory associated with the output type of this pipeline.
+     * Gets an array factory associated with the output type of this pipeline.
      *
      * @return a factory for arrays of the output type of this pipeline.
      */
     IntFunction<P_OUT[]> arrayGenerator();
 
     /**
-     * Collect all output elements resulting from the applying the pipeline
+     * Collects all output elements resulting from the applying the pipeline
      * stages, plus an additional final stage that is an intermediate operation,
      * to the source {@code Spliterator} into a {code Node}.  The order of
      * output elements will respect the encounter order of the source stream,
--- a/src/share/classes/java/util/stream/Sink.java	Thu Mar 07 13:13:44 2013 +0100
+++ b/src/share/classes/java/util/stream/Sink.java	Thu Mar 07 13:58:43 2013 +0100
@@ -112,7 +112,7 @@
 @FunctionalInterface
 interface Sink<T> extends Consumer<T> {
     /**
-     * Reset the sink state to receive a fresh data set. This is used when a
+     * Resets the sink state to receive a fresh data set. This is used when a
      * {@code Sink} is being reused by multiple calculations.
      * @param size The exact size of the data to be pushed downstream, if
      * known or {@code Long.MAX_VALUE} if unknown or infinite.
@@ -120,23 +120,24 @@
     default void begin(long size) {}
 
     /**
-     * Indicate that all elements have been pushed.  If the {@code Sink} buffers
+     * Indicates that all elements have been pushed.  If the {@code Sink} buffers
      * any results from previous values, they should dump their contents
      * downstream and clear any stored state.
      */
     default void end() {}
 
     /**
-     * Used to communicate to upstream sources that this {@code Sink} does not
+     * Communicates to upstream sources that this {@code Sink} does not
      * wish to receive any more data
-     * @return If cancellation is requested
+     *
+     * @return true if cancellation is requested
      */
     default boolean cancellationRequested() {
         return false;
     }
 
     /**
-     * Accept an int value
+     * Accepts an int value
      * @implSpec The default implementation throws IllegalStateException
      *
      * @throws IllegalStateException If this sink does not accept int values
@@ -146,7 +147,7 @@
     }
 
     /**
-     * Accept a long value
+     * Accepts a long value
      * @implSpec The default implementation throws IllegalStateException
      *
      * @throws IllegalStateException If this sink does not accept long values
@@ -156,7 +157,7 @@
     }
 
     /**
-     * Accept a double value
+     * Accepts a double value
      * @implSpec The default implementation throws IllegalStateException
      *
      * @throws IllegalStateException If this sink does not accept double values
--- a/src/share/classes/java/util/stream/StatefulOp.java	Thu Mar 07 13:13:44 2013 +0100
+++ b/src/share/classes/java/util/stream/StatefulOp.java	Thu Mar 07 13:58:43 2013 +0100
@@ -27,7 +27,8 @@
 interface StatefulOp<E> extends IntermediateOp<E, E> {
 
     /**
-     * This method must return {@code true}
+     * Returns {@code true}.  Any overriding implementations must also return
+     * {@code true}
      * @implSpec The default implementation returns {@code true}
      * @return {@code true}
      */
--- a/src/share/classes/java/util/stream/StreamOpFlag.java	Thu Mar 07 13:13:44 2013 +0100
+++ b/src/share/classes/java/util/stream/StreamOpFlag.java	Thu Mar 07 13:58:43 2013 +0100
@@ -398,7 +398,7 @@
     }
 
     /**
-     * Get the bitmap associated with setting this characteristic
+     * Gets the bitmap associated with setting this characteristic
      * @return the bitmap for setting this characteristic
      */
     int set() {
@@ -406,7 +406,7 @@
     }
 
     /**
-     * Get the bitmap associated with clearing this characteristic
+     * Gets the bitmap associated with clearing this characteristic
      * @return the bitmap for clearing this characteristic
      */
     int clear() {
@@ -414,7 +414,7 @@
     }
 
     /**
-     * Is this flag a stream-based flag?
+     * Determines if this flag is a stream-based flag.
      *
      * @return true if a stream-based flag, otherwise false.
      */
@@ -423,7 +423,7 @@
     }
 
     /**
-     * Check if this flag is set on stream flags, injected on operation flags,
+     * Checks if this flag is set on stream flags, injected on operation flags,
      * and injected on combined stream and operation flags.
      *
      * @param flags the stream flags, operation flags, or combined stream and
@@ -435,7 +435,7 @@
     }
 
     /**
-     * Check if this flag is cleared on operation flags or combined stream and
+     * Checks if this flag is cleared on operation flags or combined stream and
      * operation flags.
      *
      * @param flags the operation flags or combined stream and operations flags.
@@ -446,7 +446,7 @@
     }
 
     /**
-     * Check if this flag is preserved on combined stream and operation flags.
+     * Checks if this flag is preserved on combined stream and operation flags.
      *
      * @param flags the combined stream and operations flags.
      * @return true if this flag is preserved, otherwise false.
@@ -456,6 +456,7 @@
     }
 
     /**
+     * Determines if this flag can be set for a flag type.
      *
      * @param t the flag type.
      * @return true if this flag can be set for the flag type, otherwise false.
@@ -582,7 +583,7 @@
     }
 
     /**
-     * Combine stream or operation flags with previously combined stream and
+     * Combines stream or operation flags with previously combined stream and
      * operation flags to produce updated combined stream and operation flags.
      * <p>
      * A flag set on stream flags or injected on operation flags,
@@ -639,7 +640,7 @@
     }
 
     /**
-     * Convert combined stream and operation flags to stream flags.
+     * Converts combined stream and operation flags to stream flags.
      *
      * <p>Each flag injected on the combined stream and operation flags will be
      * set on the stream flags.
@@ -654,7 +655,7 @@
     }
 
     /**
-     * Convert stream flags to a spliterator characteristic bit set.
+     * Converts stream flags to a spliterator characteristic bit set.
      *
      * @param streamFlags the stream flags.
      * @return the spliterator characteristic bit set.
@@ -664,7 +665,13 @@
     }
 
     /**
-     * Convert a spliterator characteristic bit set to stream flags.
+     * Converts a spliterator characteristic bit set to stream flags.
+     *
+     * @implSpec
+     * If the spliterator is naturally {@code SORTED} (the associated
+     * {@code Comparator} is {@code null}) then the characteristic is converted
+     * to the {@link #SORTED} flag, otherwise the characteristic is not
+     * converted.
      *
      * @param spliterator the spliterator from which to obtain characteristic
      *        bit set.
@@ -683,7 +690,7 @@
     }
 
     /**
-     * Convert a spliterator characteristic bit set to stream flags.
+     * Converts a spliterator characteristic bit set to stream flags.
      *
      * @param characteristics the spliterator characteristic bit set.
      * @return the stream flags.
--- a/src/share/classes/java/util/stream/TerminalOp.java	Thu Mar 07 13:13:44 2013 +0100
+++ b/src/share/classes/java/util/stream/TerminalOp.java	Thu Mar 07 13:58:43 2013 +0100
@@ -44,7 +44,7 @@
  */
 interface TerminalOp<E_IN, R> {
     /**
-     * Get the shape of the input type of this operation
+     * Gets the shape of the input type of this operation
      *
      * @implSpec The default returns {@code StreamShape.REFERENCE}
      * @return Shape of the input type of this operation
@@ -52,7 +52,7 @@
     default StreamShape inputShape() { return StreamShape.REFERENCE; }
 
     /**
-     * Get the properties of the operation.  Terminal operations may set a
+     * Gets the properties of the operation.  Terminal operations may set a
      * limited subset of the stream flags defined in {@link StreamOpFlag}, and
      * these flags are combined with the previously combined stream and
      * intermediate operation flags for the pipeline.
@@ -64,7 +64,7 @@
     default int getOpFlags() { return 0; }
 
     /**
-     * Perform a parallel evaluation of the operation using the specified
+     * Performs a parallel evaluation of the operation using the specified
      * {@code PipelineHelper}, which describes the stream source and upstream
      * intermediate operations.
      *
@@ -82,7 +82,7 @@
     }
 
     /**
-     * Perform a sequential evaluation of the operation using the specified
+     * Performs a sequential evaluation of the operation using the specified
      * {@code PipelineHelper}, which describes the stream source and upstream
      * intermediate operations.
      *
--- a/src/share/classes/java/util/stream/Tripwire.java	Thu Mar 07 13:13:44 2013 +0100
+++ b/src/share/classes/java/util/stream/Tripwire.java	Thu Mar 07 13:58:43 2013 +0100
@@ -53,7 +53,7 @@
     private Tripwire() { }
 
     /**
-     * Produce a log warning, using {@code Logger.getLogger(className)}, using
+     * Produces a log warning, using {@code Logger.getLogger(className)}, using
      * the supplied message.  The class name of {@code trippingClass} will be
      * used as the first parameter to the message.
      *