On 4/26/2017 4:06 PM, Paul Sandoz wrote:
Please review some documentation changes to VarHandle:
http://cr.openjdk.java.net/~psandoz/jdk9/JDK-8167229-varhandle-docs/webrev/index.html
I notice that "shape" is still mentioned throughout the
MethodHandles.Lookup class.
59 * {@code CT1, CT2, ..., CTn}, the types of <em>coordinate
expressions</em> that
60 * uniquely locate a variable referenced by this VarHandle.
I'm unsure of "uniquely locate". Distinct coordinate expressions can
refer to the same object, due to aliasing. And there is nothing said
later about one VarHandle being the exclusive systemwide locator of a
variable. Do you mean "that _jointly_ locate a variable ..." ?
73 * instance, the initial arguments to the invocation are coordinate
expressions
74 * that indicate precisely which variable is to be accessed.
"that indicate _in precisely which object_ the variable is to be
accessed." ?
BTW Since "array elements" are mentioned in the opening paragraph, and
since here is an example involving String[] as a coordinate type later,
it would be nice to say how a VarHandle pointing to an array element can
be created.
209 * <h1>Compilation of an access mode's method</h1>
First, the term "access mode's method" appears only here and in
accessModeType, but I think you mean "mode" not "mode's".
Second, this section isn't about compilation of the method. Access mode
methods are not native and there is nothing to suggest that a suitably
skilled platform developer can't write one in Java and compile it -- yet
this section will not tell them how to compile it. (I appreciate the
style comes from j.l.i.MethodHandle, and it would be better to avoid
speaking of "Method handle compilation" there.) I recommend "Invoking
access mode methods from source code" and "Invoking access mode methods
from bytecode". Or "Compiling invocation of access mode methods" and
"Performing invocation of access mode methods".
Alex
