HTML API: Use @link instead of @see for URL references by westonruter · Pull Request #14370 · WordPress/wordpress-develop

westonruter · 2026-10-17T04:48:04Z

✅ Committed in r64636 (bfc5008).

This splits the HTML API changes out of #10804 so they can be reviewed separately by the HTML API maintainers.

The WordPress PHP Documentation Standards reserve @see for references to code elements (functions, methods, classes, hooks) and @link for URLs. Generic PHPDoc does allow a URI in @see (phpDocumentor defines it as @see [URI | FQSEN]), so these usages are not invalid PHPDoc, but they are non-standard for WordPress. The same conversion was previously committed for WP_Site_Icon in r63569.

Changes in src/wp-includes/html-api/ and the HTML API tests:

Every @see tag pointing to a URL, such as a section of the HTML Standard, is converted to @link.
Where a converted @link ended up above an @see tag, the two are swapped so @see comes first, per the documentation standards.
Spec references that appear in the middle of prose use the inline {@link URL} form, since a tag is only recognized at the start of a line and a block-level tag ends the description. This applies to the bulleted list in WP_HTML_Tag_Processor and to the WP_HTML_Doctype_Info class description, which was previously cut short at the first reference.

The first commit carries the HTML API portion of the original commits by @huzaifaalmesbah from #10804, applied on top of the current trunk.

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

Use of AI Tools

AI assistance: Yes
Tool(s): Claude Code
Model(s): Claude Opus 5.5
Used for: Reviewing #10804, the follow-up fixes to tag order and inline links, splitting out the HTML API changes into this branch, and drafting this description; reviewed by me.

This Pull Request is for code review only. Please keep all other discussion in the Trac ticket. Do not merge this Pull Request. See GitHub Pull Requests for Code Review in the Core Handbook for more details.

🤖 Generated with Claude Code

Convert `@see URL` references to external resources, such as the HTML Standard, to `@link` in the HTML API classes. This combines the HTML API portions of the commits from WordPress#10804, made against an older trunk, into one commit applied on top of the current trunk.

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>

@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 in the HTML API tests and test helpers. 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>

github-actions · 2026-10-17T04:49:13Z

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, jonsurrell, rejaulalomkhan.

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

github-actions · 2026-10-17T04:52:01Z

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

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.

rejaulalomkhan

Looks good! Tested locally against trunk and verified the html-api tests pass cleanly.

sirreal

This looks good, I left a question in one place where I don't understand why enclosing {} were added.

In r64436 the `@see` tags pointing to URLs were converted to `@link` across core, since the WordPress inline documentation standards reserve `@see` for references to functions, methods, classes, and hooks. The HTML API was split out of that change so that it could be reviewed by the component's maintainers, and its references to the HTML Standard and other specifications are now converted as well, in both the classes and their tests. Where both tags appear, `@see` is kept ahead of `@link`, per the standards. Spec references within prose or a list use the inline `{@link}` form instead, since a tag is only recognized at the start of a line and a block-level tag ends the description. In `WP_HTML_Doctype_Info` this had cut the class description short at its first reference, so that the Code Reference rendered the paragraphs after it as the link's text. Those references are now worked into the prose with descriptive link text. Developed in #14370. Follow-up to r63569, r64436. Props huzaifaalmesbah, westonruter, jonsurrell, rejaulalomkhan. See #65860. git-svn-id: https://develop.svn.wordpress.org/trunk@64636 602fd350-edb4-49c9-b593-d223f7449a82

In r64436 the `@see` tags pointing to URLs were converted to `@link` across core, since the WordPress inline documentation standards reserve `@see` for references to functions, methods, classes, and hooks. The HTML API was split out of that change so that it could be reviewed by the component's maintainers, and its references to the HTML Standard and other specifications are now converted as well, in both the classes and their tests. Where both tags appear, `@see` is kept ahead of `@link`, per the standards. Spec references within prose or a list use the inline `{@link}` form instead, since a tag is only recognized at the start of a line and a block-level tag ends the description. In `WP_HTML_Doctype_Info` this had cut the class description short at its first reference, so that the Code Reference rendered the paragraphs after it as the link's text. Those references are now worked into the prose with descriptive link text. Developed in WordPress/wordpress-develop#14370. Follow-up to r63569, r64436. Props huzaifaalmesbah, westonruter, jonsurrell, rejaulalomkhan. See #65860. Built from https://develop.svn.wordpress.org/trunk@64636 git-svn-id: http://core.svn.wordpress.org/trunk@63786 1a063a9b-81f0-0310-95a4-ce76da25c4cd

dmsnell · 2026-10-21T23:14:11Z

- *
- * @see https://html.spec.whatwg.org/#the-initial-insertion-mode
+ * hadn't already determined it from other information. The HTML parser's
+ * {@link https://html.spec.whatwg.org/#the-initial-insertion-mode initial insertion mode}


What are your thoughts on how these interrupt the flow of the sentences with links? I know that on the rendered docs it will be an inline link, but here in the code where people will be working, the impact is different.

I don't mind it in this case:

LSP/IDE's probably handle this better

Docs will be better

I don't find the literal lines of code comments significantly worse.

huzaifaalmesbah and others added 5 commits October 16, 2026 21:46

HTML API: Replace remaining @see tags for URLs with @link in tests.

8506feb

Convert the `@see URL` references the earlier sweep missed in the HTML API tests and test helpers. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

westonruter marked this pull request as ready for review October 17, 2026 04:49

westonruter requested a review from dmsnell October 17, 2026 04:49

westonruter requested a review from sirreal October 17, 2026 04:49

westonruter mentioned this pull request Oct 17, 2026

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

Closed

rejaulalomkhan approved these changes Oct 17, 2026

View reviewed changes

sirreal approved these changes Oct 19, 2026

View reviewed changes

Comment thread src/wp-includes/html-api/class-wp-html-doctype-info.php Outdated

Integrate links in docblock prose

8e655d9

westonruter closed this Oct 20, 2026

dmsnell reviewed Oct 21, 2026

View reviewed changes

Navigation Menu

Repository navigation

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

HTML API: Use @link instead of @see for URL references#14370
westonruter wants to merge 6 commits into
WordPress:trunkfrom
westonruter:fix/html-api-see-link-usage

westonruter commented Oct 17, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Oct 17, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Oct 17, 2026

Uh oh!

rejaulalomkhan left a comment •

edited

Loading

Uh oh!

sirreal left a comment

Uh oh!

Uh oh!

dmsnell Oct 21, 2026

Uh oh!

sirreal Oct 22, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Conversation

westonruter commented Oct 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Use of AI Tools

Uh oh!

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

Uh oh!

Uh oh!

github-actions Bot commented Oct 17, 2026

Test using WordPress Playground

Some things to be aware of

Uh oh!

rejaulalomkhan left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sirreal left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

dmsnell Oct 21, 2026

Choose a reason for hiding this comment

Uh oh!

sirreal Oct 22, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

westonruter commented Oct 17, 2026 •

edited

Loading

github-actions Bot commented Oct 17, 2026 •

edited

Loading

rejaulalomkhan left a comment •

edited

Loading