RFR(s): 8060192: Add default method Collection.toArray(generator)

[Stuart Marks]

>  
> +    // no spec changes relative to supertype
> +    public <T> T[] toArray(IntFunction<T[]> generator) {
> 
> You probably at least need @inheritDoc for the unchecked exception throws (as I've forgotten many times)
> 

There's a new javadoc option "--override-methods summary" that was recently 
added that we're using now. If an overriding method has no doc comment, it's 
simply listed in the "Methods inherited from" section at the bottom of the 
summary table. (It's now called "Methods declared in".)

See it in action here:

     http://download.java.net/java/jdk10/docs/api/java/util/Properties.html

Compare it to the JDK 9 version of Properties.

(This suggests a big cleanup in collections, and probably many other areas, 
where docs were copied into subclasses for no good reason, or because they 
wanted to disinherit stuff that properly belongs in @implSpec.)

> The needToWorkAround6260652 changes ought to be in a separate changeset.

OK, I can pull these out.

> The biggest question is whether Collection.toArray(generator) pulls its weight, especially in view of https://shipilev.net/blog/2016/arrays-wisdom-ancients.
> 
> I rarely want to dump elements into a typed array.  Dumping into Object[] with toArray() is just fine for me (but I'm a biased core library developer).

Yeah, most collections want to use Object[]. But when you want a typed array, 
this is really helpful.

> Oh wait - Aleksey actually links to this bug!  Sounds like he would be the most 
> qualified reviewer!

:-)

s'marks