Summary

Specify exactly which index values are valid arguments for Linker.Option.firstVariadicArg

Problem

The linker option returned by the Linker.Option.firstVariadicArg method is used when linking variadic functions.

However, it's currently not well specified which index values, a parameter of this method, are valid. Specifically, it might be surprising that an index value equal to the number of argument layouts of the function descriptor used in the same linkage request is valid. (this indicates a variadic function to which no variadic arguments are passed).

Solution

Improve the specification of the Linker.Option.firstVariadicArg method, to make it clear which index values are valid.

Specification

The javadoc of the firstVariadicArg method is updated, and a small note is also added to the section on variadic functions in the Linker class javadoc:

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 f374755e193a..3af21dd56c23 100644
--- a/src/java.base/share/classes/java/lang/foreign/Linker.java
+++ b/src/java.base/share/classes/java/lang/foreign/Linker.java
@@ -416,8 +416,8 @@
  * The native linker only supports linking the specialized form of a variadic function. A variadic function in its specialized
  * form can be linked using a function descriptor describing the specialized form. Additionally, the
  * {@link Linker.Option#firstVariadicArg(int)} linker option must be provided to indicate the first variadic parameter in
- * the parameter list. The corresponding argument layout, and all following argument layouts in the specialized function
- * descriptor, are called <em>variadic argument layouts</em>. For a prototype-less function, the index passed to
+ * the parameter list. The corresponding argument layout (if any), and all following argument layouts in the specialized
+ * function descriptor, are called <em>variadic argument layouts</em>. For a prototype-less function, the index passed to
  * {@link Linker.Option#firstVariadicArg(int)} should always be {@code 0}.
  * <p>
  * The native linker will reject an attempt to link a specialized function descriptor with any variadic argument layouts
@@ -644,8 +644,23 @@ sealed interface Option
             permits LinkerOptions.LinkerOptionImpl {

         /**
-         * {@return a linker option used to denote the index of the first variadic argument layout in the
-         *          function descriptor associated with a downcall linkage request}
+         * {@return a linker option used to denote the index indicating the start of the variadic arguments passed to the
+         *          function described by the function descriptor associated with a downcall linkage request}
+         * <p>
+         * The {@code index} value must conform to {@code 0 <= index <= N}, where {@code N} is the number of argument
+         * layouts of the function descriptor used in conjunction with this linker option. When the {@code index} is:
+         * <ul>
+         * <li>{@code 0}, all arguments passed to the function are passed as variadic arguments</li>
+         * <li>{@code N}, none of the arguments passed to the function are passed as variadic arguments</li>
+         * <li>{@code n}, where {@code 0 < m < N}, the arguments {@code m..N} are passed as variadic arguments</li>
+         * </ul>
+         * It is important to always use this linker option when linking a <a href=Linker.html#variadic-funcs>variadic
+         * function</a>, even if no variadic argument is passed (the second case in the list
+         * above), as this might still affect the calling convention on certain platforms.
+         *
+         * @implNote The index value is validated when making a linkage request, which is when the function descriptor
+         *           against which the index is validated is available.
+         *
          * @param index the index of the first variadic argument layout in the function descriptor associated
          *              with a downcall linkage request.
          */