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

[Gavin Ray]

Maurizio, while the area of docs in MemorySegment is being worked on, could
it make sense to include a section on memory alignment?

(It may be out of scope)

But for example, not knowing much about low-level programming I tried to do
some basic things with Foreign Memory and got "misaligned access" errors:
https://stackoverflow.com/questions/73430301/java-foreign-memory-varhandlesegmentviewbase-error-misaligned-access-at-addr

If the error message included something like:
"See the Javadoc on MemorySegment#foo to understand alignment"

And then there was a brief explainer somewhere about how memory alignment
works for newbies

I think that would save a lot of pain for folks.


On Wed, Sep 21, 2022 at 6:54 AM Maurizio Cimadamore <mcimadamore at openjdk.org>
wrote:

> 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.
>
> Rather than looking at code changes, it might be perhaps more valuable to
> look at the javadoc, here:
>
> http://cr.openjdk.java.net/~mcimadamore/panama/memory_segment_refresh_javadoc/javadoc/java.base/module-summary.html
>
> -------------
>
> PR: https://git.openjdk.org/panama-foreign/pull/730
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.openjdk.org/pipermail/panama-dev/attachments/20220921/86d76747/attachment.htm>