RFR(S): 8143410: augment pseudo-code descriptions in MethodHandles API

[Paul Sandoz]

> On 23 Feb 2016, at 07:39, Michael Haupt <michael.haupt at oracle.com> wrote:
> 
> Hi Paul,
> 
> thank you. I'm holding off on pushing; a new webrev is at http://cr.openjdk.java.net/~mhaupt/8143410/webrev.01. See below for two specific comments.
> 
>> Am 22.02.2016 um 21:45 schrieb Paul Sandoz <paul.sandoz at oracle.com>:
>>> Webrev: http://cr.openjdk.java.net/~mhaupt/8143410/webrev.00
>>> 
>>> The change documents the type variables used in the pseudo-code in the API documentation of the following methods in MethodHandles: catchException(), collectArguments(), filterArguments(), filterReturnValue(), foldArguments(), and guardWithTest().
>> 
>> Just minor stuff:
>> 
>> 2642      * <p>Here is pseudocode for the resulting adapter. In the code, {@code T}
>> 2643      * denotes the return type of both the {@code target} and resulting adapter.
>> 2644      * {@code P}/{@code p} and {@code B}/{@code b} represent the types / values
>> 2645      * of the parameters / arguments that precede / follow the filter position
>> 2646      * {@code pos}. {@code A[i]}/{@code a[i]} stand for the types / values of
>> 
>> 
>> "precede / follow ..." -> "proceed and follow …, respectively” ? like that for the last modified method doc.
> 
> That's "precede" as in "coming before in the list". "Proceed" wouldn't make sense in this context. Or did you mean "... respectively" should be appended? (In the webrev, I've applied the latter.)
> 

Oops, I typed “proceed and follow …, respectively” but meant “precede and follow…, respectively” :-)

Tis a minor thing, I find the use of “and” rather than “/“ flows better, given the already heavy use of ‘/‘.


>> 2884      * }</pre></blockquote>
>> 2885      * <p>Here is pseudocode for the resulting adapter. In the code, {@code V}
>> 2886      * represents the result type of the {@code target}; {@code T}, that of the
>> 2887      * {@code filter}; and {@code A}/{@code a}, the types / values of the
>> 2888      * parameters / arguments of the {@code target} as well as the resulting
>> 2889      * adapter.
>> 2890      * <blockquote><pre>{@code
>> 2891      * V target(A...);
>> 2892      * T filter(V);
>> 
>> 
>> Should target return a type of T, and filter V for consistency with the other pseudocode examples? That might be more changes than you wanna apply in this case :-)
> 
> You're right, the naming should be consistent. I've applied this throughout.
> 

Ok.

Paul.