RFR(S): 8150360: augment/correct MethodHandle API documentation

[Michael Haupt]

Dear all,

please review this (doc-only) fix.
Bug: https://bugs.openjdk.java.net/browse/JDK-8150360
Webrev: http://cr.openjdk.java.net/~mhaupt/8150360/webrev.00

The fix addresses one contradiction in the API documentation of MethodHandles.tryFinally(), and adds the following note to the API documentation of the method handle combinators given below:

+     * <p>
+     * <em>Note:</em> The resulting adapter is never a {@linkplain MethodHandle#asVarargsCollector
+     * variable-arity method handle}, even if the original target method handle was.

* MethodHandle.asCollector(), .bindTo()
* MethodHandles.collectArguments(), .dropArguments(), .filterArguments(), .filterReturnValue(), .foldArguments(), .permuteArguments()

Thanks,

Michael

-- 

 <http://www.oracle.com/>
Dr. Michael Haupt | Principal Member of Technical Staff
Phone: +49 331 200 7277 | Fax: +49 331 200 7561
Oracle Java Platform Group | LangTools Team | Nashorn
Oracle Deutschland B.V. & Co. KG | Schiffbauergasse 14 | 14467 Potsdam, Germany

ORACLE Deutschland B.V. & Co. KG | Hauptverwaltung: Riesstraße 25, D-80992 München
Registergericht: Amtsgericht München, HRA 95603

Komplementärin: ORACLE Deutschland Verwaltung B.V. | Hertogswetering 163/167, 3543 AS Utrecht, Niederlande
Handelsregister der Handelskammer Midden-Nederland, Nr. 30143697
Geschäftsführer: Alexander van der Ven, Jan Schultheiss, Val Maher
 <http://www.oracle.com/commitment>	Oracle is committed to developing practices and products that help protect the environment