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

[Michael Haupt]

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.)

> 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.

Best,

Michael

-- 

 <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