[foreign-memaccess+abi] RFR: Beef up javadoc for base offset in var handles derived from layouts

[Jorn Vernee]

On Tue, 3 Oct 2023 14:42:16 GMT, Maurizio Cimadamore <mcimadamore at openjdk.org> wrote:

> This PR adds more javadoc to explain how base offsets in var handles obtained from layouts can be used.
> 
> First, a number of examples in the main `MemoryLayout` javadoc is rectified, as such examples did not use the additional base offset parameter (and were hence incorrect).
> 
> Second, the var handles part in the `MemorySegment` section on "accessing memory segment" has been rewritten to avoid duplication with the concepts exposed in `MemoryLayout`. Now we show how `MemorySegment::get` and `MemorySegment::getAtIndex` can be obtained using basic var handles and combinators. We mention that more complex var handles can be obtained using layout paths, but we now just reference the layout path section.
> 
> Last, I've added a new section on the `MemoryLayout` javadoc, with an example on how to deal with variable-length structs. This example showcases how var handles can be used in intricate situations, and combined with the new `scaleOffset` method.

src/java.base/share/classes/java/lang/foreign/MemoryLayout.java line 323:

> 321:  * the {@code x} and {@code y} coordinates, accordingly. The first layout is used to obtain a var handle
> 322:  * that provides access to the polygon size; the second layout is used to obtain a var handle that provides
> 323:  * access to the {@code x} coordinate of a point struct. Finally, an offset to the start of the variable-length

'first' and 'second' seem reversed here? (the first layout is the point, from which we get a VH to access 'x')

src/java.base/share/classes/java/lang/foreign/MemorySegment.java line 146:

> 144:  * MethodHandle scale = ValueLayout.JAVA_INT.scaleHandle();              // (long, long)long
> 145:  * VarHandle intAtOffsetAndIndexHandle =
> 146:  *         MethodHandles.filterCoordinates(intAtOffsetHandle, 1, scale); // (MemorySegment, long, long)

This should be `collectCoordinates`. (`filterCoordinates` only works for filters with a single parameter)

-------------

PR Review Comment: https://git.openjdk.org/panama-foreign/pull/901#discussion_r1345783289
PR Review Comment: https://git.openjdk.org/panama-foreign/pull/901#discussion_r1345772747