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

[Jorn Vernee]

On Tue, 20 Jun 2023 22:54:47 GMT, Maurizio Cimadamore <mcimadamore 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 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?

index == 0 would mean all arguments are variadic. index == num layouts means none. (just like `"abcd".substring(4)` returns an empty string).

> 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.

Right, will polish this some more as well.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/14565#discussion_r1236016752
PR Review Comment: https://git.openjdk.org/jdk/pull/14565#discussion_r1236017428