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 throw because of an overflow during offset computation. Finally, I've left most of the snippets alone, as they are being dealt with in https://github.com/openjdk/jdk/pull/14030 ------------- Commit messages: - Merge branch 'master' into javadoc_fixes - Add overflow tests - Fix overflow @throw in MemorySegment::copy - Add overflow @throws clause on SegmentAllocator::allocateArray - More fixes to MemoryLayout - Finish ValueLayout - Merge branch 'master' into javadoc_fixes - Finish SymbolLookup - Finish SequenceLayout/StructLayout/UnionLayout - Finish SegmentAllocator - ... and 11 more: https://git.openjdk.org/jdk/compare/c0c4d771...afb7360e Changes: https://git.openjdk.org/jdk/pull/14098/files Webrev: https://webrevs.openjdk.org/?repo=jdk&pr=14098&range=00 Issue: https://bugs.openjdk.org/browse/JDK-8308645 Stats: 818 lines in 23 files changed: 269 ins; 116 del; 433 mod Patch: https://git.openjdk.org/jdk/pull/14098.diff Fetch: git fetch https://git.openjdk.org/jdk.git pull/14098/head:pull/14098 PR: https://git.openjdk.org/jdk/pull/14098
