Summary

Clarify specifications of Collection.toArray() and Collection.toArray(T[ ]).

Problem

The Collection.toArray() method returns Object[] but it doesn't make clear that
the runtime type of the returned array must be Object[]. (Oddly, that is specified in toArray(T[]) which is in the wrong place.) Also, there are a few locations in the specs of toArray() and toArray(T[]) where they are imprecise about array types, array component types, and runtime types.

Solution

Adjust the wording of the specifications of these two methods. No code or behavior changes are included in this changeset.

Specification

diff -r 9bb771005928 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 Thu Nov 30 11:29:09 2017 -0800
@@ -266,21 +266,23 @@

     /**
      * 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 {@linkplain Class#getComponentType
+     * runtime 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
      * allocate a new array even if this collection is backed by an array).
      * The caller is thus free to modify the returned array.
      *
      * <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 {@linkplain Class#getComponentType runtime component
+     * type} is {@code Object}, containing all of the elements in this collection
      */
     Object[] toArray();

     /**
      * Returns an array containing all of the elements in this collection;
@@ -313,18 +315,18 @@
      *     String[] y = x.toArray(new String[0]);</pre>
      *
      * Note that {@code toArray(new Object[0])} is identical in function to
      * {@code toArray()}.
      *
-     * @param  the runtime type of the array to contain the collection
+     * @param  the component type of the array to contain the collection
      * @param a the array into which the elements of this collection are to be
      *        stored, if it is big enough; otherwise, a new array of the same
      *        runtime type is allocated for this purpose.
      * @return an array containing all of the elements in this collection
-     * @throws ArrayStoreException if the runtime type of the specified array
-     *         is not a supertype of the runtime type of every element in
-     *         this collection
+     * @throws ArrayStoreException if the runtime type of any element in this
+     *         collection is not assignable to the {@linkplain Class#getComponentType
+     *         runtime component type} of the specified array
      * @throws NullPointerException if the specified array is null
      */
      T[] toArray(T[] a);

     // Modification Operations