RFR: 8298095: Refine implSpec for SegmentAllocator [v2]

[Maurizio Cimadamore]

On Mon, 24 Jul 2023 13:32:58 GMT, Per Minborg <pminborg at openjdk.org> wrote:

>> This PR suggests refining the `@implSpec` for the SegmentAllocator::allocate methods as well as clarifying the docs a bit more. Also, a local variable is renamed.
>
> Per Minborg has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Update array methods

src/java.base/share/classes/java/lang/foreign/SegmentAllocator.java line 223:

> 221: 
> 222:     /**
> 223:      * {@return a newly allocated memory segment with a {@linkplain MemorySegment#byteSize() byteSize()} of 4

Size should be 8 here - but in general I think I'd rather leave it more general and not to specify sizes. The reader should be able to follow the javadoc, and get that we end up calling `allocate(long, long)` with certain parameters (which are derived from the layout). I don't think being extra precise here helps - and also opens up to issues: note that the alignment of double/long layout constants is platform-specific, which I don't think you want to get into here?

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

PR Review Comment: https://git.openjdk.org/jdk/pull/14997#discussion_r1272403749