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

[Maurizio Cimadamore]

Please look at the new linked javadoc:

http://cr.openjdk.java.net/~mcimadamore/panama/memory_segment_refresh_javadoc/javadoc/java.base/java/lang/foreign/MemorySegment.html#segment-alignment

The section has been reworked big time, and a lot of new examples (both 
on what alignment _means_ and on how clients are supposed to work with 
it) have been added.

As for referencing javadoc sections from exception messages, I'm not 
sure there is any precedent in other JDK APIs.

Maurizio

On 21/09/2022 12:21, Gavin Ray wrote:
> 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/ad11699f/attachment-0001.htm>