On Tue, 24 Sep 2024 14:56:19 GMT, Maurizio Cimadamore <mcimadam...@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 The JavaDoc parts mostly look good, but a few details about how the doc file path is created can be improved. Since I'm more familiar with the code I could contribute the changes. Alternatively, I can help with any questions. src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/resources/standard.properties line 427: > 425: doclet.PreviewTrailingNote1=Programs can only use {0} when preview > features are enabled. > 426: doclet.PreviewTrailingNote2=Preview features may be removed in a future > release, or upgraded to permanent features of the Java platform. > 427: > doclet.Restricted.url={@docRoot}/java.base/java/lang/doc-files/RestrictedMethods.html There is no reason to add the path to the properties, as it will not be internationalized. The place to put this would be `jdk.javadoc.internal.doclets.toolkit.util.DocPaths`, but I would only define the file name `RestrictedMethods.html` there as the rest of the path can be resolved as a doc-file relative to the `java.lang` package. ------------- Changes requested by hannesw (Reviewer). PR Review: https://git.openjdk.org/jdk/pull/21067#pullrequestreview-2348525063 PR Review Comment: https://git.openjdk.org/jdk/pull/21067#discussion_r1787990067
