[foreign-memaccess] RFR: 8247924: Improve javadoc of Foreign Memory Access API (part two) [v3]

[Maurizio Cimadamore]

> This patch addresses some misc issues in the foreign memory access javadoc, following some feedback from Brian
> (thanks!).
> Things to look out for:
> 
> * the package-level javadoc has been tweaked so that we first introduce the entities, then the example - also there's a
>   bit more text to make things clearer
> * the javadoc section in MemorySegment on confinement has been moved at the end - since it's fairly advanced
> * the toplevel javadoc of `MemoryLayout` has been reworked pretty substantially; it now has a leading example which shows
>   how to go from a C decl to a layout; that same example is then reused throughout the javadoc to explain layout paths
> 
> When doing this, I realized that the section on layout paths has several mistakes - from code mistakes to a section
> which was repeated twice (!!) no idea how that could have gone through all the review rounds (it's not a merge
> artifact - same issue is in jdk/jdk).

Maurizio Cimadamore has updated the pull request incrementally with two additional commits since the last revision:

 - Merge branch 'foreign-memaccess-doc2' of https://github.com/mcimadamore/panama-foreign into foreign-memaccess-doc2
 - Clarify MemoryLayout javadoc

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

Changes:
  - all: https://git.openjdk.java.net/panama-foreign/pull/211/files
  - new: https://git.openjdk.java.net/panama-foreign/pull/211/files/f7a7f60d..e1ef968d

Webrevs:
 - full: https://webrevs.openjdk.java.net/panama-foreign/211/webrev.02
 - incr: https://webrevs.openjdk.java.net/panama-foreign/211/webrev.01-02

  Stats: 1 line in 1 file changed: 0 ins; 0 del; 1 mod
  Patch: https://git.openjdk.java.net/panama-foreign/pull/211.diff
  Fetch: git fetch https://git.openjdk.java.net/panama-foreign pull/211/head:pull/211

PR: https://git.openjdk.java.net/panama-foreign/pull/211