8356632: Fix remaining {@link/@linkplain} tags with refer to private/protected types in java.base #25287

nizarbenalla · 2025-05-17T19:42:39Z

Please review this patch to fix some javadoc bugs in java.base.
Certain @link tags used to refer to private fields instead of public APIs.

A couple of @see tags in the serialization page referred to private methods, I updated the javadoc in a way to not change the way it is displayed to users but also remove @link tags to non-included types.

TIA

Progress

Change must be properly reviewed (1 review required, with at least 1 Reviewer)
Change must not contain extraneous whitespace
Commit message must refer to an issue

Issue

JDK-8356632: Fix remaining {@link/@linkplain} tags with refer to private/protected types in java.base (Sub-task - P4)

Reviewers

Chen Liang (@liach - Reviewer) Review applies to 0653af94
Weijun Wang (@wangweij - Reviewer)

Reviewing

Using git

Checkout this PR locally:
$ git fetch https://git.openjdk.org/jdk.git pull/25287/head:pull/25287
$ git checkout pull/25287

Update a local copy of the PR:
$ git checkout pull/25287
$ git pull https://git.openjdk.org/jdk.git pull/25287/head

Using Skara CLI tools

Checkout this PR locally:
$ git pr checkout 25287

View PR using the GUI difftool:
$ git pr show -t 25287

Using diff file

Download this PR as a diff file:
https://git.openjdk.org/jdk/pull/25287.diff

Using Webrev

Link to Webrev Comment

bridgekeeper · 2025-05-17T19:43:25Z

👋 Welcome back nbenalla! A progress list of the required criteria for merging this PR into master will be added to the body of your pull request. There are additional pull request commands available for use with this pull request.

openjdk · 2025-05-17T19:44:17Z

@nizarbenalla This change now passes all automated pre-integration checks.

ℹ️ This project also has non-automated pre-integration requirements. Please see the file CONTRIBUTING.md for details.

After integration, the commit message for the final commit will be:

8356632: Fix remaining {@link/@linkplain} tags with refer to private/protected types in java.base

Reviewed-by: weijun, liach

You can use pull request commands such as /summary, /contributor and /issue to adjust it as needed.

At the time when this comment was updated there had been 113 new commits pushed to the master branch:

90e076b: 8357654: [BACKOUT] JDK-8343580: Type error with inner classes of generic classes in functions generic by outer
6a07820: 8357285: JSR166 Test case testShutdownNow_delayedTasks failed
b07da7b: 8357171: Test tools/jpackage/windows/WinOSConditionTest.java fails for non administrator
... and 110 more: https://git.openjdk.org/jdk/compare/76570c627db527f856f2394fb9ead02939eca621...master

As there are no conflicts, your changes will automatically be rebased on top of these commits when integrating. If you prefer to avoid this automatic rebasing, please check the documentation for the /integrate command for further details.

➡️ To integrate this PR with the above commit message to the master branch, type /integrate in a new comment.

openjdk · 2025-05-17T19:44:40Z

@nizarbenalla The following labels will be automatically applied to this pull request:

core-libs
net
security

When this pull request is ready to be reviewed, an "RFR" email will be sent to the corresponding mailing lists. If you would like to change these labels, use the /label pull request command.

liach · 2025-05-18T02:17:46Z

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 MethodHandles#primitiveZero
+     * @see <code>primitiveZero(Wrapper)</code>


Just #zero(Class) should be sufficient. This is probably changed by intellij during my original work to consolidate zero and constant.

From #23706 (comment):

Suggested change

* @see <code>primitiveZero(Wrapper)</code>

* @see MethodHandles#zero

liach · 2025-05-18T02:18:24Z

src/java.base/share/classes/java/lang/invoke/MethodType.java

-     * @see #readResolve
-     * @see #writeObject
+     * @see <code>MethodType.readResolve()</code>
+     * @see <code>MethodType.writeObject(ObjectOutputStream s)</code>


This is already not generated by the javadoc as this method is private. Why is this check against a private method?

They are documented in this page

Okay -- if there is some link to the private serial-related methods even in a public javadoc run, I think it would be preferable if links to those methods could be resolved by javadoc. Otherwise, if the links to private methods from a private method, would be valid in a private javadoc run, I thinks more refined version of warning would let those be.

As it is, if the see tags are going to stay, I don't think <code>foo</code> markup should be used.

I will revert the changes to MethoType.java and try to make the links to the private methods resolvable. (In a future patch)

mlbridge · 2025-05-19T16:08:02Z

Webrevs

AlanBateman · 2025-05-20T06:48:01Z

src/java.base/share/classes/java/util/concurrent/ForkJoinTask.java

 * 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


Looks right too, the private overload of getException was added in JDK 22.

AlanBateman · 2025-05-20T06:52:07Z

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


dfuch

