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 104:

> 102: 
> 103:     /**
> 104:      * {@return a newly allocated memory segment with a {@linkplain MemorySegment#byteSize() byteSize()} of 1

The emphasis of "newly allocated" is IMHO wrong (although that was there even before). Recycling allocators do not "allocate" - so we should make this more neutral. Perhaps just "return a new memory segment..."

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

> 105:      * initialized with the provided byte {@code value}}.
> 106:      *
> 107:      * @implSpec The default implementation of this method first calls {@code this.allocate(layout)} to

would it be useful to describe what the implementation does in terms of code, rather than narrative text?

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

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