RFR: 8312522: Implementation of Foreign Function & Memory API [v22]

[Maurizio Cimadamore]

On Fri, 22 Sep 2023 16:29:51 GMT, Jorn Vernee <jvernee at openjdk.org> wrote:

>> I forgot about the change that went into mainline. Do you have a link of the latest javadoc? I'd like to check how the method summary looks.
>
> Here you go: https://cr.openjdk.org/~jvernee/FFM_22_PR_v1/java.base/java/lang/foreign/SegmentAllocator.html#allocateFrom(java.lang.foreign.ValueLayout,java.lang.foreign.MemorySegment,java.lang.foreign.ValueLayout,long,long)

Ok, now I'm more convinced that the method summary really does look bad (or worse, compared to 20).

For instance [allocateFrom](https://cr.openjdk.org/~jvernee/FFM_22_PR_v1/java.base/java/lang/foreign/SegmentAllocator.html#allocateFrom(java.lang.foreign.ValueLayout.OfByte,byte...):


Returns a new memory segment with a byteSize() initialized with the provided E byte elements as specified by the provided layout (i.e. byte ordering, alignment and size).


(same is true for all the other array-accepting `allocateFrom` methods). This should be simplified to:


Returns a new memory segment initialized with the elements in the provided byte array.

(then, if we want to say that the initialization honors the endianness of the provided layout, we can do so in a followup para, but the method summary should be simple).

So, once all the array-accepting methods are fixed, the segment-accepting `allocateFrom` needs to be simplified to:


Returns a new memory segment initialized with the contents of the provided segment.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/15103#discussion_r1334627056