RFR: 8308645: Javadoc of FFM API needs to be refreshed [v5]

[Jorn Vernee]

On Fri, 2 Jun 2023 11:41:38 GMT, Maurizio Cimadamore <mcimadamore at openjdk.org> wrote:

>> As the FFM API evolved over time, some parts of the javadoc went out of sync. Now that most of the API is stable, it is a good time to look again at the javadoc as a whole, and bring some more consistency.
>> 
>> While most of the changes in this PR are stylistic, I'd like to call out few things which resulted in API changes:
>> 
>> * `MemorySegment::asSlice(long, long, long)` did not (incorrectly) specified requirement that its alignment parameter must be a power of two.
>> 
>> * `MemoryLayout::sliceHandle` did not require the absence of dereference paths in the provided layout path. While that is technically possible to allow, currently the method is specified as returning a "slice" corresponding to some "nested layout", so following pointers seems incompatible with the spec. I have decided to disallow for now - we can always compatibly enable it later, if required.
>> 
>> * `MemorySegment::copy` - most of the overloads did not specify that `UnsupportedOperationException` is thrown if the destination segment is read-only.
>> 
>> * In several places, an extra `@throws IllegalArgumentException` or `@throws IllegalArgumentException` has been added to capture cases where element size * index computation can overflow. This is true for all the element-wise segment copy methods, for the indexed accessors in memory segment (e.g. `MemorySegment.getAtIndex(ValueLayout.OfInt, long)`), as well as for `SegmentAllocator::allocateArray(MemoryLayout, long)`.
>> 
>> In all these cases (except for overflows), new tests have been added to cover the additional API changes (a CSR will also be filed to cover these).
>> 
>> The class with most changes is `MemoryLayout`. I realized that the javadoc there was a bit sloppy around the definition of "layout paths". Now there are several subsection in the class javadoc, which explain how different kinds of paths can be used. I have introduced the notion of "open path elements" to denote those path elements that are not fully specified, and result in additional var handle coordinates to be added. There is also now a definition of what it means for a layout path to be "well-formed", so that all methods accepting a layout path can simply refer to it (this definition is tricky to give inline in the javadoc of the various path-accepting methods, as it depends on many factors).
>> 
>> Another biggie change was in `MemorySegment` as now all dereference methods state precisely their spatial checks requirements, as well also specifying when the API can th...
>
> Maurizio Cimadamore has updated the pull request incrementally with three additional commits since the last revision:
> 
>  - Missed a review comment
>  - Use more `{@return}` tags
>  - Address review comments

Marked as reviewed by jvernee (Reviewer).

src/java.base/share/classes/java/lang/foreign/MemorySegment.java line 945:

> 943:      * cannot be returned if this segment's size is greater than {@link Integer#MAX_VALUE};</li>
> 944:      * <li>It is a {@linkplain ByteBuffer#isDirect() direct buffer}, if this is a native segment.</li>
> 945:      * </ul>

Nice!

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

PR Review: https://git.openjdk.org/jdk/pull/14098#pullrequestreview-1457977686
PR Review Comment: https://git.openjdk.org/jdk/pull/14098#discussion_r1214587551