Summary

The proposed change is to explicitly state that MethodHandles#insertArguments throws IllegalArgumentException and ClassCastException.

Problem

MethodHandles#insertArguments throws IllegalArgumentException if pos is an illegal index to the target's parameters array, or if there are too many values to insert. MethodHandles.insertArguments also throws ClassCastException if there is a mismatch between the formal and actual param types of the target method. But Javadoc does not explicitly specify these currently.

Solution

Make the documentation more explicit about the implemented behavior.

Specification

src/java.base/share/classes/java/lang/invoke/MethodHandles.java

      * @return a method handle which inserts an additional argument,
      *         before calling the original method handle
      * @throws NullPointerException if the target or the {@code values} array is null
+     * @throws IllegalArgumentException if (@code pos) is less than {@code 0} or greater than
+     *         {@code N - L} where {@code N} is the arity of the target method handle and {@code L}
+     *         is the length of the values array.
+     * @throws ClassCastException if an argument does not match the corresponding bound parameter
+     *         type.
      * @see MethodHandle#bindTo
      */
     public static
     MethodHandle insertArguments(MethodHandle target, int pos, Object... values) {