News from the backport: Hitches in MethodHandles

[Rémi Forax]

While hacking the backport, I found some hitches in MethodHandles doc,
here is my notes:

- The documentation of spread/collectArgument talk about an array type T[]
  but T is not defined. The question here is: Can T be a primitive type 
or not ?

- Mismatch between  spread/collectArguments() regarding
   the case where there is no parameter to collect.
   spread allow null as an array, collect doesn't specified if it will 
create
   an array or just send null.

- drop/insert, spread/collect, permute doesn't specify
that an IllegalArgumentException can be thrown.

- convertArgument specify that instead of an IllegalArgumentException,
  a WrongMethodTypeException is used to indicate inconvertible type.
  I don't really understand why and the current implementaion doesn't follow
  the doc (i.e raise an IAE).

- the actual implementation of combineArguments() allow "pos" to
be negative but this is not specified in the doc.

- permute arguments should take the reorder array as a varargs:
  MethodHandle permuteArguments(MethodHandle target, MethodType newType, 
int... reorder)

- drop allow to drop more than one arguments but insert don't.
  insert should be:
  MethodHandle insertArguments(MethodHandle target, int index, Object... 
value)

- some adapters allow conversions, and some doesn't.
   Allow conversions:
     spread, permute
   Don't allow conversions:
     combine, guardWithTest, drop, insert, collect
   The rational should be: if the type of the resulting method handler 
is present
    in the signature of the method, conversions are allowed.
   So collect should allow conversions.
   Moreover, combine and guardWithTest should allow conversions too,
   perhaps by taking the type of the resulting method handle.

- arrayElementGetter/arrayElementSetter are useless because JavaMethodHandle
  is much more powerfull. I don't see why array deverse a special treatment.

- invoke_* have no documentation ??
  Are they part of the spec or not ?

cheers,
Rémi