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

[Alan Bateman]

On Thu, 19 Sep 2024 14:08:37 GMT, Maurizio Cimadamore <mcimadamore at openjdk.org> wrote:

>> Maurizio Cimadamore has updated the pull request incrementally with one additional commit since the last revision:
>> 
>>   Move restricted method page to `java.lang`
>>   Update restricted method page
>
> src/java.base/share/classes/java/lang/doc-files/RestrictedMethods.html line 41:
> 
>> 39:     done either via implementation-specific command line options or programmatically, e.g.
>> 40:     by calling <a href="../../ModuleLayer.Controller.html#enableNativeAccess(java.lang.Module)"><code>ModuleLayer.Controller.enableNativeAccess(java.lang.Module)</code></a>.</p>
>> 41: <p>When a restricted method is invoked by <a href="../../../../specs/jni/index.html">JNI code</a>,
> 
> IMHO, having this text here is better than copy and paste a similar version of this text in 14 (!!) places. That's why we added the `@Restricted` annotation, to make sure that uniform javadoc is generated for all restricted methods.

At some point we may have to re-visit the word "access". All restricted methods are accessible (public methods in  public classes in exported packages) as need to more clearly distinguish this from the native or restricted operation the method performs.  Okay for now as this PR is mostly moving text.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/21067#discussion_r1770954535