Javadoc complexity

[Paul Sandoz]

On Aug 27, 2013, at 4:30 PM, Peter Levart <peter.levart at gmail.com> wrote:

> On 08/27/2013 12:57 PM, Stephen Colebourne wrote:
>> The Javadoc of JDK8 is starting to show some unecessary complexity
>> folowing the library changes for lambda. This needs combatting to
>> avoid scaring developers. This is therefore a request for a minor
>> tweak to Javadoc.
>> 
>> See
>> http://download.java.net/jdk8/docs/api/java/util/package-summary.html
>> 
>> Note in particular that there is some immediate "in your face" type
>> parameter complexity:
>> 
>> Spliterator.OfPrimitive<T,T_CONS,T_SPLITR extends
>> Spliterator.OfPrimitive<T,T_CONS,T_SPLITR>>
> Hi Stephen and list,
> 
> I don't know if that still holds now, but a couple of months ago I 
> noticed that T_SPLITR generic parameter seems to be redundant.

Oopps sorry i forgot to respond to that. I think it still holds.


> All 
> current JDK code can be modified to cope without it:
> 
> http://cr.openjdk.java.net/~plevart/lambda/Spliterator.OfPrimitive/webrev.01/
> 
> I can check if that still holds now. Even if it does, a question remains 
> if the parameter was introduced for some other reason...
> 

IIRC the rational was that OfPrimitive impls wrapping some other spliterator instance could implement trySplit and call trySplit on the wrapping spliterator without casting.

But in all our cases such trySplit implementations are shared between T (Object) and the primitives and a cast is required for any declared T_SPLITR type in the class hierarchy.

I think we can apply your patch to simplify the signature given the stream impl never takes advantage of the additional type (as proven by the changes you had to make), and i suspect others will not either.

Paul.