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