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

[Paul Sandoz]

> On 22 Feb 2016, at 15:08, Michael Haupt <michael.haupt at oracle.com> wrote:
> 
> Dear all,
> 
> please review this (doc-only) fix.
> Bug: https://bugs.openjdk.java.net/browse/JDK-8143410
> 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.


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


3123      * Here is pseudocode for the resulting adapter. In the code, {@code V}

"{@code V}” -> "{@code T}”


3124      * represents the return type of the {@code target} and {@code handler},
3125      * and correspondingly that of the resulting adapter; {@code A}/{@code a},
3126      * the types and values of arguments to the resulting handle consumed by
3127      * {@code handler}; and {@code B}/{@code b}, those of arguments to the
3128      * resulting handle discarded by {@code handler}.
3129      * <blockquote><pre>{@code
3130      * T target(A..., B...);
3131      * T handler(ExType, A...);
3132      * T adapter(A... a, B... b) {
3133      *   try {
3134      *     return target(a..., b...);
3135      *   } catch (ExType ex) {
3136      *     return handler(ex, a...);
3137      *   }
3138      * }
3139      * }</pre></blockquote>


Paul.

> Thanks,
> 
> 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
>