[foreign-memaccess+abi] RFR: Refresh FFM documents

[Per Minborg]

On Tue, 19 Dec 2023 14:29:21 GMT, Maurizio Cimadamore <mcimadamore at openjdk.org> wrote:

> This PR brings the FFM documents in sync with the finalized API in JDK 22. The most obvious changes are:
> 
> * in the foreign memory document, the section on structured access has been rectified, to take into account the extra offset parameter that is added to memory access var handles;
> * in both documents, several calls to `allocateArray` and `allocateUtf8String` have been replaced with `allocateFrom`
> * the section introducing the `Linker` in the ffi document has been revamped; it now talks more at length about the mapping between layouts and C types. The table with Linux/x64 mappings has been moved to a section in the appendix, and I have also added a mention of `Linker::canonicalLayouts`

It would be possible to include the examples in the text in the Snippets.java file so we can make sure the syntax is correct now and also over time.

doc/panama_memaccess.md line 249:

> 247: try (Arena slicingArena = new SlicingArena(1000)) {
> 248:      for (int i = 0 ; i < 10 ; i++) {
> 249:          MemorySegment s = arena.allocateArray(JAVA_INT, 1, 2, 3, 4, 5);

I think this should read `arena.allocateFrom(...)`

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

PR Comment: https://git.openjdk.org/panama-foreign/pull/914#issuecomment-1864083631
PR Review Comment: https://git.openjdk.org/panama-foreign/pull/914#discussion_r1432421376