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

[Nizar Benalla]

On Mon, 12 May 2025 15:58:11 GMT, Nizar Benalla <nbenalla at openjdk.org> wrote:

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

Deferred to 26.

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

PR Comment: https://git.openjdk.org/jdk/pull/25187#issuecomment-2931179524