RFR 9 JDK-8180075: Javadoc of MethodHandles.Lookup::bind should note the difference from MethodHandle::bindTo introduced by JDK-8177146

[Paul Sandoz]

> On 10 May 2017, at 13:46, Ron Pressler <ron.pressler at oracle.com> wrote:
> 
> Hi.
> Please review the following doc-only patch.
> 
> Bug: https://bugs.openjdk.java.net/browse/JDK-8180075
> 
> There is no change in specification, only an elaboration on a note.
> 

+1

Paul.

> Ron
> 
> ----
> 
> diff -r fc53a0468c1f src/java.base/share/classes/java/lang/invoke/MethodHandles.java
> --- a/src/java.base/share/classes/java/lang/invoke/MethodHandles.java Fri Apr 14 00:05:54 2017 -0700
> +++ b/src/java.base/share/classes/java/lang/invoke/MethodHandles.java Wed May 10 20:38:05 2017 +0000
> @@ -1660,7 +1660,7 @@
>          * (If the trailing array argument is the only argument,
>          * the given receiver value will be bound to it.)
>          * <p>
> -         * This is equivalent to the following code:
> +         * This is almost equivalent to the following code, with some differences noted below:
>          * <blockquote><pre>{@code
> import static java.lang.invoke.MethodHandles.*;
> import static java.lang.invoke.MethodType.*;
> @@ -1673,7 +1673,10 @@
>          * where {@code defc} is either {@code receiver.getClass()} or a super
>          * type of that class, in which the requested method is accessible
>          * to the lookup class.
> -         * (Note that {@code bindTo} does not preserve variable arity.)
> +         * (Unlike {@code bind}, {@code bindTo} does not preserve variable arity.
> +         * Also, {@code bindTo} may throw a {@code ClassCastException} in instances where {@code bind} would
> +         * throw a {@code IllegalAccessException}, as in the case where the member is {@code protected} and
> +         * the receiver is restricted by {@code findVirtual} to the lookup class.)
>          * @param receiver the object from which the method is accessed
>          * @param name the name of the method
>          * @param type the type of the method, with the receiver argument omitted
> 
>