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

[Michael Haupt]

Hi Paul,

thanks - all right; I'll consider using "and" rather than "/" and push the result.

Best,

Michael

> Am 23.02.2016 um 09:13 schrieb Paul Sandoz <paul.sandoz at oracle.com>:
> 
>> 
>> 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.

-- 

 <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