[foreign-memaccess+abi] RFR: Improve ResourceScope javadoc

[Maurizio Cimadamore]

Chris and I had some discussions around the new `ResourceScope` API, and realized that the toplevel javadoc doesn't make it easy for developers to grasp all the various dimensions of resource scopes.
This is mostly caused by the fact that the concept of implicit closure is used to refer to _all_ scopes that support some form of GC-backed closure - and this brings confusion, as we have added the concept of "implicit" scopes to denote those scopes that *cannot* be closed explicitly.

I have rewritten the javadoc to talk about explicit and implicit scopes; we now say, in the section on explicit scopes, that explicit scopes can sometimes be associated with a Cleaner, but it is now clearer that that's mostly a fallback option.

When working on this, I think that we should probably make `ResourceScope::acquire` fail for implicit scope - either return null or throw. In other words, while acquiring handles makes sense to prevent deterministic deallocation, it seems like it doesn't make a lot of sense to prevent implicit deallocation (we already have reachability fences for this). What the implementation does right now permanently capture the scope instance in a handle instance, so the original implicit scope will never be closed as long as handles are reachable, even after close. In other words, having an handle that can be closed doesn't make sense for implicit scopes, since `Handle::close` doesn't do anything intersting in that case (or is not sufficient).

Any thoughts?

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

Commit messages:
 - Improve ResourceScope javadoc

Changes: https://git.openjdk.java.net/panama-foreign/pull/510/files
 Webrev: https://webrevs.openjdk.java.net/?repo=panama-foreign&pr=510&range=00
  Stats: 43 lines in 1 file changed: 11 ins; 7 del; 25 mod
  Patch: https://git.openjdk.java.net/panama-foreign/pull/510.diff
  Fetch: git fetch https://git.openjdk.java.net/panama-foreign pull/510/head:pull/510

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