RFR 8013334: Spliterator behavior for LinkedList contradicts Spliterator.trySplit

[Peter Levart]

Hi Paul,

Maybe the JavaDoc could also suggest that the trySplit producing N+0 
result should converge so that returned Spliterator eventualy produces 
either null+N or n+m (n<N, m<N) and splitting terminates in finite 
number of steps. Also I don't know why would any Spliterator 
implementation want to return 0+N from trySplit (the N+0 return can be 
useful because the returned instance can be of different 
class/implementation, but the 0+N has no utility), so the javaDoc could 
be more strict:

       * Upon non-null return:
       * <ul>
       * <li>the value reported for {@code estimateSize()} before splitting,
       * must, after splitting, be greater than {@code estimateSize()}
       * for this and greater than or equal than {@code estimateSize()}
       * for the returned Spliterator; and</li>
       * <li>if this Spliterator is {@code SUBSIZED}, then {@code estimateSize()}
       * for this spliterator before splitting must be equal to the sum of
       * {@code estimateSize()} for this and the returned Spliterator after
  


Regards, Peter


On 05/03/2013 11:10 AM, Paul Sandoz wrote:
> Hi,
>
> Please review the patch below for some minor fixes to the Spltierator JavaDoc and a tweak to the spec of Spliterator.trySplit.
>
> http://bugs.sun.com/view_bug.do?bug_id=8013334
>
> Paul.
>
> # HG changeset patch
> # User psandoz
> # Date 1367571917 -7200
> # Node ID fda6ca78a7c299349f201c310ec480351a855ed1
> # Parent  470f19b6bfdd07aed3ca6e0debdabcd8cd7f8083
> 8013334: Spliterator behavior for LinkedList contradicts Spliterator.trySplit
> Summary: In addition to fixing 8013334 this changeset containts some minor,
> non spec, related fixes to tidy up other areas of the JavaDoc.
> Reviewed-by:
> Contributed-by: John Rose <john.r.rose at oracle.com>, Mike Duigou <mike.duigou at oracle.com>,
> Paul Sandoz <paul.sandoz at oracle.com>
>
> diff -r 470f19b6bfdd -r fda6ca78a7c2 src/share/classes/java/util/Spliterator.java
> --- a/src/share/classes/java/util/Spliterator.java	Thu May 02 13:21:09 2013 +0200
> +++ b/src/share/classes/java/util/Spliterator.java	Fri May 03 11:05:17 2013 +0200
> @@ -140,32 +140,32 @@
>    * (in approximate order of decreasing desirability):
>    * <ul>
>    * <li>The source cannot be structurally interfered with.
> - * </br>For example, an instance of
> + * <br>For example, an instance of
>    * {@link java.util.concurrent.CopyOnWriteArrayList} is an immutable source.
>    * A Spliterator created from the source reports a characteristic of
>    * {@code IMMUTABLE}.</li>
>    * <li>The source manages concurrent modifications.
> - * </br>For example, a key set of a {@link java.util.concurrent.ConcurrentHashMap}
> + * <br>For example, a key set of a {@link java.util.concurrent.ConcurrentHashMap}
>    * is a concurrent source.  A Spliterator created from the source reports a
>    * characteristic of {@code CONCURRENT}.</li>
>    * <li>The mutable source provides a late-binding and fail-fast Spliterator.
> - * </br>Late binding narrows the window during which interference can affect
> + * <br>Late binding narrows the window during which interference can affect
>    * the calculation; fail-fast detects, on a best-effort basis, that structural
>    * interference has occurred after traversal has commenced and throws
>    * {@link ConcurrentModificationException}.  For example, {@link ArrayList},
>    * and many other non-concurrent {@code Collection} classes in the JDK, provide
>    * a late-binding, fail-fast spliterator.</li>
>    * <li>The mutable source provides a non-late-binding but fail-fast Spliterator.
> - * </br>The source increases the likelihood of throwing
> + * <br>The source increases the likelihood of throwing
>    * {@code ConcurrentModificationException} since the window of potential
>    * interference is larger.</li>
>    * <li>The mutable source provides a late-binding and non-fail-fast Spliterator.
> - * </br>The source risks arbitrary, non-deterministic behavior after traversal
> + * <br>The source risks arbitrary, non-deterministic behavior after traversal
>    * has commenced since interference is not detected.
>    * </li>
>    * <li>The mutable source provides a non-late-binding and non-fail-fast
>    * Spliterator.
> - * </br>The source increases the risk of arbitrary, non-deterministic behavior
> + * <br>The source increases the risk of arbitrary, non-deterministic behavior
>    * since non-detected interference may occur after construction.
>    * </li>
>    * </ul>
> @@ -284,6 +284,8 @@
>    * is set to {@code true} then diagnostic warnings are reported if boxing of
>    * primitive values occur when operating on primitive subtype specializations.
>    *
> + * @param <T> the type of elements returned by this Spliterator
> + *
>    * @see Collection
>    * @since 1.8
>    */
> @@ -333,9 +335,8 @@
>        * Upon non-null return:
>        * <ul>
>        * <li>the value reported for {@code estimateSize()} before splitting,
> -     * if not already zero or {@code Long.MAX_VALUE}, must, after splitting, be
> -     * greater than {@code estimateSize()} for this and the returned
> -     * Spliterator; and</li>
> +     * must, after splitting, be greater than or equal to {@code estimateSize()}
> +     * for this and the returned Spliterator; and</li>
>        * <li>if this Spliterator is {@code SUBSIZED}, then {@code estimateSize()}
>        * for this spliterator before splitting must be equal to the sum of
>        * {@code estimateSize()} for this and the returned Spliterator after