Please, observe j.l.i.MethodHandles.whileLoop(...) sections:

1. Returns: the value of the loop variable as the loop terminates.
This could mislead users because actually this method returns method handle representing loop. But this information is necessary to, I suppose it could be good to store this assertion somewhere in documentation.
2. Throws: IllegalArgumentException - if any argument has a type inconsistent with the loop structure
It looks a little bit unclear, because there is no definition for 'loop structure'.
3. The pred handle must have an additional leading parameter of the same type as init's result, and so must the body.
-- It looks a little bit unclear, it's hard to understand what kind of parameters should 'pred' and body' have. It's clear that leading parameter is the same as 'init' return type, but there is no rules for other parameters. It could be deducted from pseudocode, but maybe it would be good to make this description clearer.
-- The parameter list of resulting method handle could be deducted from pseudocode too, but it couldn't be determined from preceeding documentation.
4. The implementation of this method is equivalent to:
 MethodHandle whileLoop(MethodHandle init, MethodHandle pred, MethodHandle body) {
     MethodHandle[]
         checkExit = {null, null, pred, identity(init.type().returnType())},
         varBody = {init, body};
     return loop(checkExit, varBody);
 }


I suppose we can't say they are equals because according to doc, 'init'=null should work correctly, but according to given documentation, 'init'=null will lead to NullPointerException (see init.type()). So same calls with init==null for jdk implementation and for given implementation have different results. Example attached.