8024408: Specifications for Collection/List/Set/SortedSet.spliterator() need...

8024408: Specifications for Collection/List/Set/SortedSet.spliterator() need to document if all the (subclass) instances are required to return SIZED spliterators
Reviewed-by: alanb

src/share/classes/java/util/Collection.java

@@ -503,12 +503,10 @@ public interface Collection<E> extends Iterable<E> {
     /**
      * Creates a {@link Spliterator} over the elements in this collection.
      *
-     * <p>The returned {@code Spliterator} must report the characteristic
-     * {@link Spliterator#SIZED}; implementations should document any additional
-     * characteristic values reported by the returned spliterator.  If
-     * this collection contains no elements then the returned spliterator is
-     * only required to report {@link Spliterator#SIZED} and is not required to
-     * report additional characteristic values (if any).
+     * Implementations should document characteristic values reported by the
+     * spliterator.  Such characteristic values are not required to be reported
+     * if the spliterator reports {@link Spliterator#SIZED} and this collection
+     * contains no elements.
      *
      * <p>The default implementation should be overridden by subclasses that
      * can return a more efficient spliterator.  In order to
@@ -534,9 +532,11 @@ public interface Collection<E> extends Iterable<E> {
      * <em><a href="Spliterator.html#binding">late-binding</a></em> spliterator
      * from the collections's {@code Iterator}.  The spliterator inherits the
      * <em>fail-fast</em> properties of the collection's iterator.
+     * <p>
+     * The created {@code Spliterator} reports {@link Spliterator#SIZED}.
      *
      * @implNote
-     * The returned {@code Spliterator} additionally reports
+     * The created {@code Spliterator} additionally reports
      * {@link Spliterator#SUBSIZED}.
      *
      * <p>If a spliterator covers no elements then the reporting of additional

src/share/classes/java/util/Set.java

@@ -386,15 +386,18 @@ public interface Set<E> extends Collection<E> {
     /**
      * Creates a {@code Spliterator} over the elements in this set.
      *
-     * <p>The {@code Spliterator} reports {@link Spliterator#SIZED} and
-     * {@link Spliterator#DISTINCT}.  Implementations should document the
-     * reporting of additional characteristic values.
+     * <p>The {@code Spliterator} reports {@link Spliterator#DISTINCT}.
+     * Implementations should document the reporting of additional
+     * characteristic values.
      *
      * @implSpec
      * The default implementation creates a
      * <em><a href="Spliterator.html#binding">late-binding</a></em> spliterator
      * from the set's {@code Iterator}.  The spliterator inherits the
      * <em>fail-fast</em> properties of the set's iterator.
+     * <p>
+     * The created {@code Spliterator} additionally reports
+     * {@link Spliterator#SIZED}.
      *
      * @implNote
      * The created {@code Spliterator} additionally reports

src/share/classes/java/util/SortedSet.java

@@ -223,10 +223,10 @@ public interface SortedSet<E> extends Set<E> {
     /**
      * Creates a {@code Spliterator} over the elements in this sorted set.
      *
-     * <p>The {@code Spliterator} reports {@link Spliterator#SIZED},
-     * {@link Spliterator#DISTINCT}, {@link Spliterator#SORTED} and
-     * {@link Spliterator#ORDERED}.  Implementations should document the
-     * reporting of additional characteristic values.
+     * <p>The {@code Spliterator} reports {@link Spliterator#DISTINCT},
+     * {@link Spliterator#SORTED} and {@link Spliterator#ORDERED}.
+     * Implementations should document the reporting of additional
+     * characteristic values.
      *
      * <p>The spliterator's comparator (see
      * {@link java.util.Spliterator#getComparator()}) must be {@code null} if
@@ -240,6 +240,9 @@ public interface SortedSet<E> extends Set<E> {
      * from the sorted set's {@code Iterator}.  The spliterator inherits the
      * <em>fail-fast</em> properties of the set's iterator.  The
      * spliterator's comparator is the same as the sorted set's comparator.
+     * <p>
+     * The created {@code Spliterator} additionally reports
+     * {@link Spliterator#SIZED}.
      *
      * @implNote
      * The created {@code Spliterator} additionally reports

test/java/util/Spliterator/SpliteratorCharacteristics.java

@@ -23,7 +23,7 @@
 
 /**
  * @test
- * @bug 8020156 8020009 8022326 8012913 8024405
+ * @bug 8020156 8020009 8022326 8012913 8024405 8024408
  * @run testng SpliteratorCharacteristics
  */
 
@@ -46,6 +46,7 @@ import java.util.Spliterator;
 import java.util.Spliterators;
 import java.util.TreeMap;
 import java.util.TreeSet;
+import java.util.WeakHashMap;
 import java.util.concurrent.ConcurrentSkipListMap;
 import java.util.concurrent.ConcurrentSkipListSet;
 import java.util.function.Supplier;
@@ -185,6 +186,11 @@ public class SpliteratorCharacteristics {
                                  Spliterator.SIZED | Spliterator.DISTINCT);
     }
 
+    public void testWeakHashMap() {
+        assertMapCharacteristics(new WeakHashMap<>(),
+                                 Spliterator.DISTINCT);
+    }
+
     public void testHashSet() {
         assertSetCharacteristics(new HashSet<>(),
                                  Spliterator.SIZED | Spliterator.DISTINCT);