[foreign-memaccess+abi] RFR: 8298096: Refine javadoc for Linker [v3]

[Maurizio Cimadamore]

> The javadoc for the `Linker` interface is very abstract: it defines the general characteristics of downcall method handles and upcall stubs, and it does so in a very general way, so as not to bias the discussion towards a specific kind of linker implementation.
> 
> The result is that, looking at the `Linker` javadoc, one has very little clues on how this interface is meant to be used e.g. to write native interop code. While the toplevel package javadoc provides some examples, these examples are relatively simple and do not cover all the features provided by the FFM API.
> 
> To rectify this, I did another pass on the `Linker` javadoc. I retained the very good general intro (the first few paras). But then, instead of talking about "downcalls" and "upcalls" - we immediately start talking about "Calling native functions" and we ground the discussion on the native linker. This gives us the opportunity to discuss native calls, function pointers, variadic calls, and even how to deal with functions returning pointers.
> 
> The text of the sections on upcalls/downcall (which is normative text) has been moved in the javadoc of the relevant methods.
> 
> Finally, since with the new examples there was some overlapping between the toplevel package javadoc and the `Linker` javadoc, I also decided to take another pass at the package javadoc, and simplify it further: now there are only 3 sections: foreign memory, foreign function, restricted methods. For each of the first two sections there's a quick summary (which describes the main abstractions and their roles), followed by an idiomatic example. Restricted methods also belong here, as they are a cross-cutting concern of the FFM API.
> 
> Overall, I believe this iteration is much better than what we had, and more useful. While covering all the details of native interop would be outside the scope of the FFM javadoc, I think the new `Linker` javadoc strikes a good balance.

Maurizio Cimadamore has updated the pull request incrementally with one additional commit since the last revision:

  Clarify padding in structs

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

Changes:
  - all: https://git.openjdk.org/panama-foreign/pull/820/files
  - new: https://git.openjdk.org/panama-foreign/pull/820/files/696d4e46..876b9a1c

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=panama-foreign&pr=820&range=02
 - incr: https://webrevs.openjdk.org/?repo=panama-foreign&pr=820&range=01-02

  Stats: 4 lines in 1 file changed: 2 ins; 0 del; 2 mod
  Patch: https://git.openjdk.org/panama-foreign/pull/820.diff
  Fetch: git fetch https://git.openjdk.org/panama-foreign pull/820/head:pull/820

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