Summary

Better specify where the additional MemorySegment parameter appears in the parameter list when linking a downcall handle using the captureCallState linker option.

Problem

The place where the additional MemorySegment parameter appears is specified in the javadoc of the Linker.Option::captureCallState method already, but not in the javadoc of the CaptureCallState class itself. So, it might be missed by someone reading the docs.

Furthermore, it doesn't specify the placing of the parameter in relation to the optional SegmentAllocator parameter which can also appear when a struct is returned by-value.

Solution

Specify where the additional parameter appears in javadoc of the CaptureCallState class, as well as specifying the parameter position in relation to the optional SegmentAllocator paramter.

Specification

diff --git a/src/java.base/share/classes/java/lang/foreign/Linker.java b/src/java.base/share/classes/java/lang/foreign/Linker.java
index e3af69954a8..12ba7f6ce5f 100644
--- a/src/java.base/share/classes/java/lang/foreign/Linker.java
+++ b/src/java.base/share/classes/java/lang/foreign/Linker.java
@@ -303,8 +303,8 @@ static Option firstVariadicArg(int index) {
          *          before it can be overwritten by the Java runtime, or read through conventional means}
          * <p>
          * A downcall method handle linked with this option will feature an additional {@link MemorySegment}
-         * parameter directly following the target address parameter. This memory segment must be a
-         * native segment into which the captured state is written.
+         * parameter directly following the target address, and optional {@link SegmentAllocator} parameters.
+         * This memory segment must be a native segment into which the captured state is written.
          *
          * @param capturedState the names of the values to save.
          * @see CaptureCallState#supported()
@@ -323,6 +323,10 @@ static CaptureCallState captureCallState(String... capturedState) {
          * <p>
          * Execution state is captured by a downcall method handle on invocation, by writing it
          * to a native segment provided by the user to the downcall method handle.
+         * For this purpose, a downcall method handle linked with the {@link #captureCallState(String[])}
+         * option will feature an additional {@link MemorySegment} parameter directly
+         * following the target address, and optional {@link SegmentAllocator} parameters.
+         * This parameter represents the native segment into which the captured state is written.
          * <p>
          * The native segment should have the layout {@linkplain CaptureCallState#layout associated}
          * with the particular {@code CaptureCallState} instance used to link the downcall handle.