[foreign-memaccess+abi] RFR: 8312059: Clarify the documention for variadic functions [v2]

[Jorn Vernee]

On Fri, 14 Jul 2023 17:15:22 GMT, Maurizio Cimadamore <mcimadamore at openjdk.org> wrote:

>> Jorn Vernee has updated the pull request incrementally with one additional commit since the last revision:
>> 
>>   Update src/java.base/share/classes/java/lang/foreign/Linker.java
>>   
>>   Co-authored-by: Maurizio Cimadamore <54672762+mcimadamore at users.noreply.github.com>
>
> src/java.base/share/classes/java/lang/foreign/Linker.java line 424:
> 
>> 422:  * whereby the signed-ness of the source type corresponds to the signed-ness of the promoted type. The complete process
>> 423:  * of default argument promotion is described in the C specification. In effect these promotions place limits on the
>> 424:  * types that can be used to replace the {@code ...}, as the variadic parameters of the specialized form will always
> 
> specialized form -> specialized function? (this was there even before, but I'm not sure "form" is too clear given previous terminology)

Note that we use 'specialized form' in the following paragraph as well. I think it's more accurate than specialized function though, since it's the 'specialized form' of a variadic function, rather than a separate specialized function.

> src/java.base/share/classes/java/lang/foreign/Linker.java line 433:
> 
>> 431:  * function descriptor, are called <em>variadic argument layouts</em>.
>> 432:  * <p>
>> 433:  * The native linker does not automatically perform default argument promotions, since it would be ambiguous whether sign
> 
> I think we should drop the "since it would be ambiguous...". Here we should stress how things work, and less why they are the way they are (e.g. the signedness ambiguity might be lifted if we had different primitive types).

Ok, sounds good

> src/java.base/share/classes/java/lang/foreign/Linker.java line 436:
> 
>> 434:  * extension should take place. However, since passing an argument of a non-promoted type as a variadic argument is not
>> 435:  * supported in C, the native linker will reject an attempt to link a specialized function descriptor with any variadic
>> 436:  * argument layouts corresponding to a non-promoted C type. Since the size of the C {@code int} type is platform-specific,
> 
> This is slightly imprecise - although I know what you mean - it does seem to imply that if I pass a struct layout it will be rejected.

I thought saying "non-promoted" would be easier to understand than "a type that would undergo default argument promotion in C"

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

PR Review Comment: https://git.openjdk.org/panama-foreign/pull/846#discussion_r1263980208
PR Review Comment: https://git.openjdk.org/panama-foreign/pull/846#discussion_r1263980348
PR Review Comment: https://git.openjdk.org/panama-foreign/pull/846#discussion_r1263977092