RFR: 8338596: Clarify handling of restricted and caller-sensitive methods [v3]

[Maurizio Cimadamore]

> This PR moves the section on restricted methods from the the javadoc of `java.lang.foreign` package into a standalone static [javadoc page](https://cr.openjdk.org/~mcimadamore/jdk/restricted_javadoc_section/docs/api/java.base/java/lang/foreign/doc-files/RestrictedMethods.html).
> 
> This is because, after [JEP 472](https://openjdk.org/jeps/472), we now have restricted methods *outside* the foreign package, namely `System::loadLibrary`, `Runtime::loadLibrary` (and related methods). And, even before, we also had a restricted method in `ModuleLayer.Controller`.
> 
> The new static page contains some guidance of what happens when a restricted method is called when there's no Java frame on the stack (this can happen e.g. when upcalling into a restricted method from a native thread not known to the JVM) - that is, the call is treated as originating from an unnamed module.
> 
> The static page is linked from the restricted method banner in a restricted method javadoc. Here's an [example](https://cr.openjdk.org/~mcimadamore/jdk/restricted_javadoc_section/docs/api/java.base/java/lang/foreign/Linker.html#downcallHandle(java.lang.foreign.MemorySegment,java.lang.foreign.FunctionDescriptor,java.lang.foreign.Linker.Option...)).

Maurizio Cimadamore has updated the pull request incrementally with one additional commit since the last revision:

  Update src/java.base/share/classes/java/lang/doc-files/RestrictedMethods.html
  
  Co-authored-by: Jorn Vernee <JornVernee at users.noreply.github.com>

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

Changes:
  - all: https://git.openjdk.org/jdk/pull/21067/files
  - new: https://git.openjdk.org/jdk/pull/21067/files/0d7d0f9b..effefb50

Webrevs:
 - full: https://webrevs.openjdk.org/?repo=jdk&pr=21067&range=02
 - incr: https://webrevs.openjdk.org/?repo=jdk&pr=21067&range=01-02

  Stats: 1 line in 1 file changed: 0 ins; 0 del; 1 mod
  Patch: https://git.openjdk.org/jdk/pull/21067.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/21067/head:pull/21067

PR: https://git.openjdk.org/jdk/pull/21067