changeset 7734:61e80759e592

Doc.
author psandoz
date Mon, 25 Mar 2013 11:56:26 +0100
parents 08f05353a6d4
children 70cf1e9c9b9c de6a56e6b6b6
files src/share/classes/java/lang/Iterable.java src/share/classes/java/util/Arrays.java src/share/classes/java/util/Collection.java src/share/classes/java/util/Iterator.java src/share/classes/java/util/PrimitiveIterator.java src/share/classes/java/util/Spliterator.java src/share/classes/java/util/Spliterators.java
diffstat 7 files changed, 331 insertions(+), 319 deletions(-) [+]
line wrap: on
line diff
--- a/src/share/classes/java/lang/Iterable.java	Sun Mar 24 18:53:47 2013 +0100
+++ b/src/share/classes/java/lang/Iterable.java	Mon Mar 25 11:56:26 2013 +0100
@@ -50,14 +50,10 @@
 
     /**
      * Performs the given action on the contents of the {@code Iterable}, in the
-     * order elements are returned by an iterator, until all elements have been
+     * order elements occur when iterating, until all elements have been
      * processed or the action throws an {@code Exception}.  Exceptions thrown
      * by the action are relayed to the caller.
      *
-     * <p>The default implementation should be overridden by implementations if
-     * they can provide a more performant implementation than an iterator-based
-     * one, or to include this method within their synchronization protocol.
-     *
      * @implSpec
      * <p>The default implementation behaves as if:
      * <pre>
@@ -65,11 +61,6 @@
      *         action.accept(t);
      * </pre>
      *
-     * <p>The default implementation does not apply any synchronization
-     * protocol.  If an {@code Iterable} implementation has a specific
-     * synchronization protocol, then it must override this default
-     * implementation to apply that protocol.
-     *
      * @param action The action to be performed for each element
      * @throws NullPointerException if the specified action is null
      * @since 1.8
--- a/src/share/classes/java/util/Arrays.java	Sun Mar 24 18:53:47 2013 +0100
+++ b/src/share/classes/java/util/Arrays.java	Mon Mar 25 11:56:26 2013 +0100
@@ -4559,12 +4559,15 @@
     }
 
     /**
-     * Creates a {@link Spliterator} for the contents of the specified array.
-     *
-     * @param array The array for which to create a {@code Spliterator}
-     * @param <T> The type of the array elements
-     * @throws NullPointerException if the specified array is null
-     * @return A {@code Spliterator} for the specified array
+     * Creates a {@link Spliterator} covering all of the specified array.
+     *
+     * <p>The spliterator reports {@link Spliterator#SIZED},
+     * {@link Spliterator#SUBSIZED}, and {@link Spliterator#ORDERED}.
+     *
+     * @param array The array, assumed to be unmodified during use
+     * @param <T> Type of elements
+     * @throws NullPointerException if the specified array is {@code null}
+     * @return A spliterator from an array
      * @since 1.8
      */
     public static <T> Spliterator<T> spliterator(T[] array) {
@@ -4572,20 +4575,21 @@
     }
 
     /**
-     * Creates a {@link Spliterator} for a contiguous portion of the specified
-     * array.
-     *
-     * @param array The array for which to create a {@code Spliterator}
-     * @param fromIndex The index of the first element (inclusive) to be
-     *        included in the traversal
-     * @param toIndex The index of the last element (exclusive) to be included
-     *        in the traversal
-     * @param <T> The type of the array elements
-     * @throws NullPointerException if the specified array is null
-     * @throws ArrayIndexOutOfBoundsException if fromIndex is negative, toIndex
-     *         is less than fromIndex, or toIndex is greater than the array size
-     * @return A {@code Spliterator} for the desired portion of the specified
-     *         array
+     * Creates a {@link Spliterator} covering the specified range of the
+     * specified array.
+     *
+     * <p>The spliterator reports {@link Spliterator#SIZED},
+     * {@link Spliterator#SUBSIZED}, and {@link Spliterator#ORDERED}.
+     *
+     * @param array The array, assumed to be unmodified during use
+     * @param fromIndex The least index (inclusive) to cover
+     * @param toIndex One past the greatest index to cover
+     * @param <T> Type of elements
+     * @throws NullPointerException if the specified array is {@code null}
+     * @throws ArrayIndexOutOfBoundsException if {@code fromIndex} is negative,
+     *         {@code toIndex} is less than {@code fromIndex}, or
+     *         {@code toIndex} is greater than the array size
+     * @return A spliterator from an array
      * @since 1.8
      */
     public static <T> Spliterator<T> spliterator(T[] array, int fromIndex, int toIndex) {
@@ -4593,12 +4597,14 @@
     }
 
     /**
-     * Creates a {@link Spliterator.OfInt} for the contents of the specified
-     * {@code int} array.
-     *
-     * @param array The array for which to create a {@code Spliterator.OfInt}
-     * @throws NullPointerException if the specified array is null
-     * @return A {@code Spliterator.OfInt} for the specified array
+     * Creates a {@link Spliterator.OfInt} covering all of the specified array.
+     *
+     * <p>The spliterator reports {@link Spliterator#SIZED},
+     * {@link Spliterator#SUBSIZED}, and {@link Spliterator#ORDERED}.
+     *
+     * @param array The array, assumed to be unmodified during use
+     * @throws NullPointerException if the specified array is {@code null}
+     * @return A spliterator from an array
      * @since 1.8
      */
     public static Spliterator.OfInt spliterator(int[] array) {
@@ -4606,18 +4612,20 @@
     }
 
     /**
-     * Creates a {@link Spliterator.OfInt} for a contiguous portion of the
-     * specified {@code int} array.
-     *
-     * @param array The array for which to create a {@code Spliterator.OfInt}
-     * @param fromIndex The index of the first element (inclusive) to be
-     *        included in the traversal
-     * @param toIndex The index of the last element (exclusive) to be included
-     *        in the traversal
-     * @throws NullPointerException if the specified array is null
-     * @throws ArrayIndexOutOfBoundsException if fromIndex is negative, toIndex
-     *         is less than fromIndex, or toIndex is greater than the array size
-     * @return A {@code Spliterator.OfInt} for the specified array
+     * Creates a {@link Spliterator.OfInt} covering the specified range of the
+     * specified array.
+     *
+     * <p>The spliterator reports {@link Spliterator#SIZED},
+     * {@link Spliterator#SUBSIZED}, and {@link Spliterator#ORDERED}.
+     *
+     * @param array The array, assumed to be unmodified during use
+     * @param fromIndex The least index (inclusive) to cover
+     * @param toIndex One past the greatest index to cover
+     * @throws NullPointerException if the specified array is {@code null}
+     * @throws ArrayIndexOutOfBoundsException if {@code fromIndex} is negative,
+     *         {@code toIndex} is less than {@code fromIndex}, or
+     *         {@code toIndex} is greater than the array size
+     * @return A spliterator from an array
      * @since 1.8
      */
     public static Spliterator.OfInt spliterator(int[] array, int fromIndex, int toIndex) {
@@ -4625,12 +4633,14 @@
     }
 
     /**
-     * Creates a {@link Spliterator.OfLong} for the contents of the specified
-     * {@code long} array.
-     *
-     * @param array The array for which to create a {@code Spliterator.OfLong}
-     * @throws NullPointerException if the specified array is null
-     * @return A {@code Spliterator.OfLong} for the specified array
+     * Creates a {@link Spliterator.OfLong} covering all of the specified array.
+     *
+     * <p>The spliterator reports {@link Spliterator#SIZED},
+     * {@link Spliterator#SUBSIZED}, and {@link Spliterator#ORDERED}.
+     *
+     * @param array The array, assumed to be unmodified during use
+     * @throws NullPointerException if the specified array is {@code null}
+     * @return A spliterator from an array
      * @since 1.8
      */
     public static Spliterator.OfLong spliterator(long[] array) {
@@ -4638,18 +4648,20 @@
     }
 
     /**
-     * Creates a {@link Spliterator.OfLong} for a contiguous portion of the
-     * specified {@code long} array.
-     *
-     * @param array The array for which to create a {@code Spliterator.OfLong}
-     * @param fromIndex The index of the first element (inclusive) to be
-     *        included in the traversal
-     * @param toIndex The index of the last element (exclusive) to be included
-     *        in the traversal
-     * @throws NullPointerException if the specified array is null
-     * @throws ArrayIndexOutOfBoundsException if fromIndex is negative, toIndex
-     *         is less than fromIndex, or toIndex is greater than the array size
-     * @return A {@code Spliterator.OfLong} for the specified array
+     * Creates a {@link Spliterator.OfLong} covering the specified range of the
+     * specified array.
+     *
+     * <p>The spliterator reports {@link Spliterator#SIZED},
+     * {@link Spliterator#SUBSIZED}, and {@link Spliterator#ORDERED}.
+     *
+     * @param array The array, assumed to be unmodified during use
+     * @param fromIndex The least index (inclusive) to cover
+     * @param toIndex One past the greatest index to cover
+     * @throws NullPointerException if the specified array is {@code null}
+     * @throws ArrayIndexOutOfBoundsException if {@code fromIndex} is negative,
+     *         {@code toIndex} is less than {@code fromIndex}, or
+     *         {@code toIndex} is greater than the array size
+     * @return A spliterator from an array
      * @since 1.8
      */
     public static Spliterator.OfLong spliterator(long[] array, int fromIndex, int toIndex) {
@@ -4657,12 +4669,15 @@
     }
 
     /**
-     * Creates a {@link Spliterator.OfDouble} for the contents of the specified
-     * {@code double} array.
-     *
-     * @param array The array for which to create a {@code Spliterator.OfDouble}
-     * @throws NullPointerException if the specified array is null
-     * @return A {@code Spliterator.OfDouble} for the specified array
+     * Creates a {@link Spliterator.OfDouble} covering all of the specified
+     * array.
+     *
+     * <p>The spliterator reports {@link Spliterator#SIZED},
+     * {@link Spliterator#SUBSIZED}, and {@link Spliterator#ORDERED}.
+     *
+     * @param array The array, assumed to be unmodified during use
+     * @throws NullPointerException if the specified array is {@code null}
+     * @return A spliterator from an array
      * @since 1.8
      */
     public static Spliterator.OfDouble spliterator(double[] array) {
@@ -4670,18 +4685,20 @@
     }
 
     /**
-     * Creates a {@link Spliterator.OfDouble} for a contiguous portion of the
-     * specified {@code double} array.
-     *
-     * @param array The array for which to create a {@code Spliterator.OfDouble}
-     * @param fromIndex The index of the first element (inclusive) to be
-     *        included in the traversal
-     * @param toIndex The index of the last element (exclusive) to be included
-     *        in the traversal
-     * @throws NullPointerException if the specified array is null
-     * @throws ArrayIndexOutOfBoundsException if fromIndex is negative, toIndex
-     *         is less than fromIndex, or toIndex is greater than the array size
-     * @return A {@code Spliterator.OfDouble} for the specified array
+     * Creates a {@link Spliterator.OfDouble} covering the specified range of
+     * the specified array.
+     *
+     * <p>The spliterator reports {@link Spliterator#SIZED},
+     * {@link Spliterator#SUBSIZED}, and {@link Spliterator#ORDERED}.
+     *
+     * @param array The array, assumed to be unmodified during use
+     * @param fromIndex The least index (inclusive) to cover
+     * @param toIndex One past the greatest index to cover
+     * @throws NullPointerException if the specified array is {@code null}
+     * @throws ArrayIndexOutOfBoundsException if {@code fromIndex} is negative,
+     *         {@code toIndex} is less than {@code fromIndex}, or
+     *         {@code toIndex} is greater than the array size
+     * @return A spliterator from an array
      * @since 1.8
      */
     public static Spliterator.OfDouble spliterator(double[] array, int fromIndex, int toIndex) {
--- a/src/share/classes/java/util/Collection.java	Sun Mar 24 18:53:47 2013 +0100
+++ b/src/share/classes/java/util/Collection.java	Mon Mar 25 11:56:26 2013 +0100
@@ -108,6 +108,12 @@
  * <a href="{@docRoot}/../technotes/guides/collections/index.html">
  * Java Collections Framework</a>.
  *
+ * @implSpec
+ * The default method implementations (inherited or otherwise) do not apply any
+ * synchronization protocol.  If a {@code Collection} implementation has a
+ * specific synchronization protocol, then it must override default
+ * implementations to apply that protocol.
+ *
  * @param <E> the type of elements in this collection
  *
  * @author  Josh Bloch
--- a/src/share/classes/java/util/Iterator.java	Sun Mar 24 18:53:47 2013 +0100
+++ b/src/share/classes/java/util/Iterator.java	Mon Mar 25 11:56:26 2013 +0100
@@ -77,10 +77,6 @@
      * iteration is in progress in any way other than by calling this
      * method.
      *
-     * <p>The default implementation should be overridden by implementations if
-     * they can provide a more performant implementation than an iterator-based
-     * one, or to include this method within their synchronization protocol.
-     *
      * @implSpec
      * The default implementation throws an instance of
      * {@link UnsupportedOperationException} and performs no other action.
@@ -99,14 +95,10 @@
     }
 
     /**
-     * Performs the given action, in the order elements occur when iterating,
-     * until all remaining elements have been processed or the action throws
-     * an {@code Exception}.  Exceptions occurring as a result of performing
-     * this action are relayed to the caller.
-     *
-     * <p>The default implementation should be overridden by implementations if
-     * they can provide a more performant implementation than an iterator-based
-     * one, or to include this method within their synchronization protocol.
+     * Performs the given action for each remaining element, in the order
+     * elements occur when iterating, until all elements have been processed or
+     * the action throws an {@code Exception}.  Exceptions thrown by the action
+     * are relayed to the caller.
      *
      * @implSpec
      * <p>The default implementation behaves as if:
@@ -115,14 +107,6 @@
      *         action.accept(next());
      * </pre>
      *
-     * <p>The default implementation does not apply any synchronization
-     * protocol.  If an {@code Iterator} implementation has a specific
-     * synchronization protocol, then it must override this default
-     * implementation to apply that protocol.  The caller must ensure usage
-     * follows the correct synchronization protocol.  For example, an underlying
-     * collection may require the caller to manually synchronize on that
-     * collection when traversing it via {@code Iterator}.
-     *
      * @param action The action to be performed for each element
      * @throws NullPointerException if the specified action is null
      * @since 1.8
--- a/src/share/classes/java/util/PrimitiveIterator.java	Sun Mar 24 18:53:47 2013 +0100
+++ b/src/share/classes/java/util/PrimitiveIterator.java	Mon Mar 25 11:56:26 2013 +0100
@@ -30,10 +30,25 @@
 import java.util.function.LongConsumer;
 
 /**
- * A base type for primitive specializations of {@code Iterator}.  Subtypes
- * specialize for {@link OfInt int}, {@link OfLong long}, and
+ * A base type for primitive specializations of {@code Iterator}.  Specialized
+ * subtypes are provided for {@link OfInt int}, {@link OfLong long}, and
  * {@link OfDouble double} values.
  *
+ * <p>The specialized subtype default implementations of {@link Iterator#next}
+ * and {@link Iterator#forEach(java.util.function.Consumer)} box primitive
+ * values to instances of their corresponding wrapper class.  Such boxing may
+ * offset any advantages gained when using the primitive specializations.  To
+ * avoid boxing the corresponding primitive-based methods should be used.  For
+ * example, {@link PrimitiveIterator.OfInt#nextInt()} and
+ * {@link PrimitiveIterator.OfInt#forEachInt(java.util.function.IntConsumer)}
+ * should be used in preference to {@link PrimitiveIterator.OfInt#next()} and
+ * {@link PrimitiveIterator.OfInt#forEach(java.util.function.Consumer)}.
+ *
+ * @implNote
+ * If boxing occurs when operating on instances of primitive subtype
+ * specializations a warning may be output if the boolean system property
+ * {@code org.openjdk.java.util.stream.tripwire} is set to {@code true}.
+ *
  * @param <T> the boxed type of a primitive
  * @since 1.8
  */
