Docs: Replace incorrect @see usage with @link

[huzaifaalmesbah]

Trac Ticket: https://core.trac.wordpress.org/ticket/64224

Why this change?

This change aligns the codebase with the WordPress PHP Documentation Standards, which clearly distinguish between the intended usage of the @see and @link tags:

• @see is meant for referencing internal structural elements of the WordPress codebase, such as classes, functions, methods, or hooks.
• @link is meant for referencing external resources, including URLs, specifications, and tickets hosted outside the codebase.

Currently, there are several instances in WordPress core where @see is incorrectly used to reference:

• GitHub URLs
• Trac tickets
• External specifications (e.g. WHATWG specs)

This PR corrects those cases by replacing @see with @link where the reference points to an external resource.

When to use @link

• External URLs
  Always use @link when referencing an external URL
  Example: @link https://html.spec.whatwg.org

• External resources
  Use @link for documentation, specifications, or tickets that live outside the WordPress codebase

Contrast with @see

• Internal structure references
  Use @see when referring to:
  • Functions (e.g. @see wp_remote_get())
  • Classes (e.g. @see WP_Query)
  • Methods or hooks defined within WordPress core

Detailed changes

This PR applies targeted fixes across 15 specific files in src/wp-admin and src/wp-includes, replacing incorrect @see tags with @link where appropriate.

src/wp-admin

• edit-form-blocks.php
• site-editor.php

src/wp-includes

• html-api/class-wp-html-active-formatting-elements.php
• html-api/class-wp-html-doctype-info.php
• html-api/class-wp-html-tag-processor.php
• html-api/class-wp-html-decoder.php
• class-wp-url-pattern-prefixer.php
• nav-menu-template.php
• pluggable.php
• media.php
• rest-api/endpoints/class-wp-rest-controller.php
• rest-api/endpoints/class-wp-rest-templates-controller.php
• script-loader.php
• speculative-loading.php
• deprecated.php

[github-actions]

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

Core Committers: Use this line as a base for the props when committing in SVN:

Props huzaifaalmesbah, shailu25, noruzzaman, westonruter.

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

[github-actions]

Test using WordPress Playground

The changes in this pull request can previewed and tested using a WordPress Playground instance.

WordPress Playground is an experimental project that creates a full WordPress instance entirely within the browser.

Some things to be aware of

• The Plugin and Theme Directories cannot be accessed within Playground.
• All changes will be lost when closing a tab with a Playground instance.
• All changes will be lost when refreshing the page.
• A fresh instance is created each time the link below is clicked.
• Every time this pull request is updated, a new ZIP file containing all changes is created. If changes are not reflected in the Playground instance,
  it's possible that the most recent build failed, or has not completed. Check the list of workflow runs to be sure.

For more details about these limitations and more, check out the Limitations page in the WordPress Playground documentation.

Test this pull request with WordPress Playground.

[noruzzamans]

@huzaifaalmesbah Thanks for working on this cleanup!

The conversion from @see to @link for external URLs is correct and follows the WordPress documentation standards. However, for better consistency within this PR, I suggest adding a brief description after each @link URL, similar to what was done in src/wp-includes/html-api/class-wp-html-decoder.php

For example: * @link [URL] [Brief Description]

This would make the documentation more descriptive and maintain a uniform style across all the modified files in this PR.

[shail-mehta]

LGTM 👍

[westonruter]

I had wondered about this, but @see seems to be OK for either structural elements or a URI. See https://docs.phpdoc.org/guide/references/phpdoc/tags/see.html (pun intended)

[huzaifaalmesbah]

Thanks for pointing this out @westonruter !
You’re right. phpDocumentor does allow using @see with a URI as well.

However, according to the WordPress PHP Documentation Standards for DocBlocks:

👉 URLs should be added with the @link tag.

Specifically, the handbook states:

@link: URL that provides more information. This should never be used to reference another function, hook, class, or method — see @see.

And:

@see: Reference to a function/method/class that the function/method relies on.

So, while generic phpDocumentor allows linking URLs with @see, WordPress core’s own standard distinguishes them semantically — and this PR is aligning core with that documented WordPress standard for consistency.

Otherwise… I guess we might need to update the WordPress PHP Documentation Standards too 😄