From 5311209220bfd0e8349708f8a9459ada831e5842 Mon Sep 17 00:00:00 2001
From: Nizar Benalla <nizar.benalla@oracle.com>
Date: Sat, 17 May 2025 20:05:11 +0100
Subject: [PATCH 1/4] fix incorrect `@link` tags

---
 .../share/classes/java/lang/invoke/MethodHandles.java     | 6 +++---
 .../share/classes/java/lang/invoke/MethodType.java        | 6 +++---
 .../share/classes/java/lang/module/ModuleDescriptor.java  | 2 +-
 src/java.base/share/classes/java/net/Socket.java          | 8 ++++----
 .../share/classes/java/util/concurrent/ForkJoinTask.java  | 4 ++--
 src/java.base/share/classes/javax/crypto/KEM.java         | 2 +-
 6 files changed, 14 insertions(+), 14 deletions(-)

diff --git a/src/java.base/share/classes/java/lang/invoke/MethodHandles.java b/src/java.base/share/classes/java/lang/invoke/MethodHandles.java
index 007834ed5f4a8..33b17a4e88cd1 100644
--- a/src/java.base/share/classes/java/lang/invoke/MethodHandles.java
+++ b/src/java.base/share/classes/java/lang/invoke/MethodHandles.java
@@ -2821,10 +2821,10 @@ private IllegalAccessException makeAccessException(Class<?> targetClass) {
          * if and only if one of the following is true:
          * <ul>
          * <li>{@code targetClass} is in {@code M0} and {@code M1}
-         *     {@linkplain Module#reads reads} {@code M0} and the type is
+         *     {@linkplain Module#canRead(Module)}  reads} {@code M0} and the type is
          *     in a package that is exported to at least {@code M1}.
          * <li>{@code targetClass} is in {@code M1} and {@code M0}
-         *     {@linkplain Module#reads reads} {@code M1} and the type is
+         *     {@linkplain Module#canRead(Module)}  reads} {@code M1} and the type is
          *     in a package that is exported to at least {@code M0}.
          * <li>{@code targetClass} is in a third module {@code M2} and both {@code M0}
          *     and {@code M1} reads {@code M2} and the type is in a package
@@ -4890,7 +4890,7 @@ private static MethodHandle identityOrVoid(Class<?> type) {
      * @param type the type of the desired method handle
      * @return a constant method handle of the given type, which returns a default value of the given return type
      * @throws NullPointerException if the argument is null
-     * @see MethodHandles#primitiveZero
+     * @see <code>primitiveZero(Wrapper)</code>
      * @see MethodHandles#constant
      * @since 9
      */
diff --git a/src/java.base/share/classes/java/lang/invoke/MethodType.java b/src/java.base/share/classes/java/lang/invoke/MethodType.java
index 3d15ce6871086..49946601c79be 100644
--- a/src/java.base/share/classes/java/lang/invoke/MethodType.java
+++ b/src/java.base/share/classes/java/lang/invoke/MethodType.java
@@ -1332,13 +1332,13 @@ private void writeObject(java.io.ObjectOutputStream s) throws java.io.IOExceptio
      * deserialize it).
      * This instance is a scratch object with bogus final fields.
      * It provides the parameters to the factory method called by
-     * {@link #readResolve readResolve}.
+     * {@code readResolve}.
      * After that call it is discarded.
      * @param s the stream to read the object from
      * @throws java.io.IOException if there is a problem reading the object
      * @throws ClassNotFoundException if one of the component classes cannot be resolved
-     * @see #readResolve
-     * @see #writeObject
+     * @see <code>MethodType.readResolve()</code>
+     * @see <code>MethodType.writeObject(ObjectOutputStream s)</code>
      */
     @java.io.Serial
     private void readObject(java.io.ObjectInputStream s) throws java.io.IOException, ClassNotFoundException {
diff --git a/src/java.base/share/classes/java/lang/module/ModuleDescriptor.java b/src/java.base/share/classes/java/lang/module/ModuleDescriptor.java
index 169c2656bbaba..7aac752cc8922 100644
--- a/src/java.base/share/classes/java/lang/module/ModuleDescriptor.java
+++ b/src/java.base/share/classes/java/lang/module/ModuleDescriptor.java
@@ -2020,7 +2020,7 @@ public Builder uses(String service) {
 
         /**
          * Provides a service with one or more implementations. The package for
-         * each {@link Provides#providers provider} (or provider factory) is
+         * each {@link Provides#providers() provider} (or provider factory) is
          * added to the module if not already added.
          *
          * @param  p
diff --git a/src/java.base/share/classes/java/net/Socket.java b/src/java.base/share/classes/java/net/Socket.java
index cdf2d703233bf..d2afa166a8888 100644
--- a/src/java.base/share/classes/java/net/Socket.java
+++ b/src/java.base/share/classes/java/net/Socket.java
@@ -679,7 +679,7 @@ public void connect(SocketAddress endpoint, int timeout) throws IOException {
      *          SocketAddress subclass not supported by this socket
      *
      * @since   1.4
-     * @see #isBound
+     * @see #isBound()
      */
     public void bind(SocketAddress bindpoint) throws IOException {
         int s = state;
@@ -1612,7 +1612,7 @@ private void closeSuppressingExceptions(Throwable parentException) {
      * as well.
      *
      * @throws     IOException  if an I/O error occurs when closing this socket.
-     * @see #isClosed
+     * @see #isClosed()
      */
     public void close() throws IOException {
         synchronized (socketLock) {
@@ -1642,7 +1642,7 @@ public void close() throws IOException {
      * @see java.net.Socket#shutdownOutput()
      * @see java.net.Socket#close()
      * @see java.net.Socket#setSoLinger(boolean, int)
-     * @see #isInputShutdown
+     * @see #isInputShutdown()
      */
     public void shutdownInput() throws IOException {
         int s = state;
@@ -1672,7 +1672,7 @@ public void shutdownInput() throws IOException {
      * @see java.net.Socket#shutdownInput()
      * @see java.net.Socket#close()
      * @see java.net.Socket#setSoLinger(boolean, int)
-     * @see #isOutputShutdown
+     * @see #isOutputShutdown()
      */
     public void shutdownOutput() throws IOException {
         int s = state;
diff --git a/src/java.base/share/classes/java/util/concurrent/ForkJoinTask.java b/src/java.base/share/classes/java/util/concurrent/ForkJoinTask.java
index 5f2dcb30d413c..51b2488264e03 100644
--- a/src/java.base/share/classes/java/util/concurrent/ForkJoinTask.java
+++ b/src/java.base/share/classes/java/util/concurrent/ForkJoinTask.java
@@ -131,11 +131,11 @@
  * (including the case where a task was cancelled without executing);
  * {@link #isCompletedNormally} is true if a task completed without
  * cancellation or encountering an exception; {@link #isCancelled} is
- * true if the task was cancelled (in which case {@link #getException}
+ * true if the task was cancelled (in which case {@link #getException()}
  * returns a {@link CancellationException}); and
  * {@link #isCompletedAbnormally} is true if a task was either
  * cancelled or encountered an exception, in which case {@link
- * #getException} will return either the encountered exception or
+ * #getException()} will return either the encountered exception or
  * {@link CancellationException}.
  *
  * <p>The ForkJoinTask class is not usually directly subclassed.
diff --git a/src/java.base/share/classes/javax/crypto/KEM.java b/src/java.base/share/classes/javax/crypto/KEM.java
index f19d3306266e6..7f5c3dfa01801 100644
--- a/src/java.base/share/classes/javax/crypto/KEM.java
+++ b/src/java.base/share/classes/javax/crypto/KEM.java
@@ -708,7 +708,7 @@ public Encapsulator newEncapsulator(PublicKey publicKey, SecureRandom secureRand
      * If any extra information inside this object needs to be transmitted along
      * with the key encapsulation message so that the receiver is able to create
      * a matching decapsulator, it will be included as a byte array in the
-     * {@link Encapsulated#params} field inside the encapsulation output.
+     * {@link Encapsulated#params()} field inside the encapsulation output.
      * In this case, the security provider should provide an
      * {@code AlgorithmParameters} implementation using the same algorithm name
      * as the KEM. The receiver can initiate such an {@code AlgorithmParameters}

From b17b55fa1218d79d757524608ff9a109fdb82bff Mon Sep 17 00:00:00 2001
From: Nizar Benalla <nizar.benalla@oracle.com>
Date: Mon, 19 May 2025 16:54:10 +0100
Subject: [PATCH 2/4] respond to feedback

---
 src/java.base/share/classes/java/lang/invoke/MethodHandles.java | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/java.base/share/classes/java/lang/invoke/MethodHandles.java b/src/java.base/share/classes/java/lang/invoke/MethodHandles.java
index 33b17a4e88cd1..3d7ba22e54e09 100644
--- a/src/java.base/share/classes/java/lang/invoke/MethodHandles.java
+++ b/src/java.base/share/classes/java/lang/invoke/MethodHandles.java
@@ -4890,7 +4890,7 @@ private static MethodHandle identityOrVoid(Class<?> type) {
      * @param type the type of the desired method handle
      * @return a constant method handle of the given type, which returns a default value of the given return type
      * @throws NullPointerException if the argument is null
-     * @see <code>primitiveZero(Wrapper)</code>
+     * @see MethodHandles#zero(Class)
      * @see MethodHandles#constant
      * @since 9
      */

From 0653af94b02339830c0b226ae61d55dc3c470eac Mon Sep 17 00:00:00 2001
From: Nizar Benalla <nizar.benalla@oracle.com>
Date: Thu, 22 May 2025 16:14:24 +0100
Subject: [PATCH 3/4] revert changes to MethodType.java. <code>foo</code>
 markup should not be used

---
 .../share/classes/java/lang/invoke/MethodType.java          | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/src/java.base/share/classes/java/lang/invoke/MethodType.java b/src/java.base/share/classes/java/lang/invoke/MethodType.java
index 49946601c79be..3d15ce6871086 100644
--- a/src/java.base/share/classes/java/lang/invoke/MethodType.java
+++ b/src/java.base/share/classes/java/lang/invoke/MethodType.java
@@ -1332,13 +1332,13 @@ private void writeObject(java.io.ObjectOutputStream s) throws java.io.IOExceptio
      * deserialize it).
      * This instance is a scratch object with bogus final fields.
      * It provides the parameters to the factory method called by
-     * {@code readResolve}.
+     * {@link #readResolve readResolve}.
      * After that call it is discarded.
      * @param s the stream to read the object from
      * @throws java.io.IOException if there is a problem reading the object
      * @throws ClassNotFoundException if one of the component classes cannot be resolved
-     * @see <code>MethodType.readResolve()</code>
-     * @see <code>MethodType.writeObject(ObjectOutputStream s)</code>
+     * @see #readResolve
+     * @see #writeObject
      */
     @java.io.Serial
     private void readObject(java.io.ObjectInputStream s) throws java.io.IOException, ClassNotFoundException {

From daaed6c529c2907bf11a4206319c67b56fe5c6e3 Mon Sep 17 00:00:00 2001
From: Nizar Benalla <nizar.benalla@oracle.com>
Date: Fri, 23 May 2025 15:54:25 +0100
Subject: [PATCH 4/4] update javadoc based on feedback

---
 src/java.base/share/classes/javax/crypto/KEM.java | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/java.base/share/classes/javax/crypto/KEM.java b/src/java.base/share/classes/javax/crypto/KEM.java
index 7f5c3dfa01801..58089b386661d 100644
--- a/src/java.base/share/classes/javax/crypto/KEM.java
+++ b/src/java.base/share/classes/javax/crypto/KEM.java
@@ -707,8 +707,8 @@ public Encapsulator newEncapsulator(PublicKey publicKey, SecureRandom secureRand
      * the same key can be used to derive shared secrets in different ways.
      * If any extra information inside this object needs to be transmitted along
      * with the key encapsulation message so that the receiver is able to create
-     * a matching decapsulator, it will be included as a byte array in the
-     * {@link Encapsulated#params()} field inside the encapsulation output.
+     * a matching decapsulator, it will be included as a byte array returned by the
+     * {@link Encapsulated#params()} method within the encapsulation output.
      * In this case, the security provider should provide an
      * {@code AlgorithmParameters} implementation using the same algorithm name
      * as the KEM. The receiver can initiate such an {@code AlgorithmParameters}