Changes to java.net.Socket LGTM

… be used

liach

Changes to MethodHandles look good. Please wait for a review from security developers for KEM.java.

wangweij · 2025-05-23T14:28:29Z

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.


Good catch. The text must have been added before we changed Encapsulated from a record to a normal class. Now that params is a method instead of a record field, please consider rewriting the sentence to something like

it will be included as a byte array returned by the {@link Encapsulated#params()} method within the encapsulation output.

wangweij

The KEM.java change looks good to me. Thanks.

nizarbenalla · 2025-05-26T12:40:28Z

All files have been reviewed. Thanks All!

/integrate

openjdk · 2025-05-26T12:40:49Z

Going to push as commit bd09589.
Since your change was applied there have been 137 commits pushed to the master branch:

daa8eda: 8357056: RISC-V: Asm fixes - load/store width
7002233: 8351950: C2: AVX512 vector assembler routines causing SIGFPE / no valid evex tuple_table entry
f825a51: 7046003: Default value of Authenticator.getRequestingURL() is not specified
... and 134 more: https://git.openjdk.org/jdk/compare/76570c627db527f856f2394fb9ead02939eca621...master

Your commit was automatically rebased without conflicts.

openjdk · 2025-05-26T12:40:57Z

@nizarbenalla Pushed as commit bd09589.

💡 You may see a message that your pull request was closed with unmerged commits. This can be safely ignored.

fix incorrect @link tags

5311209

openjdk bot added security [email protected] core-libs [email protected] net [email protected] labels May 17, 2025

liach reviewed May 18, 2025

View reviewed changes

respond to feedback

b17b55f

nizarbenalla marked this pull request as ready for review May 19, 2025 16:04

openjdk bot added the rfr Pull request is ready for review label May 19, 2025

AlanBateman reviewed May 20, 2025

View reviewed changes

dfuch reviewed May 20, 2025

View reviewed changes

revert changes to MethodType.java. <code>foo</code> markup should not…

0653af9

… be used

liach approved these changes May 22, 2025

View reviewed changes

openjdk bot added the ready Pull request is ready to be integrated label May 22, 2025

wangweij reviewed May 23, 2025

View reviewed changes

update javadoc based on feedback

daaed6c

openjdk bot removed the ready Pull request is ready to be integrated label May 23, 2025

wangweij approved these changes May 23, 2025

View reviewed changes

openjdk bot added the ready Pull request is ready to be integrated label May 23, 2025

openjdk bot added the integrated Pull request has been integrated label May 26, 2025

openjdk bot closed this May 26, 2025

openjdk bot removed ready Pull request is ready to be integrated rfr Pull request is ready for review labels May 26, 2025

nizarbenalla deleted the fix-incorrect-link-tags-java.base branch May 26, 2025 12:46

	* @see <code>primitiveZero(Wrapper)</code>
	* @see MethodHandles#zero

8356632: Fix remaining {@link/@linkplain} tags with refer to private/protected types in java.base #25287

8356632: Fix remaining {@link/@linkplain} tags with refer to private/protected types in java.base #25287

Uh oh!

Conversation

nizarbenalla commented May 17, 2025 • edited by openjdk bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Progress

Issue

Reviewers

Reviewing

Uh oh!

bridgekeeper bot commented May 17, 2025

Uh oh!

openjdk bot commented May 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

openjdk bot commented May 17, 2025

Uh oh!

liach May 18, 2025

Choose a reason for hiding this comment

Uh oh!

ExE-Boss May 18, 2025

Choose a reason for hiding this comment

Uh oh!

liach May 18, 2025

Choose a reason for hiding this comment

Uh oh!

nizarbenalla May 19, 2025

Choose a reason for hiding this comment

Uh oh!

jddarcy May 19, 2025

Choose a reason for hiding this comment

Uh oh!

nizarbenalla May 20, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mlbridge bot commented May 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Webrevs

Uh oh!

AlanBateman May 20, 2025

Choose a reason for hiding this comment

Uh oh!

AlanBateman May 20, 2025

Choose a reason for hiding this comment

Uh oh!

dfuch left a comment

Choose a reason for hiding this comment

Uh oh!

liach left a comment

Choose a reason for hiding this comment

Uh oh!

wangweij May 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

wangweij left a comment

Choose a reason for hiding this comment

Uh oh!

nizarbenalla commented May 26, 2025

Uh oh!

openjdk bot commented May 26, 2025

Uh oh!

openjdk bot commented May 26, 2025

Uh oh!

Uh oh!

nizarbenalla commented May 17, 2025 •

edited by openjdk bot

Loading

openjdk bot commented May 17, 2025 •

edited

Loading

nizarbenalla May 20, 2025 •

edited

Loading

mlbridge bot commented May 19, 2025 •

edited

Loading

wangweij May 23, 2025 •

edited

Loading