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

[Maurizio Cimadamore]

On Fri, 14 Jul 2023 17:51:57 GMT, Jorn Vernee <jvernee at openjdk.org> wrote:

>> This patch attempts to refine the javadoc for variadic functions further. Particularly, it tries to make it clearer that the layouts the native linker rejects are derived from the C specification. Instead of trying to say which layouts are reject, we say which C types are rejected, and then give a hint about how to map those C types into layouts, using `canonicalLayouts()`, which would tell a client which layouts are rejected.
>> 
>> Additionally, this patch removes the mentions of prototype-less functions, which are not considered variadic functions in C. It is also not clear whether arguments passed to such a function should be treated as variadic or not in the ABI (see linked issue). Finally the latest C standard, C23, prototype-less functions no longer exist, and a declaration of the form `void foo()` instead means the same as `void foo(void)`. For these reason, passing arguments to prototype-less functions will also not be supported (officially) by the linker. I wasn't sure about whether to add a specific note about that. I figured that just not saying they are supported, combined with the state of the latest C standard, would make this obvious enough (?).
>
> Jorn Vernee has updated the pull request incrementally with two additional commits 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>
>  - review comments

Marked as reviewed by mcimadamore (Committer).

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

> 437:  * platform-specific as well. As an example: on Linux/x64 the layouts corresponding to the C types {@code _Bool},
> 438:  * {@code (unsigned) char}, {@code (unsigned) short}, and {@code float} (among others), will be rejected by the linker.
> 439:  * The {@link #canonicalLayouts()} API can be used to find which layout corresponds to a particular C type.

Suggestion:

 * The {@link #canonicalLayouts()} method can be used to find which layout corresponds to a particular C type.

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

PR Review: https://git.openjdk.org/panama-foreign/pull/846#pullrequestreview-1530717849
PR Review Comment: https://git.openjdk.org/panama-foreign/pull/846#discussion_r1263989348