Alex Buckley has proposed some simplifications to the VarHandle class documentation:

-----
A VarHandle has:

- a variable type T, the type of every variable referenced by this VarHandle; and
- a list of coordinate types CT1..CTn, the types of /coordinate expressions/ that uniquely locate the variable referenced by this VarHandle.

Variable and coordinate types may be primitive or reference, and are represented by Class objects. The list of coordinate types may be empty.

Factory methods document the variable type and coordinate types of the VarHandle instances they produce or lookup. For example, the factory method _findVarHandle(Class,String,Class)_ produces a VarHandle instance that references a non-static field of type T declared in type R, so the VarHandle instance has variable type T and one coordinate type R. The VarHandle instance can be utilized with an instance of R to access the field. As another example, a VarHandle instance produced to reference elements of a T[] array has variable type T and two coordinate types T[] and int. The VarHandle instance can be utilized with an instance of the array type and an int index to access an array element.
-----

-----
MethodHandles.Lookup::findVarHandle :-

Produces a VarHandle giving access to a non-static field /name/ of type /type/ declared in a class of type /recv/.

The VarHandle's variable type is /type/ and it has one coordinate type, /recv/.
-----

-----
Each access mode is associated with an /access mode method/, a signature polymorphic method named for the access mode. When an access mode method is invoked on a VarHandle instance, the initial arguments to the invocation are coordinate expressions that indicate precisely which variable is to be accessed. Trailing arguments to the invocation represent values of importance to the access mode, e.g., the compare-and-set access modes require two trailing arguments for the variable's expected value and new value.

The arity and types of arguments to the invocation are not checked statically. Instead, each access mode method specifies an /access mode descriptor/ that serves as a kind of method signature against which the arguments are checked dynamically. An access mode descriptor gives formal parameter types in terms of the coordinate types of a VarHandle instance and the types for values of importance to the access mode. An access mode descriptor also gives a return type, often in terms of the variable type of a VarHandle instance. When an access mode method is invoked on a VarHandle instance, both the symbolic type descriptor at the call site and the types of arguments to the invocation must match the types given in the access mode descriptor.

For example, the access mode method compareAndSet(Object...) specifies that if its receiver is a VarHandle instance with coordinate types CT1..CTn and variable type T, then its access mode descriptor is (CT1 c1, ..., CTn cn, T extendedValue, T newValue)boolean. Suppose that a VarHandle instance can access array elements, and that its coordinate types are String[] and int while its variable type is String. The access mode descriptor for compareAndSet(Object...) on this VarHandle instance would be (String[] c1, int c2, String extendedValue, String newValue)boolean. Both the symbolic type descriptor at the call site, and the run time types of arguments on the stack, must match the types in the access mode descriptor.
-----