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

[Maurizio Cimadamore]

On Thu, 1 Jun 2023 21:09:12 GMT, Maurizio Cimadamore <mcimadamore at openjdk.org> wrote:

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

I'll replace "if" with "iff". I think to address your comment on linker options affecting what's supported, we can add a paragraph in that sense (but I think I'd like to do that after we fix https://git.openjdk.org/jdk/pull/14225, so that I can add a link to somewhere concrete.

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

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