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

[Maurizio Cimadamore]

On Wed, 21 Sep 2022 10:47:07 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.

This pull request has now been integrated.

Changeset: 9d5141d8
Author:    Maurizio Cimadamore <mcimadamore at openjdk.org>
URL:       https://git.openjdk.org/panama-foreign/commit/9d5141d89088ae62118604694c3803875a3494b7
Stats:     707 lines in 11 files changed: 228 ins; 83 del; 396 mod

8292034: Improve javadoc after memory segment/memory address unification

Reviewed-by: jvernee

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

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