RFR(s): 8160406: Collection.toArray() spec should be explicit about returning precisely an Object[]

[Stuart Marks]

Hi all,

Please review this small spec change / clarification regarding 
Collection.toArray(). The runtime type of the array returned has always been 
intended to be exactly Object[] and not an array of some subtype. This 
requirement is actually implied by the spec already, but in the wrong place; the 
spec for

     <T> T[] toArray​(T[] a)

says

> Note that toArray(new Object[0]) is identical in function to toArray().

Clearly, this should also be specified on toArray() itself.

Patch is below.

Thanks,

s'marks



diff -r 9bb771005928 -r c3d5e370e06f 
src/java.base/share/classes/java/util/Collection.java
--- a/src/java.base/share/classes/java/util/Collection.java	Tue Nov 28 17:14:30 
2017 -0800
+++ b/src/java.base/share/classes/java/util/Collection.java	Wed Nov 29 14:29:14 
2017 -0800
@@ -268,7 +268,7 @@
       * Returns an array containing all of the elements in this collection.
       * If this collection makes any guarantees as to what order its elements
       * are returned by its iterator, this method must return the elements in
-     * the same order.
+     * the same order. The returned array's component type is {@code Object}.
       *
       * <p>The returned array will be "safe" in that no references to it are
       * maintained by this collection.  (In other words, this method must
@@ -278,7 +278,8 @@
       * <p>This method acts as bridge between array-based and collection-based
       * APIs.
       *
-     * @return an array containing all of the elements in this collection
+     * @return an array, whose component type is {@code Object}, containing all
+     * of the elements in this collection
       */
      Object[] toArray();