[JDK9] RFR 8167229: Improve VarHandle documentation

[Alex Buckley]

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