8278607: Misc issues in foreign API javadoc

Reviewed-by: sundar

Author: mcimadamore

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

@@ -55,7 +55,7 @@
  * {@linkplain #downcallHandle(FunctionDescriptor) Linking a foreign function} is a process which requires a function descriptor,
  * a set of memory layouts which, together, specify the signature of the foreign function to be linked, and returns,
  * when complete, a downcall method handle, that is, a method handle that can be used to invoke the target native function.
- * The Java {@link java.lang.invoke.MethodType method type} associated with the returned method handle is
+ * The Java {@linkplain java.lang.invoke.MethodType method type} associated with the returned method handle is
  * {@linkplain #downcallType(FunctionDescriptor) derived} from the argument and return layouts in the function descriptor.
  * More specifically, given each layout {@code L} in the function descriptor, a corresponding carrier {@code C} is inferred,
  * as described below:
@@ -69,7 +69,8 @@
  * <li>or, if {@code L} is a {@link GroupLayout}, then {@code C} is set to {@code MemorySegment.class}</li>
  * </ul>
  * <p>
- * The downcall method handle type, derived as above, might be decorated by additional leading parameters:
+ * The downcall method handle type, derived as above, might be decorated by additional leading parameters,
+ * in the given order if both are present:
  * <ul>
  * <li>If the downcall method handle is created {@linkplain #downcallHandle(FunctionDescriptor) without specifying a native symbol},
  * the downcall method handle type features a leading parameter of type {@link NativeSymbol}, from which the
@@ -91,7 +92,7 @@
  * handle and a function descriptor; in this case, the set of memory layouts in the function descriptor
  * specify the signature of the function pointer associated with the upcall stub.
  * <p>
- * The type of the provided method handle has to match the Java {@link java.lang.invoke.MethodType method type}
+ * The type of the provided method handle has to match the Java {@linkplain java.lang.invoke.MethodType method type}
  * associated with the upcall stub, which is derived from the argument and return layouts in the function descriptor.
  * More specifically, given each layout {@code L} in the function descriptor, a corresponding carrier {@code C} is inferred, as described below:
  * <ul>
@@ -109,7 +110,7 @@
  *
  * <h2>System lookup</h2>
  *
- * This class implements the {@link SymbolLookup} interface; as such clients can {@linkplain #lookup(String) lookup} symbols
+ * This class implements the {@link SymbolLookup} interface; as such clients can {@linkplain #lookup(String) look up} symbols
  * in the standard libraries associated with this linker. The set of symbols available for lookup is unspecified,
  * as it depends on the platform and on the operating system.
  *
@@ -163,7 +164,7 @@ static CLinker systemCLinker() {
  }
 
  /**
- * Lookup a symbol in the standard libraries associated with this linker.
+ * Look up a symbol in the standard libraries associated with this linker.
  * The set of symbols available for lookup is unspecified, as it depends on the platform and on the operating system.
  * @return a symbol in the standard libraries associated with this linker.
  */

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

@@ -29,14 +29,16 @@
 import jdk.internal.foreign.MemoryAddressImpl;
 import jdk.internal.reflect.CallerSensitive;
 
+import java.lang.invoke.MethodHandle;
 import java.nio.ByteOrder;
 
 /**
- * A memory address models a reference into a memory location. Memory addresses are typically obtained in three ways:
+ * A memory address models a reference into a memory location. Memory addresses are typically obtained in one of the following ways:
  * <ul>
  * <li>By calling {@link Addressable#address()} on an instance of type {@link Addressable} (e.g. a memory segment);</li>
  * <li>By invoking a {@linkplain CLinker#downcallHandle(FunctionDescriptor) downcall method handle} which returns a pointer;</li>
  * <li>By reading an address from memory, e.g. via {@link MemorySegment#get(ValueLayout.OfAddress, long)}.</li>
+ * <li>By the invocation of an {@linkplain CLinker#upcallStub(MethodHandle, FunctionDescriptor, ResourceScope) upcall stub} which accepts a pointer.
  * </ul>
  * A memory address is backed by a raw machine pointer, expressed as a {@linkplain #toRawLongValue() long value}.
  *

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

@@ -56,7 +56,7 @@
  * A memory segment models a contiguous region of memory. A memory segment is associated with both spatial
  * and temporal bounds (e.g. a {@link ResourceScope}). Spatial bounds ensure that memory access operations on a memory segment cannot affect a memory location
  * which falls <em>outside</em> the boundaries of the memory segment being accessed. Temporal bounds ensure that memory access
- * operations on a segment cannot occur after the resource scope associated with a memory segment has been closed (see {@link ResourceScope#close()}).
+ * operations on a segment cannot occur <em>after</em> the resource scope associated with a memory segment has been closed (see {@link ResourceScope#close()}).
  * <p>
  * All implementations of this interface must be <a href="{@docRoot}/java.base/java/lang/doc-files/ValueBased.html">value-based</a>;
  * programmers should treat instances that are {@linkplain Object#equals(Object) equal} as interchangeable and should not
@@ -157,7 +157,7 @@
  * scope, it can only be accessed by the thread which owns the scope.
  * <p>
  * Heap and buffer segments are always associated with a <em>global</em>, shared scope. This scope cannot be closed,
- * and can be considered as <em>always alive</em>.
+ * and segments associated with it can be considered as <em>always alive</em>.
  *
  * <h2>Memory segment views</h2>
  *
@@ -217,11 +217,11 @@ public sealed interface MemorySegment extends Addressable permits AbstractMemory
  * The returned spliterator splits this segment according to the specified element layout; that is,
  * if the supplied layout has size N, then calling {@link Spliterator#trySplit()} will result in a spliterator serving
  * approximately {@code S/N/2} elements (depending on whether N is even or not), where {@code S} is the size of
- * this segment. As such, splitting is possible as long as {@code S/N >= 2}. The spliterator returns segments that feature the same
- * scope as this given segment.
+ * this segment. As such, splitting is possible as long as {@code S/N >= 2}. The spliterator returns segments that
+ * are associated with the same scope as this segment.
  * <p>
- * The returned spliterator effectively allows to slice this segment into disjoint sub-segments, which can then
- * be processed in parallel by multiple threads.
+ * The returned spliterator effectively allows to slice this segment into disjoint {@linkplain #asSlice(long, long) slices},
+ * which can then be processed in parallel by multiple threads.
  *
  * @param elementLayout the layout to be used for splitting.
  * @return the element spliterator for this segment
@@ -679,7 +679,7 @@ static MemorySegment ofByteBuffer(ByteBuffer bb) {
 
  /**
  * Creates a new array memory segment that models the memory associated with a given heap-allocated byte array.
- * The returned segment's resource scope is set to the {@linkplain ResourceScope#globalScope() global} resource scope.
+ * The returned segment is associated with the {@linkplain ResourceScope#globalScope() global} resource scope.
  *
  * @param arr the primitive array backing the array memory segment.
  * @return a new array memory segment.
@@ -690,7 +690,7 @@ static MemorySegment ofArray(byte[] arr) {
 
  /**
  * Creates a new array memory segment that models the memory associated with a given heap-allocated char array.
- * The returned segment's resource scope is set to the {@linkplain ResourceScope#globalScope() global} resource scope.
+ * The returned segment is associated with the {@linkplain ResourceScope#globalScope() global} resource scope.
  *
  * @param arr the primitive array backing the array memory segment.
  * @return a new array memory segment.
@@ -701,7 +701,7 @@ static MemorySegment ofArray(char[] arr) {
 
  /**
  * Creates a new array memory segment that models the memory associated with a given heap-allocated short array.
- * The returned segment's resource scope is set to the {@linkplain ResourceScope#globalScope() global} resource scope.
+ * The returned segment is associated with the {@linkplain ResourceScope#globalScope() global} resource scope.
  *
  * @param arr the primitive array backing the array memory segment.
  * @return a new array memory segment.
@@ -712,7 +712,7 @@ static MemorySegment ofArray(short[] arr) {
 
  /**
  * Creates a new array memory segment that models the memory associated with a given heap-allocated int array.
- * The returned segment's resource scope is set to the {@linkplain ResourceScope#globalScope() global} resource scope.
+ * The returned segment is associated with the {@linkplain ResourceScope#globalScope() global} resource scope.
  *
  * @param arr the primitive array backing the array memory segment.
  * @return a new array memory segment.
@@ -723,7 +723,7 @@ static MemorySegment ofArray(int[] arr) {
 
  /**
  * Creates a new array memory segment that models the memory associated with a given heap-allocated float array.
- * The returned segment's resource scope is set to the {@linkplain ResourceScope#globalScope() global} resource scope.
+ * The returned segment is associated with the {@linkplain ResourceScope#globalScope() global} resource scope.
  *
  * @param arr the primitive array backing the array memory segment.
  * @return a new array memory segment.
@@ -734,7 +734,7 @@ static MemorySegment ofArray(float[] arr) {
 
  /**
  * Creates a new array memory segment that models the memory associated with a given heap-allocated long array.
- * The returned segment's resource scope is set to the {@linkplain ResourceScope#globalScope() global} resource scope.
+ * The returned segment is associated with the {@linkplain ResourceScope#globalScope() global} resource scope.
  *
  * @param arr the primitive array backing the array memory segment.
  * @return a new array memory segment.
@@ -745,7 +745,7 @@ static MemorySegment ofArray(long[] arr) {
 
  /**
  * Creates a new array memory segment that models the memory associated with a given heap-allocated double array.
- * The returned segment's resource scope is set to the {@linkplain ResourceScope#globalScope() global} resource scope.
+ * The returned segment is associated with the {@linkplain ResourceScope#globalScope() global} resource scope.
  *
  * @param arr the primitive array backing the array memory segment.
  * @return a new array memory segment.

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

@@ -456,7 +456,6 @@ static SegmentAllocator nativeAllocator(ResourceScope scope) {
  * Returns a native allocator which allocates segments in independent {@linkplain ResourceScope#newImplicitScope() implicit scopes}.
  * Equivalent to (but likely more efficient than) the following code:
  * {@snippet lang=java :
- * ResourceScope scope = ...
  * SegmentAllocator implicitAllocator = (size, align) -> MemorySegment.allocateNative(size, align, ResourceScope.newImplicitScope());
  * }
  *

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

@@ -59,7 +59,8 @@
 sealed public interface VaList extends Addressable permits WinVaList, SysVVaList, LinuxAArch64VaList, MacOsAArch64VaList, SharedUtils.EmptyVaList {
 
  /**
- * Reads the next value as an {@code int} and advances this variable argument list's position.
+ * Reads the next value as an {@code int} and advances this variable argument list's position. The behavior of this
+ * method is equivalent to the C {@code va_arg} function.
  *
  * @param layout the layout of the value to be read.
  * @return the {@code int} value read from this variable argument list.
@@ -69,7 +70,8 @@ sealed public interface VaList extends Addressable permits WinVaList, SysVVaList
  int nextVarg(ValueLayout.OfInt layout);
 
  /**
- * Reads the next value as a {@code long} and advances this variable argument list's position.
+ * Reads the next value as a {@code long} and advances this variable argument list's position. The behavior of this
+ * method is equivalent to the C {@code va_arg} function.
  *
  * @param layout the layout of the value to be read.
  * @return the {@code long} value read from this variable argument list.
@@ -79,7 +81,8 @@ sealed public interface VaList extends Addressable permits WinVaList, SysVVaList
  long nextVarg(ValueLayout.OfLong layout);
 
  /**
- * Reads the next value as a {@code double} and advances this variable argument list's position.
+ * Reads the next value as a {@code double} and advances this variable argument list's position. The behavior of this
+ * method is equivalent to the C {@code va_arg} function.
  *
  * @param layout the layout of the value
  * @return the {@code double} value read from this variable argument list.
@@ -89,7 +92,8 @@ sealed public interface VaList extends Addressable permits WinVaList, SysVVaList
  double nextVarg(ValueLayout.OfDouble layout);
 
  /**
- * Reads the next value as a {@code MemoryAddress} and advances this variable argument list's position.
+ * Reads the next value as a {@code MemoryAddress} and advances this variable argument list's position. The behavior of this
+ * method is equivalent to the C {@code va_arg} function.
  *
  * @param layout the layout of the value to be read.
  * @return the {@code MemoryAddress} value read from this variable argument list.
@@ -99,7 +103,13 @@ sealed public interface VaList extends Addressable permits WinVaList, SysVVaList
  MemoryAddress nextVarg(ValueLayout.OfAddress layout);
 
  /**
- * Reads the next value as a {@code MemorySegment}, and advances this variable argument list's position.
+ * Reads the next value as a {@code MemorySegment}, and advances this variable argument list's position. The behavior of this
+ * method is equivalent to the C {@code va_arg} function. The provided group layout must correspond to a C struct or union
+ * type.
+ * <p>
+ * How the value is read in the returned segment is ABI-dependent: calling this method on a group layout
+ * with member layouts {@code L_1, L_2, ... L_n} is not guaranteed to be semantically equivalent to perform distinct
+ * calls to {@code nextVarg} for each of the layouts in {@code L_1, L_2, ... L_n}.
  * <p>
  * The memory segment returned by this method will be allocated using the given {@link SegmentAllocator}.
  *
@@ -129,9 +139,12 @@ sealed public interface VaList extends Addressable permits WinVaList, SysVVaList
 
  /**
  * Copies this variable argument list at its current position into a new variable argument list associated
- * with the same scope as this variable argument list. Copying is useful to
- * traverse the variable argument list elements, starting from the current position, without affecting the state
- * of the original variable argument list, essentially allowing the elements to be traversed multiple times.
+ * with the same scope as this variable argument list. The behavior of this method is equivalent to the C
+ * {@code va_copy} function.
+ * <p>
+ * Copying is useful to traverse the variable argument list elements, starting from the current position,
+ * without affecting the state of the original variable argument list, essentially allowing the elements to be
+ * traversed multiple times.
  *
  * @return a copy of this variable argument list.
  * @throws IllegalStateException if the scope associated with this variable argument list has been closed, or if access occurs from
@@ -187,8 +200,8 @@ static VaList ofAddress(MemoryAddress address, ResourceScope scope) {
  * of the underlying variable argument list.
  * @param scope scope the scope to be associated with the new variable arity list.
  * @return a new variable argument list.
- * @throws IllegalStateException if the scope associated with {@code allocator} has been already closed,
- * or if access occurs from a thread other than the thread owning that scope.
+ * @throws IllegalStateException if {@code scope} has been already closed, or if access occurs from a thread other
+ * than the thread owning {@code scope}.
  */
  static VaList make(Consumer<Builder> actions, ResourceScope scope) {
  Objects.requireNonNull(actions);

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

@@ -41,7 +41,7 @@
 
 /**
  * A value layout. A value layout is used to model the memory layout associated with values of basic data types, such as <em>integral</em> types
- * (either signed or unsigned) and <em>floating-point</em> types. Each value layout has a size, a {@linkplain ByteOrder byte order})
+ * (either signed or unsigned) and <em>floating-point</em> types. Each value layout has a size, an alignment, a {@linkplain ByteOrder byte order})
  * and a <em>carrier</em>, that is, the Java type that should be used when {@linkplain MemorySegment#get(OfInt, long) accessing}
  * a memory region using the value layout.
  * <p>