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

[Maurizio Cimadamore]

On Thu, 1 Jun 2023 13:16:44 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/SequenceLayout.java line 75:
> 
>> 73:      * @return a sequence layout with the same characteristics of this layout, but with the given element count.
>> 74:      * @throws IllegalArgumentException if {@code elementCount} is negative.
>> 75:      * @throws IllegalArgumentException if {@code elementLayout.bitSize() * elementCount} overflows.
> 
> Shouldn't the exception descriptions be combined to avoid IAE being listed twice in the generated javadoc?

I think @PaulSandoz  suggested this idiom in other places where the `@throws` clause was very hard to break up, so I thought that would have been preferrable than having a single para. But if there are strong opinions, I could tweak in different ways, perhaps with bullet lists (but that will require a lot of work).

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

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