RFR: 8310405: Linker.Option.firstVariadicArg should specify which index values are valid

[Maurizio Cimadamore]

On Tue, 20 Jun 2023 14:21:26 GMT, Jorn Vernee <jvernee at openjdk.org> wrote:

> Improve the specification of `Linker.Option.firstVariadicArg`, by specifying more clearly which index values are valid.

src/java.base/share/classes/java/lang/foreign/Linker.java line 650:

> 648:          *          function descriptor associated with a downcall linkage request}
> 649:          * <p>
> 650:          * The {@code index} value must be greater than zero, and less than or equal to the number of argument layouts

Why > 0 and not >= 0? If the list of argument layout is empty, wouldn't the first vararg be in position 0? E.g. a call to a function `m(...)` with _no_ actual arguments?

src/java.base/share/classes/java/lang/foreign/Linker.java line 652:

> 650:          * The {@code index} value must be greater than zero, and less than or equal to the number of argument layouts
> 651:          * of the function descriptor that is used in the same linkage request as this option. When the {@code index} is
> 652:          * equal to the number of argument layouts in the descriptor, it indicates a variadic function to which zero

This sentence is not clear. If index == num layouts then it means *all* arguments are variadic?

src/java.base/share/classes/java/lang/foreign/Linker.java line 659:

> 657:          * against which the index is validated is available.
> 658:          *
> 659:          * @param index the index of the first variadic argument layout in the function descriptor associated

IMHO this description is still confusing because it speaks about an index into the function descriptor argument layouts - which this thing is not.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/14565#discussion_r1235980081
PR Review Comment: https://git.openjdk.org/jdk/pull/14565#discussion_r1235981064
PR Review Comment: https://git.openjdk.org/jdk/pull/14565#discussion_r1235981781