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.r...@oracle.com>, Mike Duigou
<mike.dui...@oracle.com>,
Paul Sandoz <paul.san...@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
