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

[Jorn Vernee]

On Thu, 1 Jun 2023 13:06:15 GMT, Alan Bateman <alanb 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/FunctionDescriptor.java line 127:
> 
>> 125:     /**
>> 126:      * Creates a function descriptor with the given argument layouts and no return layout.  This is useful to model functions
>> 127:      * which return no values.
> 
> I think I would use "that return" rather than "which return" here.

I [looked this up](https://www.grammarly.com/blog/which-vs-that/), and learned something (thanks!). 

"which" is used for optional clauses. It implies the sentence could be written as "This is useful to model functions (which, by the way, return no values)". i.e. it is optional information about functions. "that" is used to indicate we're talking about a particular kind of function (implying also that there are multiple kinds).

> src/java.base/share/classes/java/lang/foreign/SegmentAllocator.java line 325:
> 
>> 323:      * @return a segment for the newly allocated memory block.
>> 324:      * @throws IllegalArgumentException if {@code elementLayout.byteSize() * count} overflows.
>> 325:      * @throws IllegalArgumentException if {@code count < 0}.
> 
> Another case where the IAE descriptions should probably be combined.

I think having the different failure cases split up like this makes the doc easier to read. (IIRC we used to have everything combined in the past, but got the advice at some point to split things up into separate `@throws` clauses).

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

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