Docs: Replace incorrect @see usage with @link by huzaifaalmesbah · Pull Request #10804 · WordPress/wordpress-develop

huzaifaalmesbah · 2026-01-27T19:02:14Z

✅ Committed in r64436 (8ce8797).

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

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.

Note that generic PHPDoc does allow a URI in @see (phpDocumentor defines it as @see [URI | FQSEN]), so these usages are not invalid PHPDoc; they are non-standard under the WordPress PHP Documentation Standards, which reserve @see for elements and @link for URLs. The same conversion was previously committed in r63569.

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

Every @see tag that pointed to a URL is converted to @link, across 34 files in src/wp-includes, src/wp-load.php, src/js/_enqueues, the Twenty Fifteen and Twenty Twenty themes, and tests/phpunit.

The HTML API changes (src/wp-includes/html-api/ and its tests) have been split out into #14370 for review by the HTML API maintainers.

Related cleanups:

Where the converted @link ended up above an @see tag, the two are swapped so @see comes first, per the documentation standards.
In the Twenty Twenty comment walker, the developer.wordpress.org URLs for core functions are replaced with @see function_name() references.
Broken links on the touched lines are fixed: the Trac /tickets/42957 path in pluggable.php and user.php, the Requests hooks docs URL (master → stable), and the dead MSDN and Chromium links on send_nosniff_header().

Out of scope and left unchanged:

src/wp-includes/blocks/, which is synced from Gutenberg.
src/wp-includes/pomo/, which is a bundled library.
The vendored normalize.css comment in Twenty Thirteen's style.css.
The HTML API, which is handled in HTML API: Use @link instead of @see for URL references #14370.

See https://core.trac.wordpress.org/ticket/64224

github-actions · 2026-01-27T19:02:24Z

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, westonruter, shailu25, noruzzaman.

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

github-actions · 2026-01-27T19:13:47Z

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 · 2026-01-28T05:03:08Z

@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 · 2026-01-31T07:56:19Z

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 · 2026-01-31T08:18:35Z

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 😄

westonruter · 2026-07-16T01:05:01Z

Note there are merge conflicts.

Also, if we are to make this change, should probably do it once every single occurrence.

@see

Comprehensive pass converting all `@see <url>` occurrences to `@link <url>` across WordPress core PHP, where @see was incorrectly used for URLs. Symbol references such as `@see Class::method()` are unchanged. Bundled external libraries (PHPMailer, SimplePie, PSR/Nyholm) are intentionally excluded.

@see

The pomo/ directory is a bundled library, out of scope for this docs convention change. Restores the original @see in plural-forms.php.

huzaifaalmesbah · 2026-07-16T03:14:14Z

Thanks for the review @westonruter ! Both points are now addressed:

Merge conflicts have been resolved.
The @see → @link change has been applied to all WordPress core PHP occurrences. Bundled libraries were excluded.

@see

The src/wp-includes/blocks/ directory is synced from Gutenberg packages and out of scope for core repo docs convention changes. Restores original @see tags to prevent build process failures.

# Conflicts: # src/wp-includes/global-styles-and-settings.php

huzaifaalmesbah · 2026-10-17T00:49:16Z

@westonruter I merged the latest trunk into this branch and resolved the conflict in src/wp-includes/global-styles-and-settings.php (1c4cec8). Trunk had removed the caching block in wp_get_global_settings() whose comment this PR updated, so I kept trunk's version there. The rest of the diff is unchanged: 208 @see to @link replacements across 34 files, with no other changes. PHPCS reports the same 13 warnings as trunk for these files, and the PR is mergeable again.

The remaining @see URLs in src are in the bundled php-ai-client/third-party code and in a JavaScript docblock inside script-loader.php, so I left them out of scope.

Converting `@see URL` to `@link URL` in place left the new `@link` tags ahead of the `@see` tags that followed them. The PHP documentation standards order `@see` before `@link`, so swap them. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

…lker. The `html5_comment()` docblock linked to the developer.wordpress.org pages for core functions. Internal symbols are referenced with `@see function()`, which lets the documentation parser cross-link them, matching the existing `@see wp_list_comments()` in the same block. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

@see

