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

[Jorn Vernee]

On Fri, 22 Sep 2023 16:58:05 GMT, Maurizio Cimadamore <mcimadamore at openjdk.org> wrote:

>> 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.

I've updated the 'header' of these methods, and instead added a more elaborated comment in a second paragraph. The single value `allocateFrom` methods had the same issue. I fixed those as well See: https://github.com/openjdk/jdk/pull/15103/commits/49bdd953eaed8732b59a803516355abc8df31fa3

Here is the re-generated javadoc: https://cr.openjdk.org/~jvernee/FFM_22_PR/v2/java.base/java/lang/foreign/SegmentAllocator.html#allocateFrom(java.lang.foreign.ValueLayout.OfInt,int...)

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

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