RFR: 8139744: Types referred in @link/@linkplain tags are not always hyperlinks

Nizar Benalla nbenalla at openjdk.org
Tue May 13 11:03:46 UTC 2025


Please review this patch to emit a new warning if the reference element cannot be linked. This is intended to prevent links to private member in the JDK docs (see https://bugs.openjdk.org/browse/JDK-8310868).

Here is a [clear example](https://download.java.net/java/early_access/jdk25/docs/api/java.base/java/net/Socket.html#shutdownOutput()) of this bug:

<img width="1071" alt="Screenshot 2025-05-12 at 16 55 26" src="https://github.com/user-attachments/assets/9bbca975-7f41-4970-9735-95906b402534" />

We should link to `sInputShutdown()` instead.


Some private fields are [documented](https://download.java.net/java/early_access/jdk25/docs/api/serialized-form.html#java.awt.Frame) on the Serialization page if the class is serializable. After this patch, warnings will be emitted if a there is an incorrect link in their javadoc. 

Similar to the image below where the there is no hypertext and the link is rendered as plain text, because the linked method is private.
<img width="422" alt="Screenshot 2025-05-12 at 16 53 56" src="https://github.com/user-attachments/assets/847a2acc-f289-4048-b239-77baa87a01ea" />

This bug can also creep in later without the author noticing, if they add a new method and javadoc matches it instead.


Note: This PR can only be integrated after all site bugs are fixed in [JDK-8356549.](https://bugs.openjdk.org/browse/JDK-8356549)

-------------

Commit messages:
 - emit warning for incorrect {@link/@linkplain} tags

Changes: https://git.openjdk.org/jdk/pull/25187/files
  Webrev: https://webrevs.openjdk.org/?repo=jdk&pr=25187&range=00
  Issue: https://bugs.openjdk.org/browse/JDK-8139744
  Stats: 112 lines in 3 files changed: 111 ins; 0 del; 1 mod
  Patch: https://git.openjdk.org/jdk/pull/25187.diff
  Fetch: git fetch https://git.openjdk.org/jdk.git pull/25187/head:pull/25187

PR: https://git.openjdk.org/jdk/pull/25187


More information about the javadoc-dev mailing list