RFR: 8298095: Refine implSpec for SegmentAllocator [v3]

[Maurizio Cimadamore]

On Wed, 26 Jul 2023 14:44:01 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 after comments

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

> 88:      * If the given string contains any {@code '\0'} characters, they will be
> 89:      * copied as well. This means that, depending on the method used to read
> 90:      * the string, such as {@link MemorySegment#getUtf8String(long)}, the string

The initial text in the javadoc of `allocateUtf8String` should be updated as well. It should start with "return a new memory segment that ...". Note also that this text has changed a bit in the panama repo, as a result of https://github.com/openjdk/panama-foreign/pull/836

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

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