Add coarser-grained statements abut NPE handling at the class level.

Add test support for LibraryLookup.

src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/FunctionDescriptor.java

@@ -42,6 +42,9 @@
 /**
  * A function descriptor is made up of zero or more argument layouts and zero or one return layout. A function descriptor
  * is used to model the signature of foreign functions.
+ *
+ * <p> Unless otherwise specified, passing a {@code null} argument, or an array argument containing one or more {@code null}
+ * elements to a method in this class causes a {@link NullPointerException NullPointerException} to be thrown. </p>
  */
 public final class FunctionDescriptor implements Constable {
 
@@ -66,7 +69,6 @@ private FunctionDescriptor(MemoryLayout resLayout, Map<String, Constable> attrib
      *
      * @param name the attribute name.
      * @return the attribute with the given name (if it exists).
-     * @throws NullPointerException if {@code name == null}.
      */
     public Optional<Constable> attribute(String name) {
         Objects.requireNonNull(name);
@@ -90,7 +92,6 @@ public Stream<String> attributes() {
      * @param name the attribute name.
      * @param value the attribute value.
      * @return a new function descriptor which features the same attributes as this descriptor, plus the newly specified attribute.
-     * @throws NullPointerException if {@code name == null}.
      */
     public FunctionDescriptor withAttribute(String name, Constable value) {
         Objects.requireNonNull(name);
@@ -120,7 +121,6 @@ public List<MemoryLayout> argumentLayouts() {
      * @param resLayout the return layout.
      * @param argLayouts the argument layouts.
      * @return the new function descriptor.
-     * @throws NullPointerException if either {@code resLayout == null}, {@code argLayouts == null}, or any of the
      * layouts in {@code argLayouts} is null.
      */
     public static FunctionDescriptor of(MemoryLayout resLayout, MemoryLayout... argLayouts) {
@@ -134,7 +134,6 @@ public static FunctionDescriptor of(MemoryLayout resLayout, MemoryLayout... argL
      * Create a function descriptor with given argument layouts and no return layout.
      * @param argLayouts the argument layouts.
      * @return the new function descriptor.
-     * @throws NullPointerException if either {@code argLayouts == null}, or any of the
      * layouts in {@code argLayouts} is null.
      */
     public static FunctionDescriptor ofVoid(MemoryLayout... argLayouts) {
@@ -148,7 +147,6 @@ public static FunctionDescriptor ofVoid(MemoryLayout... argLayouts) {
      * of this function descriptor.
      * @param addedLayouts the argument layouts to append.
      * @return the new function descriptor.
-     * @throws NullPointerException if either {@code addedLayouts == null}, or any of the
      * layouts in {@code addedLayouts} is null.
      */
     public FunctionDescriptor withAppendedArgumentLayouts(MemoryLayout... addedLayouts) {
@@ -163,7 +161,6 @@ public FunctionDescriptor withAppendedArgumentLayouts(MemoryLayout... addedLayou
      * Create a new function descriptor with the given memory layout as the new return layout.
      * @param newReturn the new return layout.
      * @return the new function descriptor.
-     * @throws NullPointerException if {@code newReturn == null}.
      */
     public FunctionDescriptor withReturnLayout(MemoryLayout newReturn) {
         Objects.requireNonNull(newReturn);

src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/GroupLayout.java

@@ -52,6 +52,9 @@
  * {@code GroupLayout} may have unpredictable results and should be avoided.
  * The {@code equals} method should be used for comparisons.
  *
+ * <p> Unless otherwise specified, passing a {@code null} argument, or an array argument containing one or more {@code null}
+ * elements to a method in this class causes a {@link NullPointerException NullPointerException} to be thrown. </p>
+ *
  * @implSpec
  * This class is immutable and thread-safe.
  */

src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/LibraryLookup.java

@@ -56,6 +56,9 @@
  * <p>
  * To allow for a library to be unloaded, a client will have to discard any strong references it
  * maintains, directly, or indirectly to a lookup object associated with given library.
+ *
+ * <p> Unless otherwise specified, passing a {@code null} argument, or an array argument containing one or more {@code null}
+ * elements to a method in this class causes a {@link NullPointerException NullPointerException} to be thrown. </p>
  */
 public interface LibraryLookup {
 

src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/MappedMemorySegments.java

@@ -43,6 +43,9 @@
  * with the desired parameters; the returned address can be easily wrapped into a memory segment, using
  * {@link MemoryAddress#ofLong(long)} and {@link MemoryAddress#asSegmentRestricted(long, Runnable, Object)}.
  *
+ * <p> Unless otherwise specified, passing a {@code null} argument, or an array argument containing one or more {@code null}
+ * elements to a method in this class causes a {@link NullPointerException NullPointerException} to be thrown. </p>
+ *
  * @implNote
  * The behavior of some the methods in this class (see {@link #load(MemorySegment)}, {@link #unload(MemorySegment)} and
  * {@link #isLoaded(MemorySegment)}) is highly platform-dependent; as a result, calling these methods might
@@ -76,7 +79,6 @@ private MappedMemorySegments() {
      * and this method is called from a thread other than the segment's owner thread.
      * @throws UnsupportedOperationException if the given segment is not a mapped memory segment, e.g. if
      * {@code segment.isMapped() == false}.
-     * @throws NullPointerException if {@code segment == null}.
      */
     public static boolean isLoaded(MemorySegment segment) {
         return toMappedSegment(segment).isLoaded();
@@ -96,7 +98,6 @@ public static boolean isLoaded(MemorySegment segment) {
      * and this method is called from a thread other than the segment's owner thread.
      * @throws UnsupportedOperationException if the given segment is not a mapped memory segment, e.g. if
      * {@code segment.isMapped() == false}.
-     * @throws NullPointerException if {@code segment == null}.
      */
     public static void load(MemorySegment segment) {
         toMappedSegment(segment).load();
@@ -116,7 +117,6 @@ public static void load(MemorySegment segment) {
      * and this method is called from a thread other than the segment's owner thread.
      * @throws UnsupportedOperationException if the given segment is not a mapped memory segment, e.g. if
      * {@code segment.isMapped() == false}.
-     * @throws NullPointerException if {@code segment == null}.
      */
     public static void unload(MemorySegment segment) {
         toMappedSegment(segment).unload();
@@ -149,7 +149,6 @@ public static void unload(MemorySegment segment) {
      * and this method is called from a thread other than the segment's owner thread.
      * @throws UnsupportedOperationException if the given segment is not a mapped memory segment, e.g. if
      * {@code segment.isMapped() == false}.
-     * @throws NullPointerException if {@code segment == null}.
      */
     public static void force(MemorySegment segment) {
         toMappedSegment(segment).force();