RFR(S): 8143410: augment pseudo-code descriptions in MethodHandles API
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(). 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
On 22 Feb 2016, at 15:08, Michael Haupt <michael.haupt@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
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@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
On 23 Feb 2016, at 07:39, Michael Haupt <michael.haupt@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@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.
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@oracle.com>:
On 23 Feb 2016, at 07:39, Michael Haupt <michael.haupt@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@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
participants (2)
-
Michael Haupt
-
Paul Sandoz