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

[David Holmes]

On Tue, 24 Sep 2024 14:56:19 GMT, Maurizio Cimadamore <mcimadamore at openjdk.org> wrote:

>> 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:
> 
>   Fix paths to links

Hmm seems github got confused and some of my comments last week did already get pushed through. Probably best to clearly state where I currently stand:

1. Now that I've seen how a restricted method gets marked up in the javadoc with the very prominent text and link to the restricted-methods page, I think that addresses my concern about each restricted method documenting what happens if there is no caller.
2. I do think there should be some description as to why a given method is declared "restricted", as it may not be obvious. But I will agree with Alan that this can addressed separately as needed.
3. I will just note that the description for this issue  is "Clarify handling of restricted and caller-sensitive methods" but there is nothing in the proposed changes that relate to CS methods, and I think we have agreed that any documentation that may be lacking for pre-existing CS methods should also be handled outside this PR.

Thanks

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

PR Comment: https://git.openjdk.org/jdk/pull/21067#issuecomment-2387646586