8319323: FFM: Harmonize the @throws tags in the javadocs

Reviewed-by: jvernee

src/java.base/share/classes/java/lang/foreign/AddressLayout.java

@@ -101,7 +101,7 @@ public sealed interface AddressLayout extends ValueLayout permits ValueLayouts.O
      *
      * @param layout the target layout.
      * @return an address layout with same characteristics as this layout, but with the provided target layout.
-     * @throws IllegalCallerException If the caller is in a module that does not have native access enabled.
+     * @throws IllegalCallerException If the caller is in a module that does not have native access enabled
      * @see #targetLayout()
      */
     @CallerSensitive

src/java.base/share/classes/java/lang/foreign/Arena.java

@@ -260,11 +260,11 @@ static Arena ofShared() {
      * @param byteSize the size (in bytes) of the off-heap region of memory backing the native memory segment.
      * @param byteAlignment the alignment constraint (in bytes) of the off-heap region of memory backing the native memory segment.
      * @return a new native memory segment.
-     * @throws IllegalArgumentException if {@code bytesSize < 0}, {@code byteAlignment <= 0}, or if {@code byteAlignment}
-     * is not a power of 2.
-     * @throws IllegalStateException if this arena has already been {@linkplain #close() closed}.
+     * @throws IllegalArgumentException if {@code bytesSize < 0}, {@code byteAlignment <= 0},
+     *         or if {@code byteAlignment} is not a power of 2
+     * @throws IllegalStateException if this arena has already been {@linkplain #close() closed}
      * @throws WrongThreadException if this arena is confined, and this method is called from a thread
-     * other than the arena's owner thread.
+     *         other than the arena's owner thread
      */
     @Override
     MemorySegment allocate(long byteSize, long byteAlignment);
@@ -289,12 +289,12 @@ static Arena ofShared() {
      *
      * @see Scope#isAlive()
      *
-     * @throws IllegalStateException if the arena has already been closed.
+     * @throws IllegalStateException if the arena has already been closed
      * @throws IllegalStateException if a segment associated with this arena is being accessed concurrently, e.g.
-     * by a {@linkplain Linker#downcallHandle(FunctionDescriptor, Linker.Option...) downcall method handle}.
+     *         by a {@linkplain Linker#downcallHandle(FunctionDescriptor, Linker.Option...) downcall method handle}
      * @throws WrongThreadException if this arena is confined, and this method is called from a thread
-     * other than the arena's owner thread.
-     * @throws UnsupportedOperationException if this arena cannot be closed explicitly.
+     *         other than the arena's owner thread
+     * @throws UnsupportedOperationException if this arena cannot be closed explicitly
      */
     @Override
     void close();

src/java.base/share/classes/java/lang/foreign/FunctionDescriptor.java

@@ -61,7 +61,7 @@ public sealed interface FunctionDescriptor permits FunctionDescriptorImpl {
      * Returns a function descriptor with the given argument layouts appended to the argument layouts
      * of this function descriptor.
      * @param addedLayouts the argument layouts to append.
-     * @throws IllegalArgumentException if one of the layouts in {@code addedLayouts} is a padding layout.
+     * @throws IllegalArgumentException if one of the layouts in {@code addedLayouts} is a padding layout
      * @return a new function descriptor, with the provided additional argument layouts.
      */
     FunctionDescriptor appendArgumentLayouts(MemoryLayout... addedLayouts);
@@ -72,15 +72,15 @@ public sealed interface FunctionDescriptor permits FunctionDescriptorImpl {
      * @param index the index at which to insert the arguments
      * @param addedLayouts the argument layouts to insert at given index.
      * @return a new function descriptor, with the provided additional argument layouts.
-     * @throws IllegalArgumentException if one of the layouts in {@code addedLayouts} is a padding layout.
-     * @throws IllegalArgumentException if {@code index < 0 || index > argumentLayouts().size()}.
+     * @throws IllegalArgumentException if one of the layouts in {@code addedLayouts} is a padding layout
+     * @throws IllegalArgumentException if {@code index < 0 || index > argumentLayouts().size()}
      */
     FunctionDescriptor insertArgumentLayouts(int index, MemoryLayout... addedLayouts);
 
     /**
      * Returns a function descriptor with the provided return layout.
      * @param newReturn the new return layout.
-     * @throws IllegalArgumentException if {@code newReturn} is a padding layout.
+     * @throws IllegalArgumentException if {@code newReturn} is a padding layout
      * @return a new function descriptor, with the provided return layout.
      */
     FunctionDescriptor changeReturnLayout(MemoryLayout newReturn);
@@ -110,8 +110,8 @@ public sealed interface FunctionDescriptor permits FunctionDescriptorImpl {
      * Creates a function descriptor with the given return and argument layouts.
      * @param resLayout the return layout.
      * @param argLayouts the argument layouts.
-     * @throws IllegalArgumentException if {@code resLayout} is a padding layout.
-     * @throws IllegalArgumentException if one of the layouts in {@code argLayouts} is a padding layout.
+     * @throws IllegalArgumentException if {@code resLayout} is a padding layout
+     * @throws IllegalArgumentException if one of the layouts in {@code argLayouts} is a padding layout
      * @return a new function descriptor with the provided return and argument layouts.
      */
     static FunctionDescriptor of(MemoryLayout resLayout, MemoryLayout... argLayouts) {
@@ -124,7 +124,7 @@ static FunctionDescriptor of(MemoryLayout resLayout, MemoryLayout... argLayouts)
      * Creates a function descriptor with the given argument layouts and no return layout.  This is useful to model functions
      * that return no values.
      * @param argLayouts the argument layouts.
-     * @throws IllegalArgumentException if one of the layouts in {@code argLayouts} is a padding layout.
+     * @throws IllegalArgumentException if one of the layouts in {@code argLayouts} is a padding layout
      * @return a new function descriptor with the provided argument layouts.
      */
     static FunctionDescriptor ofVoid(MemoryLayout... argLayouts) {

src/java.base/share/classes/java/lang/foreign/GroupLayout.java

@@ -65,8 +65,8 @@ public sealed interface GroupLayout extends MemoryLayout permits StructLayout, U
     /**
      * {@inheritDoc}
      * @throws IllegalArgumentException {@inheritDoc}
-     * @throws IllegalArgumentException if {@code byteAlignment} is less than {@code M}, where {@code M} is the maximum alignment
-     * constraint in any of the member layouts associated with this group layout.
+     * @throws IllegalArgumentException if {@code byteAlignment} is less than {@code M}, where {@code M} is
+     *         the maximum alignment constraint in any of the member layouts associated with this group layout
      */
     @Override
     GroupLayout withByteAlignment(long byteAlignment);

src/java.base/share/classes/java/lang/foreign/Linker.java

@@ -525,10 +525,10 @@ static Linker nativeLinker() {
      * @param function the function descriptor of the target foreign function.
      * @param options  the linker options associated with this linkage request.
      * @return a downcall method handle.
-     * @throws IllegalArgumentException if the provided function descriptor is not supported by this linker.
-     * @throws IllegalArgumentException if {@code !address.isNative()}, or if {@code address.equals(MemorySegment.NULL)}.
-     * @throws IllegalArgumentException if an invalid combination of linker options is given.
-     * @throws IllegalCallerException If the caller is in a module that does not have native access enabled.
+     * @throws IllegalArgumentException if the provided function descriptor is not supported by this linker
+     * @throws IllegalArgumentException if {@code !address.isNative()}, or if {@code address.equals(MemorySegment.NULL)}
+     * @throws IllegalArgumentException if an invalid combination of linker options is given
+     * @throws IllegalCallerException If the caller is in a module that does not have native access enabled
      *
      * @see SymbolLookup
      */
@@ -575,9 +575,9 @@ static Linker nativeLinker() {
      * @param function the function descriptor of the target foreign function.
      * @param options  the linker options associated with this linkage request.
      * @return a downcall method handle.
-     * @throws IllegalArgumentException if the provided function descriptor is not supported by this linker.
-     * @throws IllegalArgumentException if an invalid combination of linker options is given.
-     * @throws IllegalCallerException If the caller is in a module that does not have native access enabled.
+     * @throws IllegalArgumentException if the provided function descriptor is not supported by this linker
+     * @throws IllegalArgumentException if an invalid combination of linker options is given
+     * @throws IllegalCallerException If the caller is in a module that does not have native access enabled
      */
     @CallerSensitive
     @Restricted
@@ -610,14 +610,14 @@ static Linker nativeLinker() {
      * @param arena the arena associated with the returned upcall stub segment.
      * @param options  the linker options associated with this linkage request.
      * @return a zero-length segment whose address is the address of the upcall stub.
-     * @throws IllegalArgumentException if the provided function descriptor is not supported by this linker.
+     * @throws IllegalArgumentException if the provided function descriptor is not supported by this linker
      * @throws IllegalArgumentException if the type of {@code target} is incompatible with the
-     * type {@linkplain FunctionDescriptor#toMethodType() derived} from {@code function}.
-     * @throws IllegalArgumentException if it is determined that the target method handle can throw an exception.
+     *         type {@linkplain FunctionDescriptor#toMethodType() derived} from {@code function}
+     * @throws IllegalArgumentException if it is determined that the target method handle can throw an exception
      * @throws IllegalStateException if {@code arena.scope().isAlive() == false}
      * @throws WrongThreadException if {@code arena} is a confined arena, and this method is called from a
-     * thread {@code T}, other than the arena's owner thread.
-     * @throws IllegalCallerException If the caller is in a module that does not have native access enabled.
+     *         thread {@code T}, other than the arena's owner thread
+     * @throws IllegalCallerException If the caller is in a module that does not have native access enabled
      */
     @CallerSensitive
     @Restricted
@@ -726,7 +726,7 @@ static Option firstVariadicArg(int index) {
          *
          * @param capturedState the names of the values to save.
          * @throws IllegalArgumentException if at least one of the provided {@code capturedState} names
-         *                                  is unsupported on the current platform.
+         *         is unsupported on the current platform
          * @see #captureStateLayout()
          */
         static Option captureCallState(String... capturedState) {