On Fri, 22 Sep 2023 16:58:05 GMT, Maurizio Cimadamore <mcimadam...@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
