diff --git a/src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/Addressable.java b/src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/Addressable.java
index 39f61e76122..17d417bee51 100644
--- a/src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/Addressable.java
+++ b/src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/Addressable.java
@@ -40,8 +40,7 @@ package jdk.incubator.foreign;
public sealed interface Addressable permits MemorySegment, MemoryAddress, NativeSymbol, VaList {
/**
- * Returns the memory address associated with this addressable.
- * @return The memory address associated with this addressable.
+ * {@return the {@linkplain MemoryAddress memory address} associated with this addressable}
*/
MemoryAddress address();
}
diff --git a/src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/FunctionDescriptor.java b/src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/FunctionDescriptor.java
index 9c557ec9e9e..6bedfc4c16a 100644
--- a/src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/FunctionDescriptor.java
+++ b/src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/FunctionDescriptor.java
@@ -54,16 +54,14 @@ public sealed class FunctionDescriptor implements Constable permits FunctionDesc
}
/**
- * Returns the return layout associated with this function.
- * @return the return layout.
+ * {@return the return layout (if any) associated with this function descriptor}
*/
public Optional<MemoryLayout> returnLayout() {
return Optional.ofNullable(resLayout);
}
/**
- * Returns the argument layouts associated with this function.
- * @return the argument layouts.
+ * {@return the argument layouts associated with this function descriptor}.
*/
public List<MemoryLayout> argumentLayouts() {
return argLayouts;
@@ -166,8 +164,7 @@ public sealed class FunctionDescriptor implements Constable permits FunctionDesc
}
/**
- * Returns a string representation of this function descriptor.
- * @return a string representation of this function descriptor.
+ * {@return the string representation of this function descriptor}
*/
@Override
public String toString() {
@@ -201,8 +198,7 @@ public sealed class FunctionDescriptor implements Constable permits FunctionDesc
}
/**
- * Returns the hash code value for this function descriptor.
- * @return the hash code value for this function descriptor.
+ * {@return the hash code value for this function descriptor}
*/
@Override
public int hashCode() {
diff --git a/src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/GroupLayout.java b/src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/GroupLayout.java
index d08bb716ae8..6fc9baad7ff 100644
--- a/src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/GroupLayout.java
+++ b/src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/GroupLayout.java
@@ -133,18 +133,14 @@ public final class GroupLayout extends AbstractLayout implements MemoryLayout {
}
/**
- * Is this group layout a <em>struct</em>?
- *
- * @return true, if this group layout is a <em>struct</em>.
+ * {@return {@code true}, if this group layout is a <em>struct</em>}
*/
public boolean isStruct() {
return kind == Kind.STRUCT;
}
/**
- * Is this group layout a <em>union</em>?
- *
- * @return true, if this group layout is a <em>union</em>.
+ * {@return {@code true}, if this group layout is a <em>union</em>}
*/
public boolean isUnion() {
return kind == Kind.UNION;
diff --git a/src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/MemoryAddress.java b/src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/MemoryAddress.java
index 47a17799700..007464d1691 100644
--- a/src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/MemoryAddress.java
+++ b/src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/MemoryAddress.java
@@ -78,8 +78,7 @@ import java.nio.ByteOrder;
public sealed interface MemoryAddress extends Addressable permits MemoryAddressImpl {
/**
- * Returns the raw long value associated with this memory address.
- * @return The raw long value associated with this memory address.
+ * {@return the raw long value associated with this memory address}
*/
long toRawLongValue();
@@ -141,8 +140,7 @@ public sealed interface MemoryAddress extends Addressable permits MemoryAddressI
boolean equals(Object that);
/**
- * Returns the hash code value for this address.
- * @return the hash code value for this address.
+ * {@return the hash code value for this address}
*/
@Override
int hashCode();
diff --git a/src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/MemoryLayout.java b/src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/MemoryLayout.java
index fe0fb4e93f9..991897c367d 100644
--- a/src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/MemoryLayout.java
+++ b/src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/MemoryLayout.java
@@ -195,18 +195,15 @@ import java.util.stream.Stream;
public sealed interface MemoryLayout extends Constable permits AbstractLayout, SequenceLayout, GroupLayout, PaddingLayout, ValueLayout {
/**
- * Returns an {@link Optional} containing the nominal descriptor for this
+ * {@return an {@link Optional} containing the nominal descriptor for this
* layout, if one can be constructed, or an empty {@link Optional}
- * if one cannot be constructed.
- *
- * @return An {@link Optional} containing the resulting nominal descriptor,
- * or an empty {@link Optional} if one cannot be constructed.
+ * if one cannot be constructed}
*/
@Override
Optional<? extends DynamicConstantDesc<? extends MemoryLayout>> describeConstable();
/**
- * Does this layout have a specified size? A layout does not have a specified size if it is (or contains) a sequence layout whose
+ * Returns {@code true} if this layout has a specified size. A layout does not have a specified size if it is (or contains) a sequence layout whose
* size is unspecified (see {@link SequenceLayout#elementCount()}).
*
* Value layouts (see {@link ValueLayout}) and padding layouts (see {@link MemoryLayout#paddingLayout(long)})
@@ -217,26 +214,20 @@ public sealed interface MemoryLayout extends Constable permits AbstractLayout, S
boolean hasSize();
/**
- * Computes the layout size, in bits.
- *
- * @return the layout size, in bits.
+ * {@return the layout size, in bits}
* @throws UnsupportedOperationException if the layout is, or contains, a sequence layout with unspecified size (see {@link SequenceLayout}).
*/
long bitSize();
/**
- * Computes the layout size, in bytes.
- *
- * @return the layout size, in bytes.
+ * {@return the layout size, in bytes}
* @throws UnsupportedOperationException if the layout is, or contains, a sequence layout with unspecified size (see {@link SequenceLayout}),
* or if {@code bitSize()} is not a multiple of 8.
*/
long byteSize();
/**
- * Return the <em>name</em> (if any) associated with this layout.
- *
- * @return the layout <em>name</em> (if any).
+ * {@return the <em>name</em> (if any) associated with this layout}
* @see MemoryLayout#withName(String)
*/
Optional<String> name();
@@ -534,8 +525,7 @@ public sealed interface MemoryLayout extends Constable permits AbstractLayout, S
}
/**
- * Is this a {@linkplain #paddingLayout(long) padding layout} ?
- * @return true, if this layout is a padding layout.
+ * {@return true, if this layout is a padding layout}
*/
boolean isPadding();
@@ -651,16 +641,12 @@ public sealed interface MemoryLayout extends Constable permits AbstractLayout, S
boolean equals(Object that);
/**
- * Returns the hash code value for this layout.
- *
- * @return the hash code value for this layout.
+ * {@return the hash code value for this layout}
*/
int hashCode();
/**
- * Returns a string representation of this layout.
- *
- * @return a string representation of this layout.
+ * {@return the string representation of this layout}
*/
@Override
String toString();
diff --git a/src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/MemorySegment.java b/src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/MemorySegment.java
index 3d3401ef05b..a4508530734 100644
--- a/src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/MemorySegment.java
+++ b/src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/MemorySegment.java
@@ -250,11 +250,10 @@ boolean isAligned(MemorySegment segment, long offset, MemoryLayout layout) {
public sealed interface MemorySegment extends Addressable permits AbstractMemorySegmentImpl {
/**
- * The base memory address associated with this native memory segment.
+ * {@return the base memory address associated with this native memory segment}
* @throws UnsupportedOperationException if this segment is not a {@linkplain #isNative() native} segment.
* @throws IllegalStateException if the scope associated with this segment has been closed, or if access occurs from
* a thread other than the thread owning that scope.
- * @return The base memory address.
*/
@Override
MemoryAddress address();
@@ -299,14 +298,12 @@ public sealed interface MemorySegment extends Addressable permits AbstractMemory
Stream<MemorySegment> elements(MemoryLayout elementLayout);
/**
- * Returns the resource scope associated with this memory segment.
- * @return the resource scope associated with this memory segment.
+ * {@return the resource scope associated with this memory segment}
*/
ResourceScope scope();
/**
- * The size (in bytes) of this memory segment.
- * @return The size (in bytes) of this memory segment.
+ * {@return the size (in bytes) of this memory segment}
*/
long byteSize();
@@ -343,8 +340,7 @@ public sealed interface MemorySegment extends Addressable permits AbstractMemory
}
/**
- * Is this segment read-only?
- * @return {@code true}, if this segment is read-only.
+ * {@return {@code true}, if this segment is read-only}
* @see #asReadOnly()
*/
boolean isReadOnly();
@@ -358,7 +354,7 @@ public sealed interface MemorySegment extends Addressable permits AbstractMemory
MemorySegment asReadOnly();
/**
- * Is this a native segment? Returns true if this segment is a native memory segment,
+ * Returns {@code true} if this segment is a native segment. A native memory segment is
* created using the {@link #allocateNative(long, ResourceScope)} (and related) factory, or a buffer segment
* derived from a direct {@link java.nio.ByteBuffer} using the {@link #ofByteBuffer(ByteBuffer)} factory,
* or if this is a {@linkplain #isMapped() mapped} segment.
@@ -367,7 +363,7 @@ public sealed interface MemorySegment extends Addressable permits AbstractMemory
boolean isNative();
/**
- * Is this a mapped segment? Returns true if this segment is a mapped memory segment,
+ * Returns {@code true} if this segment is a mapped segment. A mapped memory segment is
* created using the {@link #mapFile(Path, long, long, FileChannel.MapMode, ResourceScope)} factory, or a buffer segment
* derived from a {@link java.nio.MappedByteBuffer} using the {@link #ofByteBuffer(ByteBuffer)} factory.
* @return {@code true} if this segment is a mapped segment.
@@ -484,7 +480,7 @@ public sealed interface MemorySegment extends Addressable permits AbstractMemory
long mismatch(MemorySegment other);
/**
- * Tells whether the contents of this mapped segment is resident in physical
+ * Determines whether the contents of this mapped segment is resident in physical
* memory.
*
* <p> A return value of {@code true} implies that it is highly likely
diff --git a/src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/NativeSymbol.java b/src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/NativeSymbol.java
index bf137e965d7..3dc583f98fc 100644
--- a/src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/NativeSymbol.java
+++ b/src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/NativeSymbol.java
@@ -43,22 +43,19 @@ import java.util.Objects;
sealed public interface NativeSymbol extends Addressable permits NativeSymbolImpl {
/**
- * Returns the name of this symbol.
- * @return the name of this symbol.
+ * {@return the name of this symbol}
*/
String name();
/**
- * Returns the resource scope associated with this symbol.
- * @return the resource scope associated with this symbol.
+ * {@return the resource scope associated with this symbol}
*/
ResourceScope scope();
/**
- * Returns the memory address associated with this symbol.
+ * {@return the memory address associated with this symbol}
* @throws IllegalStateException if the scope associated with this symbol has been closed, or if access occurs from
* a thread other than the thread owning that scope.
- * @return The memory address associated with this symbol.
*/
@Override
MemoryAddress address();
diff --git a/src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/ResourceScope.java b/src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/ResourceScope.java
index 24665c7dfe9..6c5d6b2b66f 100644
--- a/src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/ResourceScope.java
+++ b/src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/ResourceScope.java
@@ -147,8 +147,7 @@ import java.util.Spliterator;
*/
public sealed interface ResourceScope extends AutoCloseable permits ResourceScopeImpl {
/**
- * Is this resource scope alive?
- * @return true, if this resource scope is alive.
+ * {@return {@code true}, if this resource scope is alive}
* @see ResourceScope#close()
*/
boolean isAlive();
diff --git a/src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/SequenceLayout.java b/src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/SequenceLayout.java
index 13ac7192728..8143d2929ce 100644
--- a/src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/SequenceLayout.java
+++ b/src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/SequenceLayout.java
@@ -82,18 +82,14 @@ public final class SequenceLayout extends AbstractLayout implements MemoryLayout
}
/**
- * Returns the element layout associated with this sequence layout.
- *
- * @return The element layout associated with this sequence layout.
+ * {@return the element layout associated with this sequence layout}
*/
public MemoryLayout elementLayout() {
return elementLayout;
}
/**
- * Returns the element count of this sequence layout (if any).
- *
- * @return the element count of this sequence layout (if any).
+ * {@return the element count of this sequence layout (if any)}
*/
public OptionalLong elementCount() {
return elemCount;
diff --git a/src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/VaList.java b/src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/VaList.java
index 1bc449fa907..73ede4e4e9a 100644
--- a/src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/VaList.java
+++ b/src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/VaList.java
@@ -132,8 +132,7 @@ sealed public interface VaList extends Addressable permits WinVaList, SysVVaList
void skip(MemoryLayout... layouts);
/**
- * Returns the resource scope associated with this variable argument list.
- * @return the resource scope associated with this variable argument list.
+ * {@return the resource scope associated with this variable argument list}
*/
ResourceScope scope();
@@ -153,10 +152,9 @@ sealed public interface VaList extends Addressable permits WinVaList, SysVVaList
VaList copy();
/**
- * Returns the memory address associated with this variable argument list.
+ * {@return the {@linkplain MemoryAddress memory address} associated with this variable argument list}
* @throws IllegalStateException if the scope associated with this variable argument list has been closed, or if access occurs from
* a thread other than the thread owning that scope.
- * @return The memory address associated with this variable argument list.
*/
@Override
MemoryAddress address();
diff --git a/src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/ValueLayout.java b/src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/ValueLayout.java
index 3ce22d8743f..c2df9e1b25f 100644
--- a/src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/ValueLayout.java
+++ b/src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/ValueLayout.java
@@ -41,9 +41,9 @@ import java.util.OptionalLong;
/**
* 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, 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.
+ * (either signed or unsigned) and <em>floating-point</em> types. Each value layout has a size, an alignment (in bits),
+ * 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>
* This class defines useful value layout constants for Java primitive types and addresses.
* The layout constants in this class make implicit alignment and byte-ordering assumption: all layout
@@ -82,9 +82,7 @@ public sealed class ValueLayout extends AbstractLayout implements MemoryLayout {
}
/**
- * Returns the value's byte order.
- *
- * @return the value's byte order.
+ * {@return the value's byte order}
*/
public ByteOrder order() {
return order;
@@ -125,8 +123,7 @@ public sealed class ValueLayout extends AbstractLayout implements MemoryLayout {
}
/**
- * Returns the carrier associated with this value layout.
- * @return the carrier associated with this value layout.
+ * {@return the carrier associated with this value layout}
*/
public Class<?> carrier() {
return carrier;
@@ -513,8 +510,8 @@ public sealed class ValueLayout extends AbstractLayout implements MemoryLayout {
}
/**
- * A value layout constant whose size is the same as that of a machine address (e.g. {@code size_t}),
- * bit-alignment set to 8, and byte order set to {@link ByteOrder#nativeOrder()}.
+ * A value layout constant whose size is the same as that of a machine address ({@code size_t}),
+ * bit alignment set to 8, and byte order set to {@link ByteOrder#nativeOrder()}.
* Equivalent to the following code:
* {@snippet lang=java :
* MemoryLayout.valueLayout(MemoryAddress.class, ByteOrder.nativeOrder()).withBitAlignment(8);
@@ -524,7 +521,7 @@ public sealed class ValueLayout extends AbstractLayout implements MemoryLayout {
/**
* A value layout constant whose size is the same as that of a Java {@code byte},
- * bit-alignment set to 8, and byte order set to {@link ByteOrder#nativeOrder()}.
+ * bit alignment set to 8, and byte order set to {@link ByteOrder#nativeOrder()}.
* Equivalent to the following code:
* {@snippet lang=java :
* MemoryLayout.valueLayout(byte.class, ByteOrder.nativeOrder()).withBitAlignment(8);
@@ -534,7 +531,7 @@ public sealed class ValueLayout extends AbstractLayout implements MemoryLayout {
/**
* A value layout constant whose size is the same as that of a Java {@code boolean},
- * bit-alignment set to 8, and byte order set to {@link ByteOrder#nativeOrder()}.
+ * bit alignment set to 8, and byte order set to {@link ByteOrder#nativeOrder()}.
* Equivalent to the following code:
* {@snippet lang=java :
* MemoryLayout.valueLayout(boolean.class, ByteOrder.nativeOrder()).withBitAlignment(8);
@@ -544,7 +541,7 @@ public sealed class ValueLayout extends AbstractLayout implements MemoryLayout {
/**
* A value layout constant whose size is the same as that of a Java {@code char},
- * bit-alignment set to 8, and byte order set to {@link ByteOrder#nativeOrder()}.
+ * bit alignment set to 8, and byte order set to {@link ByteOrder#nativeOrder()}.
* Equivalent to the following code:
* {@snippet lang=java :
* MemoryLayout.valueLayout(char.class, ByteOrder.nativeOrder()).withBitAlignment(8);
@@ -554,7 +551,7 @@ public sealed class ValueLayout extends AbstractLayout implements MemoryLayout {
/**
* A value layout constant whose size is the same as that of a Java {@code short},
- * bit-alignment set to 8, and byte order set to {@link ByteOrder#nativeOrder()}.
+ * bit alignment set to 8, and byte order set to {@link ByteOrder#nativeOrder()}.
* Equivalent to the following code:
* {@snippet lang=java :
* MemoryLayout.valueLayout(short.class, ByteOrder.nativeOrder()).withBitAlignment(8);
@@ -564,7 +561,7 @@ public sealed class ValueLayout extends AbstractLayout implements MemoryLayout {
/**
* A value layout constant whose size is the same as that of a Java {@code int},
- * bit-alignment set to 8, and byte order set to {@link ByteOrder#nativeOrder()}.
+ * bit alignment set to 8, and byte order set to {@link ByteOrder#nativeOrder()}.
* Equivalent to the following code:
* {@snippet lang=java :
* MemoryLayout.valueLayout(int.class, ByteOrder.nativeOrder()).withBitAlignment(8);
@@ -574,7 +571,7 @@ public sealed class ValueLayout extends AbstractLayout implements MemoryLayout {
/**
* A value layout constant whose size is the same as that of a Java {@code long},
- * bit-alignment set to 8, and byte order set to {@link ByteOrder#nativeOrder()}.
+ * bit alignment set to 8, and byte order set to {@link ByteOrder#nativeOrder()}.
* Equivalent to the following code:
* {@snippet lang=java :
* MemoryLayout.valueLayout(long.class, ByteOrder.nativeOrder()).withBitAlignment(8);
@@ -585,7 +582,7 @@ public sealed class ValueLayout extends AbstractLayout implements MemoryLayout {
/**
* A value layout constant whose size is the same as that of a Java {@code float},
- * bit-alignment set to 8, and byte order set to {@link ByteOrder#nativeOrder()}.
+ * bit alignment set to 8, and byte order set to {@link ByteOrder#nativeOrder()}.
* Equivalent to the following code:
* {@snippet lang=java :
* MemoryLayout.valueLayout(float.class, ByteOrder.nativeOrder()).withBitAlignment(8);
@@ -595,7 +592,7 @@ public sealed class ValueLayout extends AbstractLayout implements MemoryLayout {
/**
* A value layout constant whose size is the same as that of a Java {@code double},
- * bit-alignment set to 8, and byte order set to {@link ByteOrder#nativeOrder()}.
+ * bit alignment set to 8, and byte order set to {@link ByteOrder#nativeOrder()}.
* Equivalent to the following code:
* {@snippet lang=java :
* MemoryLayout.valueLayout(double.class, ByteOrder.nativeOrder()).withBitAlignment(8);
diff --git a/src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/package-info.java b/src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/package-info.java
index 3621495d064..a74c6d3a55d 100644
--- a/src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/package-info.java
+++ b/src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/package-info.java
@@ -30,7 +30,7 @@
* <h2>Foreign memory access</h2>
*
* <p>
- * The main abstractions introduced to support foreign memory access is {@link jdk.incubator.foreign.MemorySegment}, which
+ * The main abstraction introduced to support foreign memory access is {@link jdk.incubator.foreign.MemorySegment}, which
* models a contiguous memory region, which can reside either inside or outside the Java heap.
* A memory segment represents the main access coordinate of a memory access var handle, which can be obtained
* using the combinator methods defined in the {@link jdk.incubator.foreign.MemoryHandles} class; a set of