[foreign-memaccess+abi] RFR: 8292034: Improve javadoc after memory segment/memory address unification [v2]

[Per Minborg]

On Wed, 21 Sep 2022 11:52:14 GMT, Maurizio Cimadamore <mcimadamore at openjdk.org> wrote:

>> This is a rather big patch which overhauls the javadoc of the `MemorySegment` class.
>> A big thanks to Alex Buckley, who helped review the API javadoc and contributed many of the changes you see here.
>> 
>> The main things touched in this PR are:
>> 
>> * the section on unsafe segments is gone from the package-level javadoc. In its place, there's a new section on zero-length memory segments in the `MemorySegment` javadoc
>> * the class javadoc for `MemorySegment` has been overhauled greatly. It now focusses on two kinds of segments (native segments, and heap segments) and define how address, size, alignment of both is handled by the API.
>> * we introduce a distinction between memory segment and "the region of memory" which backs the segment, which helps spelling out a lot of these properties in a cleaner way
>> * perhaps the biggest change in the javadoc is the section on memory segment alignment, which now is much more clearly defined, and provides lots of examples (as that's a complex topic).
>> * some of the javadoc, in both this class and other classes have been tweaked to reflect the new terminology (for instance, references to the term `base address` are gone)
>> 
>> Other javadoc changes might follow, at some point later. The `Linker` class might need some attention, as we don't really spell out how zero-length segments interacts with downcalls and upcalls.
>> But, given the size of the changes, I'd rather deal with that separately.
>
> Maurizio Cimadamore has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Replace "alignment constraints" with "alignment constraint", in accordance to what done in `MemorySegment` javadoc

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

> 64:  *     <li>A <em>native segment</em> is backed by, and provides access to, a region of memory outside the Java heap (an "off-heap" region).</li>
> 65:  * </ul>
> 66:  * Heap segments can be obtained by calling one of the {@link MemorySegment#ofArray(int[])} factory methods.

There is just one MemorySegment#ofArray(int[]) method. Is there a way of expressing a link to the method reference `MemorySegment::ofArray` (which covers all the overloads)?

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

> 67:  * These methods return a memory segment backed by the on-heap region that holds the specified Java array.
> 68:  * <p>
> 69:  * Native segments can be obtained by calling one of the {@link MemorySegment#allocateNative(long, long)}

DItto here

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

PR: https://git.openjdk.org/panama-foreign/pull/730