A tag is only recognized at the start of a docblock line, so a list item reading `- @link URL` is plain text. Inside prose and lists, the inline `{@link URL}` form is the correct one, and it also restores the braces the original `- @see {URL}` items had. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Convert the `@see URL` references the earlier sweep missed: the inline prefetch script in `script-loader.php`, `pomo/plural-forms.php`, core JavaScript sources in `src/js`, and the PHPUnit tests and test helpers. The block render files in `src/wp-includes/blocks/` are left alone since they are synced from Gutenberg, and the normalize.css comment in Twenty Thirteen is left alone since it is vendored. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Trac ticket URLs use `/ticket/<number>`, not `/tickets/<number>`. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

The Requests library no longer has a `master` branch; the old URL only works through a redirect to `stable`, so link to `stable` directly. Also move the `@link` tag after `@since`, per the PHP documentation standards. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

The IE blog post moved from blogs.msdn.com to the Microsoft Learn archive, and the Chromium ViewVC revision link no longer resolves. Point to the archived post and to the Fetch Standard, which now defines the `X-Content-Type-Options` header. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Restore the `@see` tag in `pomo/plural-forms.php`, which was converted despite the earlier decision to treat the pomo library as out of scope. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

…cription. The class description interleaves spec references with its paragraphs. As block-level tags, the first `@link` ended the description, and the paragraphs after it were parsed as the link's text. The inline form keeps the references in place without cutting the description short. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Restore the HTML API classes and their tests to match trunk. Their `@see` to `@link` changes now live in their own pull request, so the HTML API maintainers can review them separately. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

The WordPress inline documentation standards for PHP and JavaScript reserve `@see` for references to functions, methods, classes, and hooks, and use `@link` for URLs. While phpDocumentor and JSDoc both accept a URL in `@see`, core had used both forms for external references such as specifications, Trac tickets, and GitHub pull requests, so the remaining `@see` tags pointing to URLs are converted to `@link` across core, the bundled themes, core scripts, and the unit tests. On the touched lines, `@see` is kept ahead of `@link` where both appear, per the standards; links to developer.wordpress.org pages for core functions in Twenty Twenty become `@see` references to those functions; and links that no longer resolve are updated. The block files synced from Gutenberg, the bundled pomo library, and other third-party code are left unchanged, and the HTML API is handled separately. Developed in #10804. Follow-up to r63569. Props huzaifaalmesbah, westonruter, noruzzaman, shailu25. See #65860. git-svn-id: https://develop.svn.wordpress.org/trunk@64436 602fd350-edb4-49c9-b593-d223f7449a82

The WordPress inline documentation standards for PHP and JavaScript reserve `@see` for references to functions, methods, classes, and hooks, and use `@link` for URLs. While phpDocumentor and JSDoc both accept a URL in `@see`, core had used both forms for external references such as specifications, Trac tickets, and GitHub pull requests, so the remaining `@see` tags pointing to URLs are converted to `@link` across core, the bundled themes, core scripts, and the unit tests. On the touched lines, `@see` is kept ahead of `@link` where both appear, per the standards; links to developer.wordpress.org pages for core functions in Twenty Twenty become `@see` references to those functions; and links that no longer resolve are updated. The block files synced from Gutenberg, the bundled pomo library, and other third-party code are left unchanged, and the HTML API is handled separately. Developed in WordPress/wordpress-develop#10804. Follow-up to r63569. Props huzaifaalmesbah, westonruter, noruzzaman, shailu25. See #65860. Built from https://develop.svn.wordpress.org/trunk@64436 git-svn-id: http://core.svn.wordpress.org/trunk@63586 1a063a9b-81f0-0310-95a4-ce76da25c4cd

Docs: Replace incorrect @see usage with @link in specific core files

844c520

See https://core.trac.wordpress.org/ticket/64224

Merge branch 'trunk' into fix/correct-see-usage

644e037

shail-mehta reviewed Jan 28, 2026

View reviewed changes

huzaifaalmesbah added 2 commits January 29, 2026 16:26

Merge branch 'trunk' into fix/correct-see-usage

f0659ae

Merge branch 'trunk' into fix/correct-see-usage

f7f58b9

