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

[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 incremental
webrev excludes the unrelated changes brought in by the merge/rebase. The pull request contains six additional commits
since the last revision:

 - 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:
  - all: https://git.openjdk.java.net/panama-foreign/pull/211/files
  - new: https://git.openjdk.java.net/panama-foreign/pull/211/files/c09b1143..f7a7f60d

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

  Stats: 6520 lines in 339 files changed: 4193 ins; 1719 del; 608 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