Merge

Author: JesperIRL

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

@@ -40,8 +40,7 @@
 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();
 }

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

@@ -54,16 +54,14 @@ private FunctionDescriptor(MemoryLayout resLayout, List<MemoryLayout> argLayouts
     }
 
     /**
-     * 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 FunctionDescriptor dropReturnLayout() {
     }
 
     /**
-     * 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 boolean equals(Object other) {
     }
 
     /**
-     * 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() {

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

@@ -133,18 +133,14 @@ public String toString() {
     }
 
     /**
-     * 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;

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

@@ -78,8 +78,7 @@
 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();

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

@@ -195,18 +195,15 @@
 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 @@ private static <Z> Z computePathOp(LayoutPath path, Function<LayoutPath, Z> fina
     }
 
     /**
-     * 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 @@ static PathElement sequenceElement() {
     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();

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 @@ default MemorySegment asSlice(long offset) {
     }
 
     /**
-     * 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 @@ default MemorySegment asSlice(long offset) {
     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 @@ default MemorySegment asSlice(long offset) {
     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 @@ default MemorySegment copyFrom(MemorySegment src) {
     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

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

@@ -43,22 +43,19 @@
 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();

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

@@ -147,8 +147,7 @@
  */
 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();

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;

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();