huzaifaalmesbah added 3 commits February 4, 2026 15:49

Merge branch 'trunk' into fix/correct-see-usage

9ecf2f1

Fix malformed @link tags in WP_HTML_Tag_Processor

5792687

docs: Replace @see with @link for external URLs in PHPDoc comments.

aee5124

westonruter approved these changes Feb 4, 2026

View reviewed changes

Merge branch 'trunk' into fix/correct-see-usage

824e315

pento force-pushed the trunk branch from 3af2d27 to 64ede28 Compare July 6, 2026 03:10

westonruter mentioned this pull request Jul 9, 2026

HTML API: Update Processing Instruction handling #12424

Closed

huzaifaalmesbah added 4 commits July 16, 2026 08:29

Merge branch 'trunk' into fix/correct-see-usage

86149e0

Docs: Exclude bundled pomo library from @see -> @link conversion

9ceebca

The pomo/ directory is a bundled library, out of scope for this docs convention change. Restores the original @see in plural-forms.php.

Merge branch 'trunk' into fix/correct-see-usage

012c2c0

huzaifaalmesbah added 3 commits October 5, 2026 12:10

Merge remote-tracking branch 'upstream/trunk' into fix/correct-see-usage

ec7fd47

Docs: Exclude bundled blocks from @see -> @link conversion

7439782

The src/wp-includes/blocks/ directory is synced from Gutenberg packages and out of scope for core repo docs convention changes. Restores original @see tags to prevent build process failures.

Merge remote-tracking branch 'upstream/trunk' into fix/correct-see-usage

1c4cec8

# Conflicts: # src/wp-includes/global-styles-and-settings.php

westonruter and others added 3 commits October 16, 2026 20:59

westonruter and others added 6 commits October 16, 2026 21:00

Docs: Correct the Trac ticket URL path in password reset comments.

5cc8bc7

Trac ticket URLs use `/ticket/<number>`, not `/tickets/<number>`. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Docs: Keep the bundled pomo library out of the @link conversion.

34d1ddf

Restore the `@see` tag in `pomo/plural-forms.php`, which was converted despite the earlier decision to treat the pomo library as out of scope. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

westonruter mentioned this pull request Oct 17, 2026

HTML API: Use @link instead of @see for URL references #14370

Closed

westonruter closed this Oct 17, 2026

Navigation Menu

Repository navigation

Docs: Replace incorrect @see usage with @link - #10804

Docs: Replace incorrect @see usage with @link#10804
huzaifaalmesbah wants to merge 25 commits into
WordPress:trunkfrom
huzaifaalmesbah:fix/correct-see-usage

huzaifaalmesbah commented Jan 27, 2026 •

edited by westonruter

Loading

Uh oh!

github-actions Bot commented Jan 27, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Jan 27, 2026

Uh oh!

noruzzamans commented Jan 28, 2026

Uh oh!

shail-mehta left a comment

Uh oh!

westonruter commented Jan 31, 2026

Uh oh!

huzaifaalmesbah commented Jan 31, 2026

Uh oh!

westonruter commented Jul 16, 2026

Uh oh!

huzaifaalmesbah commented Jul 16, 2026

Uh oh!

huzaifaalmesbah commented Oct 17, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Conversation

huzaifaalmesbah commented Jan 27, 2026 • edited by westonruter Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Why this change?

When to use @link

Contrast with @see

Detailed changes

Uh oh!

github-actions Bot commented Jan 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Jan 27, 2026

Test using WordPress Playground

Some things to be aware of

Uh oh!

noruzzamans commented Jan 28, 2026

Uh oh!

shail-mehta left a comment

Choose a reason for hiding this comment

Uh oh!

westonruter commented Jan 31, 2026

Uh oh!

huzaifaalmesbah commented Jan 31, 2026

Uh oh!

westonruter commented Jul 16, 2026

Uh oh!

huzaifaalmesbah commented Jul 16, 2026

Uh oh!

huzaifaalmesbah commented Oct 17, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

huzaifaalmesbah commented Jan 27, 2026 •

edited by westonruter

Loading

When to use `@link`

Contrast with `@see`

github-actions Bot commented Jan 27, 2026 •

edited

Loading