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

[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).

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

Commit messages:
 - 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.00
  Issue: https://bugs.openjdk.java.net/browse/JDK-8247924
  Stats: 160 lines in 4 files changed: 76 ins; 61 del; 23 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