@@ -53,15 +68,10 @@
         int nextInt();
 
         /**
-         * Performs the given action, in the order elements occur when
-         * iterating, until all remaining elements have been processed or the
-         * action throws an {@code Exception}.  Exceptions occurring as a result
-         * of performing this action are relayed to the caller.
-         *
-         * <p>The default implementation should be overridden by implementations
-         * if they can provide a more performant implementation than an
-         * iterator-based one, or to include this method within their
-         * synchronization protocol.
+         * Performs the given action for each remaining element, in the order
+         * elements occur when iterating, until all elements have been processed
+         * or the action throws an {@code Exception}.  Exceptions thrown by the
+         * action are relayed to the caller.
          *
          * @implSpec
          * <p>The default implementation behaves as if:
@@ -70,11 +80,6 @@
          *         action.accept(nextInt());
          * </pre>
          *
-         * <p>The default implementation does not apply any synchronization
-         * protocol.  If a {@code PrimitiveIterator.OfInt} implementation has a
-         * specific synchronization protocol, then it must override this default
-         * implementation to apply that protocol.
-         *
          * @param action The action to be performed for each element
          * @throws NullPointerException if the specified action is null
          * @since 1.8
@@ -87,8 +92,8 @@
         /**
          * {@inheritDoc}
          * @implSpec
-         * The default implementation defers to {@link #nextInt()}, and a
-         * warning may be output that boxing of an {@code int} value will occur.
+         * The default implementation boxes the result of calling
+         * {@link #nextInt()}, and returns that boxed result.
          */
         @Override
         default Integer next() {
@@ -100,12 +105,11 @@
         /**
          * {@inheritDoc}
          * @implSpec
-         * The default implementation defers to
-         * {@link #forEachInt(java.util.function.IntConsumer)}.  If the
-         * action is an instance of {@code IntConsumer} then it defers as
-         * if: {@code forEachInt((IntConsumer) action)}.  Otherwise, it
-         * defers as if: {@code forEachInt(action::accept)}, and a warning may
-         * be output that boxing of {@code int} values will occur.
+         * If the action is an instance of {@code IntConsumer} then it is cast
+         * to {@code IntConsumer} and passed to {@link #forEachInt}; otherwise
+         * the action is adapted to an instance of {@code IntConsumer}, by
+         * boxing the argument of {@code IntConsumer}, and then passed to
+         * {@link #forEachInt}.
          */
         @Override
         default void forEach(Consumer<? super Integer> action) {
@@ -135,15 +139,10 @@
         long nextLong();
 
         /**
-         * Performs the given action, in the order elements occur when
-         * iterating, until all remaining elements have been processed or the
-         * action throws an {@code Exception}.  Exceptions occurring as a result
-         * of performing this action are relayed to the caller.
-         *
-         * <p>The default implementation should be overridden by implementations
-         * if they can provide a more performant implementation than an
-         * iterator-based one, or to include this method within their
-         * synchronization protocol.
+         * Performs the given action for each remaining element, in the order
+         * elements occur when iterating, until all elements have been processed
+         * or the action throws an {@code Exception}.  Exceptions thrown by the
+         * action are relayed to the caller.
          *
          * @implSpec
          * <p>The default implementation behaves as if:
@@ -152,11 +151,6 @@
          *         action.accept(nextLong());
          * </pre>
          *
-         * <p>The default implementation does not apply any synchronization
-         * protocol.  If a {@code PrimitiveIterator.OfLong} implementation has
-         * a specific synchronization protocol, then it must override this
-         * default implementation to apply that protocol.
-         *
          * @param action The action to be performed for each element
          * @throws NullPointerException if the specified action is null
          * @since 1.8
@@ -169,8 +163,8 @@
         /**
          * {@inheritDoc}
          * @implSpec
-         * The default implementation defers to {@link #nextLong()}, and a
-         * warning may be output that boxing of an {@code int} value will occur.
+         * The default implementation boxes the result of calling
+         * {@link #nextLong()}, and returns that boxed result.
          */
         @Override
         default Long next() {
@@ -182,12 +176,11 @@
         /**
          * {@inheritDoc}
          * @implSpec
-         * The default implementation defers to
-         * {@link #forEachLong(java.util.function.LongConsumer)}.  If the
-         * action is an instance of {@code LongConsumer} then it defers as
-         * if: {@code forEachLong((LongConsumer) action)}.  Otherwise, it
-         * defers as if: {@code forEachLong(action::accept)}, and a warning may
-         * be output that boxing of {@code long} values will occur.
+         * If the action is an instance of {@code LongConsumer} then it is cast
+         * to {@code LongConsumer} and passed to {@link #forEachLong}; otherwise
+         * the action is adapted to an instance of {@code LongConsumer}, by
+         * boxing the argument of {@code LongConsumer}, and then passed to
+         * {@link #forEachLong}.
          */
         @Override
         default void forEach(Consumer<? super Long> action) {
@@ -216,15 +209,10 @@
         double nextDouble();
 
         /**
-         * Performs the given action, in the order elements occur when
-         * iterating, until all remaining elements have been processed or the
-         * action throws an {@code Exception}.  Exceptions occurring as a result
-         * of performing this action are relayed to the caller.
-         *
-         * <p>The default implementation should be overridden by implementations
-         * if they can provide a more performant implementation than an
-         * iterator-based one, or to include this method within their
-         * synchronization protocol.
+         * Performs the given action for each remaining element, in the order
+         * elements occur when iterating, until all elements have been processed
+         * or the action throws an {@code Exception}.  Exceptions thrown by the
+         * action are relayed to the caller.
          *
          * @implSpec
          * <p>The default implementation behaves as if:
@@ -233,11 +221,6 @@
          *         action.accept(nextDouble());
          * </pre>
          *
-         * <p>The default implementation does not apply any synchronization
-         * protocol.  If a {@code PrimitiveIterator.OfDouble} implementation has
-         * a specific synchronization protocol, then it must override this
-         * default implementation to apply that protocol.
-         *
          * @param action The action to be performed for each element
          * @throws NullPointerException if the specified action is null
          * @since 1.8
@@ -250,8 +233,8 @@
         /**
          * {@inheritDoc}
          * @implSpec
-         * The default implementation defers to {@link #nextDouble()}, and a
-         * warning may be output that boxing of an {@code int} value will occur.
+         * The default implementation boxes the result of calling
+         * {@link #nextDouble()}, and returns that boxed result.
          */
         @Override
         default Double next() {
@@ -263,12 +246,11 @@
         /**
          * {@inheritDoc}
          * @implSpec
-         * The default implementation defers to
-         * {@link #forEachDouble(java.util.function.DoubleConsumer)}.  If the
-         * action is an instance of {@code DoubleConsumer} then it defers as
-         * if: {@code forEachDouble((DoubleConsumer) action)}.  Otherwise,
-         * it defers as if: {@code forEachDouble(action::accept)}, and a warning
-         * may be output that boxing of {@code double} values will occur.
+         * If the action is an instance of {@code DoubleConsumer} then it is
+         * cast to {@code DoubleConsumer} and passed to {@link #forEachDouble};
+         * otherwise the action is adapted to an instance of
+         * {@code DoubleConsumer}, by boxing the argument of
+         * {@code DoubleConsumer}, and then passed to {@link #forEachDouble}.
          */
         @Override
         default void forEach(Consumer<? super Double> action) {
--- a/src/share/classes/java/util/Spliterator.java	Sun Mar 24 18:53:47 2013 +0100
+++ b/src/share/classes/java/util/Spliterator.java	Mon Mar 25 11:56:26 2013 +0100
@@ -30,12 +30,13 @@
 import java.util.function.LongConsumer;
 
 /**
- * A provider of element traversal operations for a possibly-parallel
- * computation.  These operations proceed either individually ({@link
- * #tryAdvance}) or in bulk ({@link #forEach}).  The source of
- * elements covered by a Spliterator may for example be an array, a
+ * An object for traversing and partitioning elements of a source. The source
+ * of elements covered by a Spliterator may for example be an array, a
  * {@link Collection}, an IO channel, or a generator function.
  *
+ * <p>A Spliterator may traverse elements individually ({@link
+ * #tryAdvance}) or sequentially in bulk ({@link #forEach}).
+ *
  * <p>A Spliterator may partition off some of its elements (using
  * {@link #trySplit}) as another Spliterator, to be used in
  * possibly-parallel operations.  Operations using a Spliterator that
@@ -92,6 +93,20 @@
  * exhaust elements, each Spliterator is useful for only a single bulk
  * computation.
  *
+ * <p>Primitive subtype specializations of {@code Spliterator} are provided for
+ * {@link OfInt int}, {@link OfLong long}, and {@link OfDouble double} values.
+ * The subtype default implementations of
+ * {@link Spliterator#tryAdvance(java.util.function.Consumer)}
+ * and {@link Spliterator#forEach(java.util.function.Consumer)} box primitive
+ * values to instances of their corresponding wrapper class.  Such boxing may
+ * offset any advantages gained when using the primitive specializations.  To
+ * avoid boxing the corresponding primitive-based methods should be used.  For
+ * example, {@link Spliterator.OfInt#tryAdvance(java.util.function.IntConsumer)}
+ * and {@link Spliterator.OfInt#forEach(java.util.function.IntConsumer)}
+ * should be used in preference to
+ * {@link Spliterator.OfInt#tryAdvance(java.util.function.Consumer)} and
+ * {@link Spliterator.OfInt#forEach(java.util.function.Consumer)}.
+ *
  * @apiNote
  * <p><b>Example.</b> Here is a class (not a very useful one except
  * for illustration) that maintains an array in which the actual data
@@ -224,6 +239,11 @@
  * {@code ConcurrentModificationException}.</li>
  * </ul>
  *
+ * @implNote
+ * If boxing occurs when operating on instances of primitive subtype
+ * specializations a warning may be output if the boolean system property
+ * {@code org.openjdk.java.util.stream.tripwire} is set to {@code true}.
+ *
  * @see Collection
  * @since 1.8
  */
@@ -516,13 +536,12 @@
         /**
          * {@inheritDoc}
          * @implSpec
-         * The default implementation defers to
-         * {@link #tryAdvance(java.util.function.IntConsumer)}.  If the
-         * action is an instance of {@code IntConsumer} then it defers as
-         * follows: {@code return tryAdvance((IntConsumer) action)}.
-         * Otherwise, it defers as follows:
-         * {@code tryAdvance((IntConsumer) action::accept)}, and a warning may
-         * be output that boxing of an {@code int} value will occur.
+         * If the action is an instance of {@code IntConsumer} then it is cast
+         * to {@code IntConsumer} and passed to
+         * {@link #tryAdvance(java.util.function.IntConsumer)}; otherwise
+         * the action is adapted to an instance of {@code IntConsumer}, by
+         * boxing the argument of {@code IntConsumer}, and then passed to
+         * {@link ##tryAdvance(java.util.function.IntConsumer)}.
          */
         @Override
         default boolean tryAdvance(Consumer<? super Integer> action) {
@@ -539,12 +558,12 @@
         /**
          * {@inheritDoc}
          * @implSpec
-         * The default implementation defers to
-         * {@link #forEach(java.util.function.IntConsumer)}.  If the
-         * action is an instance of {@code IntConsumer} then it defers as
-         * follows: {@code forEach((IntConsumer) action)}.  Otherwise, it defers
-         * as follows: {@code forEach((IntConsumer) action::accept)}, and a
-         * warning may be output that boxing of {@code int} values will occur.
+         * If the action is an instance of {@code IntConsumer} then it is cast
+         * to {@code IntConsumer} and passed to
+         * {@link #forEach(java.util.function.IntConsumer)}; otherwise
+         * the action is adapted to an instance of {@code IntConsumer}, by
+         * boxing the argument of {@code IntConsumer}, and then passed to
+         * {@link ##forEach(java.util.function.IntConsumer)}.
          */
         @Override
         default void forEach(Consumer<? super Integer> action) {
@@ -602,13 +621,12 @@
         /**
          * {@inheritDoc}
          * @implSpec
-         * The default implementation defers to
-         * {@link #tryAdvance(java.util.function.LongConsumer)}.  If the
-         * action is an instance of {@code LongConsumer} then it defers as
-         * follows: {@code return tryAdvance((LongConsumer) action)}. Otherwise,
-         * it defers as follows:
-         * {@code tryAdvance((LongConsumer) action::accept)}, and a warning may
-         * be output that boxing of a {@code long} value will occur.
+         * If the action is an instance of {@code LongConsumer} then it is cast
+         * to {@code LongConsumer} and passed to
+         * {@link #tryAdvance(java.util.function.LongConsumer)}; otherwise
+         * the action is adapted to an instance of {@code LongConsumer}, by
+         * boxing the argument of {@code LongConsumer}, and then passed to
+         * {@link ##tryAdvance(java.util.function.LongConsumer)}.
          */
         @Override
         default boolean tryAdvance(Consumer<? super Long> action) {
@@ -625,13 +643,12 @@
         /**
          * {@inheritDoc}
          * @implSpec
-         * The default implementation defers to
-         * {@link #forEach(java.util.function.LongConsumer)}.  If the
-         * action is an instance of {@code LongConsumer} then it defers as
-         * follows: {@code forEach((LongConsumer) action)}.  Otherwise, it
-         * defers as follows: {@code forEach((LongConsumer) action::accept)},
-         * and a warning may be output that boxing of {@code long} values will
-         * occur.
+         * If the action is an instance of {@code LongConsumer} then it is cast
+         * to {@code LongConsumer} and passed to
+         * {@link #forEach(java.util.function.LongConsumer)}; otherwise
+         * the action is adapted to an instance of {@code LongConsumer}, by
+         * boxing the argument of {@code LongConsumer}, and then passed to
+         * {@link ##forEach(java.util.function.LongConsumer)}.
          */
         @Override
         default void forEach(Consumer<? super Long> action) {
@@ -689,13 +706,12 @@
         /**
          * {@inheritDoc}
          * @implSpec
-         * The default implementation defers to
-         * {@link #tryAdvance(java.util.function.DoubleConsumer)}.  If the
-         * action is an instance of {@code DoubleConsumer} then it defers as
-         * follows: {@code return tryAdvance((DoubleConsumer) action)}.
-         * Otherwise, it defers as follows:
-         * {@code tryAdvance((DoubleConsumer) action::accept)}, and a warning
-         * may be output that boxing of a {@code double} value will occur.
+         * If the action is an instance of {@code DoubleConsumer} then it is
+         * cast to {@code DoubleConsumer} and passed to
+         * {@link #tryAdvance(java.util.function.DoubleConsumer)}; otherwise
+         * the action is adapted to an instance of {@code DoubleConsumer}, by
+         * boxing the argument of {@code DoubleConsumer}, and then passed to
+         * {@link ##tryAdvance(java.util.function.DoubleConsumer)}.
          */
         @Override
         default boolean tryAdvance(Consumer<? super Double> action) {
@@ -712,13 +728,12 @@
         /**
          * {@inheritDoc}
          * @implSpec
-         * The default implementation defers to
-         * {@link #forEach(java.util.function.DoubleConsumer)}.  If the
-         * action is an instance of {@code DoubleConsumer} then it defers as
-         * follows: {@code forEach((DoubleConsumer) action)}.  Otherwise, it
-         * defers as follows: {@code forEach((DoubleConsumer) action::accept)},
-         * and a warning may be output that boxing of {@code double} values will
-         * occur.
+         * If the action is an instance of {@code DoubleConsumer} then it is
+         * cast to {@code DoubleConsumer} and passed to
+         * {@link #forEach(java.util.function.DoubleConsumer)}; otherwise
+         * the action is adapted to an instance of {@code DoubleConsumer}, by
+         * boxing the argument of {@code DoubleConsumer}, and then passed to
+         * {@link ##forEach(java.util.function.DoubleConsumer)}.
          */
         @Override
         default void forEach(Consumer<? super Double> action) {
--- a/src/share/classes/java/util/Spliterators.java	Sun Mar 24 18:53:47 2013 +0100
+++ b/src/share/classes/java/util/Spliterators.java	Mon Mar 25 11:56:26 2013 +0100
@@ -93,6 +93,7 @@
      * @param <T> Type of elements
      * @throws NullPointerException if the given array is {@code null}
      * @return A spliterator from an array
+     * @see Arrays#spliterator(Object[])
      */
     public static <T> Spliterator<T> spliterator(Object[] array,
                                                  int additionalCharacteristics) {
@@ -104,22 +105,23 @@
      * array.
      *
      * @param array The array, assumed to be unmodified during use
-     * @param origin The least index (inclusive) to cover
-     * @param fence One past the greatest index to cover
+     * @param fromIndex The least index (inclusive) to cover
+     * @param toIndex One past the greatest index to cover
      * @param additionalCharacteristics Properties of this spliterator's source
      *        or elements ({@code SIZED} and {@code SUBSIZED} are always
      *        reported, so need not be supplied.)
      * @param <T> Type of elements
      * @throws NullPointerException if the given array is {@code null}
-     * @throws ArrayIndexOutOfBoundsException if {@code origin} is negative,
-     *         {@code fence} is less than {@code origin}, or {@code fence} is
+     * @throws ArrayIndexOutOfBoundsException if {@code fromIndex} is negative,
+     *         {@code toIndex} is less than {@code fromIndex}, or {@code toIndex} is
      *         greater than the array size
      * @return A spliterator from an array
+     * @see Arrays#spliterator(Object[], int, int)
      */
-    public static <T> Spliterator<T> spliterator(Object[] array, int origin, int fence,
+    public static <T> Spliterator<T> spliterator(Object[] array, int fromIndex, int toIndex,
                                                  int additionalCharacteristics) {
-        checkFromToBounds(Objects.requireNonNull(array).length, origin, fence);
-        return new ArraySpliterator<>(array, origin, fence, additionalCharacteristics);
+        checkFromToBounds(Objects.requireNonNull(array).length, fromIndex, toIndex);
+        return new ArraySpliterator<>(array, fromIndex, toIndex, additionalCharacteristics);
     }
 
     /**
@@ -131,6 +133,7 @@
      *        reported, so need not be supplied.)
      * @throws NullPointerException if the given array is {@code null}
      * @return A spliterator from an array
+     * @see Arrays#spliterator(int[])
      */
     public static Spliterator.OfInt spliterator(int[] array,
                                                 int additionalCharacteristics) {
@@ -142,21 +145,22 @@
      * given array.
      *
      * @param array The array, assumed to be unmodified during use
-     * @param origin The least index (inclusive) to cover
-     * @param fence One past the greatest index to cover
+     * @param fromIndex The least index (inclusive) to cover
+     * @param toIndex One past the greatest index to cover
      * @param additionalCharacteristics Properties of this spliterator's source
      *        or elements ({@code SIZED} and {@code SUBSIZED} are always
      *        reported, so need not be supplied.)
      * @throws NullPointerException if the given array is {@code null}
-     * @throws ArrayIndexOutOfBoundsException if {@code origin} is negative,
-     *         {@code fence} is less than {@code origin}, or {@code fence} is
-     *         greater than the array size
+     * @throws ArrayIndexOutOfBoundsException if {@code fromIndex} is negative,
+     *         {@code toIndex} is less than {@code fromIndex}, or
+     *         {@code toIndex} is greater than the array size
      * @return A spliterator from an array
+     * @see Arrays#spliterator(int[], int, int)
      */
-    public static Spliterator.OfInt spliterator(int[] array, int origin, int fence,
+    public static Spliterator.OfInt spliterator(int[] array, int fromIndex, int toIndex,
                                                 int additionalCharacteristics) {
-        checkFromToBounds(Objects.requireNonNull(array).length, origin, fence);
-        return new IntArraySpliterator(array, origin, fence, additionalCharacteristics);
+        checkFromToBounds(Objects.requireNonNull(array).length, fromIndex, toIndex);
+        return new IntArraySpliterator(array, fromIndex, toIndex, additionalCharacteristics);
     }
 
     /**
@@ -168,6 +172,7 @@
      *        reported, so need not be supplied.)
      * @throws NullPointerException if the given array is {@code null}
      * @return A spliterator from an array
+     * @see Arrays#spliterator(long[])
      */
     public static Spliterator.OfLong spliterator(long[] array,
                                                  int additionalCharacteristics) {
@@ -179,21 +184,22 @@
      * given array.
      *
      * @param array The array, assumed to be unmodified during use
-     * @param origin The least index (inclusive) to cover
-     * @param fence One past the greatest index to cover
+     * @param fromIndex The least index (inclusive) to cover
+     * @param toIndex One past the greatest index to cover
      * @param additionalCharacteristics Properties of this spliterator's source
      *        or elements ({@code SIZED} and {@code SUBSIZED} are always
      *        reported, so need not be supplied.)
      * @throws NullPointerException if the given array is {@code null}
-     * @throws ArrayIndexOutOfBoundsException if {@code origin} is negative,
-     *         {@code fence} is less than {@code origin}, or {@code fence} is
-     *         greater than the array size
+     * @throws ArrayIndexOutOfBoundsException if {@code fromIndex} is negative,
+     *         {@code toIndex} is less than {@code fromIndex}, or
+     *         {@code toIndex} is greater than the array size
      * @return A spliterator from an array
+     * @see Arrays#spliterator(long[], int, int)
      */
-    public static Spliterator.OfLong spliterator(long[] array, int origin, int fence,
+    public static Spliterator.OfLong spliterator(long[] array, int fromIndex, int toIndex,
                                                  int additionalCharacteristics) {
-        checkFromToBounds(Objects.requireNonNull(array).length, origin, fence);
-        return new LongArraySpliterator(array, origin, fence, additionalCharacteristics);
+        checkFromToBounds(Objects.requireNonNull(array).length, fromIndex, toIndex);
+        return new LongArraySpliterator(array, fromIndex, toIndex, additionalCharacteristics);
     }
 
     /**
@@ -206,6 +212,7 @@
      *        reported, so need not be supplied.)
      * @throws NullPointerException if the given array is {@code null}
      * @return A spliterator from an array
+     * @see Arrays#spliterator(double[])
      */
     public static Spliterator.OfDouble spliterator(double[] array,
                                                    int additionalCharacteristics) {
@@ -217,21 +224,22 @@
      * the given array.
      *
      * @param array The array, assumed to be unmodified during use
-     * @param origin The least index (inclusive) to cover
-     * @param fence One past the greatest index to cover
+     * @param fromIndex The least index (inclusive) to cover
+     * @param toIndex One past the greatest index to cover
      * @param additionalCharacteristics Properties of this spliterator's source
      *        or elements ({@code SIZED} and {@code SUBSIZED} are always
      *        reported, so need not be supplied.)
      * @throws NullPointerException if the given array is {@code null}
-     * @throws ArrayIndexOutOfBoundsException if {@code origin} is negative,
-     *         {@code fence} is less than {@code origin}, or {@code fence} is
-     *         greater than the array size
+     * @throws ArrayIndexOutOfBoundsException if {@code fromIndex} is negative,
+     *         {@code toIndex} is less than {@code fromIndex}, or
+     *         {@code toIndex} is greater than the array size
      * @return A spliterator from an array
+     * @see Arrays#spliterator(double[], int, int)
      */
-    public static Spliterator.OfDouble spliterator(double[] array, int origin, int fence,
+    public static Spliterator.OfDouble spliterator(double[] array, int fromIndex, int toIndex,
                                                    int additionalCharacteristics) {
-        checkFromToBounds(Objects.requireNonNull(array).length, origin, fence);
-        return new DoubleArraySpliterator(array, origin, fence, additionalCharacteristics);
+        checkFromToBounds(Objects.requireNonNull(array).length, fromIndex, toIndex);
+        return new DoubleArraySpliterator(array, fromIndex, toIndex, additionalCharacteristics);
     }
 
     private static void checkFromToBounds(int arrayLength, int origin, int fence) {
@@ -250,12 +258,9 @@
     // Iterator-based spliterators
 
     /**
-     * Creates a basic {@code Spliterator} using the given collection's
-     * {@link java.util.Collection#iterator()} for traversal, and reporting its
-     * {@link java.util.Collection#size()} as its initial size.
-     *
-     * <p>Traversal of the iterator must be accomplished through the returned
-     * spliterator.
+     * Creates a {@code Spliterator} using the given collection's
+     * {@link java.util.Collection#iterator()} as the source of elements, and
+     * reporting its {@link java.util.Collection#size()} as its initial size.
      *
      * <p>The spliterator is
      * <em><a href="Spliterator.html#binding">late-binding</a></em>, inherits
@@ -268,7 +273,7 @@
      *        reported, so need not be supplied.)
      * @param <T> Type of elements
      * @throws NullPointerException if the given collection is {@code null}
-     * @return A basic spliterator from an iterator
+     * @return A spliterator from an iterator
      */
     public static <T> Spliterator<T> spliterator(Collection<T> c,
                                                  int additionalCharacteristics) {
@@ -276,12 +281,13 @@
     }
 
     /**
-     * Creates a basic {@code Spliterator} using a given {@code Iterator}
-     * for element operations, and with a given initially reported size.  The
-     * spliterator implements {@code trySplit} to permit limited parallelism.
+     * Creates a {@code Spliterator} using a given {@code Iterator}
+     * as the source of elements, and with a given initially reported size.
      *
-     * <p>Traversal of the iterator must be accomplished through the returned
-     * spliterator.
+     * <p>The spliterator implements {@code trySplit} to permit limited
+     * parallelism.  Traversal of elements should be accomplished through the
+     * spliterator.  The behaviour of traversal is undefined if the iterator is
+     * operated on during traversal.
      *
      * @param iterator The iterator for the source
      * @param size The number of elements in the source, to be reported as
@@ -291,7 +297,7 @@
      *        reported, so need not be supplied.)
      * @param <T> Type of elements
      * @throws NullPointerException if the given iterator is {@code null}
-     * @return A basic spliterator from an iterator
+     * @return A spliterator from an iterator
      */
     public static <T> Spliterator<T> spliterator(Iterator<T> iterator, long size,
                                                  int additionalCharacteristics) {
@@ -299,12 +305,13 @@
     }
 
     /**
-     * Creates a basic {@code Spliterator} using a given {@code Iterator}
-     * for element operations, with no initial size estimate.  The spliterator
-     * implements {@code trySplit} to permit limited parallelism.
+     * Creates a {@code Spliterator} using a given {@code Iterator}
+     * as the source of elements, with no initial size estimate.
      *
-     * <p>Traversal of the iterator must be accomplished through the returned
-     * spliterator.
+     * <p>The spliterator implements {@code trySplit} to permit limited
+     * parallelism.  Traversal of elements should be accomplished through the
+     * spliterator.  The behaviour of traversal is undefined if the iterator is
+     * operated on during traversal.
      *
      * @param iterator The iterator for the source
      * @param additionalCharacteristics Properties of this spliterator's source
@@ -312,7 +319,7 @@
      *        reported, so need not be supplied.)
      * @param <T> Type of elements
      * @throws NullPointerException if the given iterator is {@code null}
-     * @return A basic spliterator from an iterator
+     * @return A spliterator from an iterator
      */
     public static <T> Spliterator<T> spliteratorUnknownSize(Iterator<T> iterator,
                                                             int additionalCharacteristics) {
@@ -320,13 +327,14 @@
     }
 
     /**
-     * Creates a basic {@code Spliterator.OfInt} using a given
-     * {@code IntStream.IntIterator} for element operations, and with a given
-     * initially reported size.  The spliterator implements {@code trySplit} to
-     * permit limited parallelism.
+     * Creates a {@code Spliterator.OfInt} using a given
+     * {@code IntStream.IntIterator} as the source of elements, and with a given
+     * initially reported size.
      *
-     * <p>Traversal of the iterator must be accomplished through the returned
-     * spliterator.
+     * <p>The spliterator implements {@code trySplit} to permit limited
+     * parallelism.  Traversal of elements should be accomplished through the
+     * spliterator.  The behaviour of traversal is undefined if the iterator is
+     * operated on during traversal.
      *
      * @param iterator The iterator for the source
      * @param size The number of elements in the source, to be reported as
@@ -335,7 +343,7 @@
      *        or elements ({@code SIZED} and {@code SUBSIZED} are always
      *        reported, so need not be supplied.)
      * @throws NullPointerException if the given iterator is {@code null}
-     * @return A basic spliterator from an iterator
+     * @return A spliterator from an iterator
      */
     public static Spliterator.OfInt spliterator(PrimitiveIterator.OfInt iterator, long size,
                                                 int additionalCharacteristics) {
@@ -343,20 +351,21 @@
     }
 
     /**
-     * Creates a basic {@code Spliterator.OfInt} using a given
-     * {@code IntStream.IntIterator} for element operations, with no initial
-     * size estimate.  The spliterator implements {@code trySplit} to permit
-     * limited parallelism.
+     * Creates a {@code Spliterator.OfInt} using a given
+     * {@code IntStream.IntIterator} as the source of elements, with no initial
+     * size estimate.
      *
-     * <p>Traversal of the iterator must be accomplished through the returned
-     * spliterator.
+     * <p>The spliterator implements {@code trySplit} to permit limited
+     * parallelism.  Traversal of elements should be accomplished through the
+     * spliterator.  The behaviour of traversal is undefined if the iterator is
+     * operated on during traversal.
      *
      * @param iterator The iterator for the source
      * @param additionalCharacteristics Properties of this spliterator's source
      *        or elements ({@code SIZED} and {@code SUBSIZED} are always
      *        reported, so need not be supplied.)
      * @throws NullPointerException if the given iterator is {@code null}
-     * @return A basic spliterator from an iterator
+     * @return A spliterator from an iterator
      */
     public static Spliterator.OfInt spliteratorUnknownSize(PrimitiveIterator.OfInt iterator,
                                                            int additionalCharacteristics) {
@@ -364,13 +373,14 @@
     }
 
     /**
-     * Creates a basic {@code Spliterator.OfLong} using a given
-     * {@code LongStream.LongIterator} for element operations, and with a given
-     * initially reported size.  The spliterator implements {@code trySplit} to
-     * permit limited parallelism.
+     * Creates a {@code Spliterator.OfLong} using a given
+     * {@code LongStream.LongIterator} as the source of elements, and with a
+     * given initially reported size.
      *
-     * <p>Traversal of the iterator must be accomplished through the returned
-     * spliterator.
+     * <p>The spliterator implements {@code trySplit} to permit limited
+     * parallelism.  Traversal of elements should be accomplished through the
+     * spliterator.  The behaviour of traversal is undefined if the iterator is
+     * operated on during traversal.
      *
      * @param iterator The iterator for the source
      * @param size The number of elements in the source, to be reported as
@@ -379,7 +389,7 @@
      *        or elements ({@code SIZED} and {@code SUBSIZED} are always
      *        reported, so need not be supplied.)
      * @throws NullPointerException if the given iterator is {@code null}
-     * @return A basic spliterator from an iterator
+     * @return A spliterator from an iterator
      */
     public static Spliterator.OfLong spliterator(PrimitiveIterator.OfLong iterator, long size,
                                                  int additionalCharacteristics) {
@@ -387,20 +397,21 @@
     }
 
     /**
-     * Creates a basic {@code Spliterator.OfLong} using a given
-     * {@code LongStream.LongIterator} for element operations, with no initial
-     * size estimate.  The spliterator implements {@code trySplit} to permit
-     * limited parallelism.
+     * Creates a {@code Spliterator.OfLong} using a given
+     * {@code LongStream.LongIterator} as the source of elements, with no
+     * initial size estimate.
      *
-     * <p>Traversal of the iterator must be accomplished through the returned
-     * spliterator.
+     * <p>The spliterator implements {@code trySplit} to permit limited
+     * parallelism.  Traversal of elements should be accomplished through the
+     * spliterator.  The behaviour of traversal is undefined if the iterator is
+     * operated on during traversal.
      *
      * @param iterator The iterator for the source
      * @param additionalCharacteristics Properties of this spliterator's source
      *        or elements ({@code SIZED} and {@code SUBSIZED} are always
      *        reported, so need not be supplied.)
      * @throws NullPointerException if the given iterator is {@code null}
-     * @return A basic spliterator from an iterator
+     * @return A spliterator from an iterator
      */
     public static Spliterator.OfLong spliteratorUnknownSize(PrimitiveIterator.OfLong iterator,
                                                             int additionalCharacteristics) {
@@ -408,13 +419,14 @@
     }
 
     /**
-     * Creates a basic {@code Spliterator.OfDouble} using a given
-     * {@code DoubleStream.DoubleIterator} for element operations, and with a
-     * given initially reported size.  The spliterator implements
-     * {@code trySplit} to permit limited parallelism.
+     * Creates a {@code Spliterator.OfDouble} using a given
+     * {@code DoubleStream.DoubleIterator} as the source of elements, and with a
+     * given initially reported size.
      *
-     * <p>Traversal of the iterator must be accomplished through the returned
-     * spliterator.
+     * <p>The spliterator implements {@code trySplit} to permit limited
+     * parallelism.  Traversal of elements should be accomplished through the
+     * spliterator.  The behaviour of traversal is undefined if the iterator is
+     * operated on during traversal.
      *
      * @param iterator The iterator for the source
      * @param size The number of elements in the source, to be reported as
@@ -423,7 +435,7 @@
      *        or elements ({@code SIZED} and {@code SUBSIZED} are always
      *        reported, so need not be supplied.)
      * @throws NullPointerException if the given iterator is {@code null}
-     * @return A basic spliterator from an iterator
+     * @return A spliterator from an iterator
      */
     public static Spliterator.OfDouble spliterator(PrimitiveIterator.OfDouble iterator, long size,
                                                    int additionalCharacteristics) {
@@ -431,20 +443,21 @@
     }
 
     /**
-     * Creates a basic {@code Spliterator.OfDouble} using a given
-     * {@code DoubleStream.DoubleIterator} for element operations, with no
-     * initial size estimate.  The spliterator implements {@code trySplit} to
-     * permit limited parallelism.
+     * Creates a {@code Spliterator.OfDouble} using a given
+     * {@code DoubleStream.DoubleIterator} as the source of elements, with no
+     * initial size estimate.
      *
-     * <p>Traversal of the iterator must be accomplished through the returned
-     * spliterator.
+     * <p>The spliterator implements {@code trySplit} to permit limited
+     * parallelism.  Traversal of elements should be accomplished through the
+     * spliterator.  The behaviour of traversal is undefined if the iterator is
+     * operated on during traversal.
      *
      * @param iterator The iterator for the source
      * @param additionalCharacteristics Properties of this spliterator's source
      *        or elements ({@code SIZED} and {@code SUBSIZED} are always
      *        reported, so need not be supplied.)
      * @throws NullPointerException if the given iterator is {@code null}
-     * @return A basic spliterator from an iterator
+     * @return A spliterator from an iterator
      */
     public static Spliterator.OfDouble spliteratorUnknownSize(PrimitiveIterator.OfDouble iterator,
                                                               int additionalCharacteristics) {
@@ -456,8 +469,9 @@
     /**
      * Creates an {@code Iterator} from a {@code Spliterator}.
      *
-     * <p>Traversal of the spliterator must be accomplished through the returned
-     * iterator.  During traversal the spliterator must not be operated on.
+     * <p>Traversal of elements should be accomplished through the iterator.
+     * The behaviour of traversal is undefined if the spliterator is operated
+     * on during traversal.
      *
      * @param spliterator The spliterator
      * @param <T> Type of elements
@@ -501,8 +515,9 @@
      * Creates an {@code PrimitiveIterator.OfInt} from a
      * {@code Spliterator.OfInt}.
      *
-     * <p>Traversal of the spliterator must be accomplished through the returned
-     * iterator.  During traversal the spliterator must not be operated on.
+     * <p>Traversal of elements should be accomplished through the iterator.
+     * The behaviour of traversal is undefined if the spliterator is operated
+     * on during traversal.
      *
      * @param spliterator The spliterator
      * @throws NullPointerException if the given spliterator is {@code null}
@@ -545,8 +560,9 @@
      * Creates an {@code PrimitiveIterator.OfLong} from a
      * {@code Spliterator.OfLong}.
      *
-     * <p>Traversal of the spliterator must be accomplished through the returned
-     * iterator.  During traversal the spliterator must not be operated on.
+     * <p>Traversal of elements should be accomplished through the iterator.
+     * The behaviour of traversal is undefined if the spliterator is operated
+     * on during traversal.
      *
      * @param spliterator The spliterator
      * @throws NullPointerException if the given spliterator is {@code null}
@@ -589,8 +605,9 @@
      * Creates an {@code PrimitiveIterator.OfDouble} from a
      * {@code Spliterator.OfDouble}.
      *
-     * <p>Traversal of the spliterator must be accomplished through the returned
-     * iterator.  During traversal the spliterator must not be operated on.
+     * <p>Traversal of elements should be accomplished through the iterator.
+     * The behaviour of traversal is undefined if the spliterator is operated
+     * on during traversal.
      *
      * @param spliterator The spliterator
      * @throws NullPointerException if the given spliterator is {@code null}
@@ -1450,7 +1467,7 @@
     // Iterator-based Spliterators
 
     /**
-     * A basic Spliterator using a given Iterator for element
+     * A Spliterator using a given Iterator for element
      * operations. The spliterator implements {@code trySplit} to
      * permit limited parallelism.
      */
@@ -1590,7 +1607,7 @@
     }
 
     /**
-     * A basic Spliterator.OfInt using a given IntStream.IntIterator for element
+     * A Spliterator.OfInt using a given IntStream.IntIterator for element
      * operations. The spliterator implements {@code trySplit} to
      * permit limited parallelism.
      */