RFR: 8308645: Javadoc of FFM API needs to be refreshed [v4]

[Maurizio Cimadamore]

On Thu, 1 Jun 2023 17:10:48 GMT, Jorn Vernee <jvernee at openjdk.org> wrote:

>> Maurizio Cimadamore has updated the pull request incrementally with one additional commit since the last revision:
>> 
>>   Fix wrong link in layout well-formedness doc
>
> src/java.base/share/classes/java/lang/foreign/Linker.java line 201:
> 
>> 199:  * <p>
>> 200:  * All native linker implementations operate on a subset of memory layouts. More formally, a layout {@code L}
>> 201:  * is supported by a native linker {@code NL} iff:
> 
> I think using `iff` (if-and-only-if) is incorrect here, since certain linkers might impose additional constraints. For instance, the fallback linker doesn't support union layouts. Also, we want to further restrict variadic argument layouts as well as part of https://github.com/openjdk/jdk/pull/14225
> 
> Maybe we could say that all layouts passed to a linker must _at least_ adhere to the following constraints.

I'll think about it - it's a bit problematic to specify in terms of "at least" because we need to be able to refer to "supported by NL" recursively in the text.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/14098#discussion_r1213683303