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

[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 with a new target base due to a merge or a rebase. The pull request
now contains ten commits:

 - Merge branch 'foreign-memaccess' into foreign-memaccess-doc2
 - Merge branch 'foreign-memaccess-doc2' of https://github.com/mcimadamore/panama-foreign into foreign-memaccess-doc2
 - Clarify MemoryLayout javadoc
 - Update src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/MemoryLayout.java
   
   Co-authored-by: Jorn Vernee <JornVernee at users.noreply.github.com>
 - Update src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/package-info.java
   
   Co-authored-by: Jorn Vernee <JornVernee at users.noreply.github.com>
 - Merge branch 'foreign-memaccess' into foreign-memaccess-doc2
 - Misc javadoc fixes
 - Fix javadoc for close()
 - Clarify javadoc w.r.t close and aliasing of existing memory sources.

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

Changes: https://git.openjdk.java.net/panama-foreign/pull/211/files
 Webrev: https://webrevs.openjdk.java.net/panama-foreign/211/webrev.03
  Stats: 144 lines in 4 files changed: 66 ins; 61 del; 17 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