8020061: Clarify reporting characteristics between splits
authorpsandoz
Wed, 09 Oct 2013 15:19:56 +0200
changeset 20744 66fd18be6993
parent 20743 cd866b3875d8
child 20745 3d2e35965c56
8020061: Clarify reporting characteristics between splits Reviewed-by: alanb, chegar
jdk/src/share/classes/java/util/Spliterator.java
--- a/jdk/src/share/classes/java/util/Spliterator.java	Wed Oct 09 10:48:44 2013 +0100
+++ b/jdk/src/share/classes/java/util/Spliterator.java	Wed Oct 09 15:19:56 2013 +0200
@@ -414,13 +414,19 @@
      * #ORDERED}, {@link #DISTINCT}, {@link #SORTED}, {@link #SIZED},
      * {@link #NONNULL}, {@link #IMMUTABLE}, {@link #CONCURRENT},
      * {@link #SUBSIZED}.  Repeated calls to {@code characteristics()} on
-     * a given spliterator should always return the same result.
+     * a given spliterator, prior to or in-between calls to {@code trySplit},
+     * should always return the same result.
      *
      * <p>If a Spliterator reports an inconsistent set of
      * characteristics (either those returned from a single invocation
      * or across multiple invocations), no guarantees can be made
      * about any computation using this Spliterator.
      *
+     * @apiNote The characteristics of a given spliterator before splitting
+     * may differ from the characteristics after splitting.  For specific
+     * examples see the characteristic values {@link #SIZED}, {@link #SUBSIZED}
+     * and {@link #CONCURRENT}.
+     *
      * @return a representation of characteristics
      */
     int characteristics();