HTML API: Docs fixes by sirreal · Pull Request #36 · sirreal/wordpress-develop

sirreal · 2026-06-01T15:26:24Z

Trac ticket:

Use of AI Tools

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.

@return

…docblock. Corrects "How many node are" to "How many nodes are" in the @return description.

@return

Corrects "How many node are" to "How many nodes are" in the @return description.

Adds a comma after "erroneously match" so the introductory clause is properly separated from the following independent clause.

…cblock. Adds a comma after "failed" to separate the introductory clause from the following independent clause.

…lock. Adds the missing closing comma around the "like an IMG element" parenthetical phrase.

Adds commas to separate the conditions in the compound conditional describing when an empty string is returned.

…ock. Corrects "HTMl" to "HTML" in the Bookmarks section.

Removes the stray "the" in "This means that the it's not possible".

Corrects "do no exist" to "do not exist" in the Processing Instructions section.

Removes the duplicated "match" in the description of CSS selector matching.

Removes the stray "to" in the special atomic tag handling comment.

Corrects "Sorting avoid" to "Sorting avoids" in WP_HTML_Tag_Processor.

Corrects "are turn into" to "are turned into" in the funky comments description.

…se_tag_name(). Corrects two occurrences of "case-insentivity" to "case-insensitivity" in comments.

Corrects "unpected" to "unexpected" in the assertion message of test_unexpected_closing_tags_are_removed().

Corrects "Deprectated" to "Deprecated" in the inline comment next to BGSOUND.

Corrects two occurrences of "Processing instriction" to "Processing instruction" in the data provider for comment-as-PI tests.

…hen". Corrects two BUTTON-in-scope test docblocks where "what" should have been "that".

Corrects three occurrences of "BLOCKQOUTE" to "BLOCKQUOTE" in assertion messages for LI, DD, and DT closing tests.

Corrects "Compete" to "Complete" in the data provider key for incomplete-HTML seek tests, adjusting alignment to match.

…sages. Corrects two occurrences of "subesequent" to "subsequent" in the assertion messages of the remove_class() test.

Corrects "why" to "when" in the assertion message of a modifiable text transformation test.

gemini-code-assist

Code Review

This pull request consists entirely of minor typographical and grammatical corrections in the documentation blocks, inline comments, and test assertion messages across the WordPress HTML API codebase and its associated PHPUnit tests. No functional code changes were made. I have no additional feedback to provide.

- Clarify $value_starts_at describes a byte offset, not the value itself - Clarify constructor @param $value_start as a byte offset

- Fix broken class name in decode_text_node() example (WP_HTML_Decode -> WP_HTML_Decoder) - Fix broken class name in decode_attribute() example (WP_HTML_Decode -> WP_HTML_Decoder)

- Correct compatibility-mode alias: quirks mode is `BackCompat`, not `CSS1Compat`.

- set_pop_handler() docblock: "pushed item" -> "popped item" - at() docblock: clarify it returns the node, not the node's name

@return

- Correct bookmark_token() @return: method returns string or throws; never false. - Add missing @SInCE 6.7.0 to create_full_parser().

- Fix stale API: get_next_tag() -> next_tag() in paused_at_incomplete_token() example - Correct token_length arithmetic in $token_length property examples - Remove inaccurate sentence claiming Tag Processor only supports tag tokens in next_token() docblock - Fix broken example in subdivide_text_appropriately():  (DC3, non-whitespace) ->  (CR, whitespace) - Remove NOSCRIPT from special raw-text elements list in class docblock (Tag Processor descends into NOSCRIPT) - Fix spelling: NOFRAME -> NOFRAMES in class docblock special-elements list

@var

- Correct @var for $bookmark_name from string to string|null to match nullable property

@return

- Correct should_skip_test() @param names/types to match signature ($test_context_element, $test_name) - Update parse_html5_dat_testfile() @return description to reflect 4-element arrays (line number, context element, HTML, DOM)

- Fix variable name in XSS example (`$p` -> `$processor`) - Correct description of set_attribute escaping (does not call esc_attr)

Brings in 9 docblock correctness/staleness fixes from the docs-review-fix pipeline on top of the writing-quality pass.

sirreal · 2026-06-01T16:53:51Z

 	 *     $processor->next_tag();
 	 *     $processor->set_attribute('class', '" onclick="alert');
-	 *     echo $p;
+	 *     echo $processor;


This seems to work, although I expected echo $processor->get_updated_html();.

sirreal · 2026-06-01T17:09:30Z

+	 *     0123456789012345
+	 *     - token length is 15 - 0 = 15
 	 *
 	 *     a <!-- comment --> is a token.
 	 *     0123456789 123456789 123456789
-	 *     - token length is 17 - 2 = 15
+	 *     - token length is 18 - 2 = 16


This needs scrutiny.

This seems correct. The lengths do seem to correspond with the actual lengths.

sirreal · 2026-06-01T17:10:21Z

 *  - `TITLE` and `TEXTAREA` whose contents are treated as plaintext and then any
 *    character references are decoded. E.g. `1 &lt; 2 < 3` becomes `1 < 2 < 3`.
- *  - `IFRAME`, `NOSCRIPT`, `NOEMBED`, `NOFRAME`, `STYLE` whose contents are treated as
+ *  - `IFRAME`, `NOEMBED`, `NOFRAMES`, `STYLE` whose contents are treated as


Additional scrutiny.

Confirmed:

NOSCRIPT doesn't get special handling by the HTML API.

The correct element name is NOFRAMES (not NOFRAME).

sirreal · 2026-06-01T17:12:12Z

 	 * isn't UTF-8, first convert the document to UTF-8, then pass in the
 	 * converted HTML.
 	 *
+	 * @since 6.7.0


Yep.

https://make.wordpress.org/core/2024/10/17/updates-to-the-html-api-in-6-7/#a-full-parser-mode-in-the-html-processor

github-actions · 2026-06-01T17:15:01Z

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.

Unlinked Accounts

The following contributors have not linked their GitHub and WordPress.org accounts: @gemini-code-assist.

Contributors, please read how to link your accounts to ensure your work is properly credited in WordPress releases.

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

Props jonsurrell.

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

Copilot

Pull request overview

This PR focuses on improving the clarity and correctness of inline documentation and test descriptions for the HTML API, primarily through spelling/grammar fixes and more accurate PHPDoc wording.

Changes:

Corrects typos and wording in PHPUnit test messages, labels, and doc comments.
Clarifies HTML API PHPDoc for accuracy (types, terminology, examples, and behavioral descriptions).
Updates narrative documentation to better reflect actual escaping/token behavior.

Reviewed changes

Copilot reviewed 18 out of 18 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
tests/phpunit/tests/html-api/wpHtmlTagProcessorModifiableText.php	Fixes wording in an assertion message.
tests/phpunit/tests/html-api/wpHtmlTagProcessor.php	Corrects example output variable and updates escaping description text.
tests/phpunit/tests/html-api/wpHtmlTagProcessor-bookmark.php	Fixes a misspelled data-provider label.
tests/phpunit/tests/html-api/wpHtmlProcessorSemanticRulesListElements.php	Fixes “BLOCKQOUTE” typo in test expectation messages.
tests/phpunit/tests/html-api/wpHtmlProcessorSemanticRules.php	Fixes “Verifies what when …” phrasing in doc comments.
tests/phpunit/tests/html-api/wpHtmlProcessorHtml5lib.php	Improves PHPDoc for helper methods/data parsing descriptions.
tests/phpunit/tests/html-api/wpHtmlProcessorComments.php	Fixes “instriction” typo in data-provider labels.
tests/phpunit/tests/html-api/wpHtmlProcessorBreadcrumbs.php	Fixes “Deprectated” typo in an inline comment.
tests/phpunit/tests/html-api/wpHtmlProcessor.php	Fixes “case-insentivity” typos in comments.
tests/phpunit/tests/html-api/wpHtmlProcessor-serialize.php	Fixes “unpected” typo in an assertion message.
src/wp-includes/html-api/class-wp-html-token.php	Corrects PHPDoc type for nullable bookmark name.
src/wp-includes/html-api/class-wp-html-tag-processor.php	Corrects multiple documentation typos and refines explanatory examples.
src/wp-includes/html-api/class-wp-html-processor.php	Minor doc punctuation/wording improvements; adds missing `@since` for full-parser factory.
src/wp-includes/html-api/class-wp-html-open-elements.php	Fixes doc wording to match actual behavior/return types.
src/wp-includes/html-api/class-wp-html-doctype-info.php	Corrects quirks-mode compatMode wording to `BackCompat`.
src/wp-includes/html-api/class-wp-html-decoder.php	Fixes class name in examples (`WP_HTML_Decoder`).
src/wp-includes/html-api/class-wp-html-attribute-token.php	Corrects property/param documentation to reflect byte-offset semantics.
src/wp-includes/html-api/class-wp-html-active-formatting-elements.php	Fixes “node” → “nodes” grammar in return doc.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

sirreal · 2026-06-01T17:27:08Z

Code review

No issues found. Checked for bugs and CLAUDE.md compliance.

🤖 Generated with Claude Code

_{- If this code review was useful, please react with 👍. Otherwise, react with 👎.}

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

sirreal added 22 commits June 1, 2026 12:54

HTML API: Fix grammar in WP_HTML_Active_Formatting_Elements::count() …

e2ca83d

…docblock. Corrects "How many node are" to "How many nodes are" in the @return description.

HTML API: Fix grammar in WP_HTML_Open_Elements::count() docblock.

10fa6c9

Corrects "How many node are" to "How many nodes are" in the @return description.

HTML API: Add missing comma in WP_HTML_Processor class docblock.

cedb241

Adds a comma after "erroneously match" so the introductory clause is properly separated from the following independent clause.

HTML API: Add missing comma in WP_HTML_Processor::get_last_error() do…

40af083

…cblock. Adds a comma after "failed" to separate the introductory clause from the following independent clause.

HTML API: Fix punctuation in WP_HTML_Processor::expects_closer() docb…

ef2f483

…lock. Adds the missing closing comma around the "like an IMG element" parenthetical phrase.

HTML API: Fix punctuation in serialize_token() docblock.

4db0be7

Adds commas to separate the conditions in the compound conditional describing when an empty string is returned.

HTML API: Fix capitalization of "HTML" in WP_HTML_Tag_Processor docbl…

e292a93

…ock. Corrects "HTMl" to "HTML" in the Bookmarks section.

HTML API: Remove extra word in WP_HTML_Tag_Processor docblock.

91414a6

Removes the stray "the" in "This means that the it's not possible".

HTML API: Fix typo "do no exist" in WP_HTML_Tag_Processor docblock.

1ce6d3f

Corrects "do no exist" to "do not exist" in the Processing Instructions section.

HTML API: Remove duplicate word in QUIRKS_MODE description.

abfbfa0

Removes the duplicated "match" in the description of CSS selector matching.

HTML API: Fix typo "closing to tag" in WP_HTML_Tag_Processor.

7a14a38

Removes the stray "to" in the special atomic tag handling comment.

HTML API: Fix subject-verb agreement in replacement sorting comment.

50cd2f2

Corrects "Sorting avoid" to "Sorting avoids" in WP_HTML_Tag_Processor.

HTML API: Fix verb tense in funky comments docblock.

3d93924

Corrects "are turn into" to "are turned into" in the funky comments description.

Tests: HTML API: Fix typo "case-insentivity" in test_next_tag_lowerca…

b1e6c4a

…se_tag_name(). Corrects two occurrences of "case-insentivity" to "case-insensitivity" in comments.

Tests: HTML API: Fix typo "unpected" in serialize assertion.

98baee0

Corrects "unpected" to "unexpected" in the assertion message of test_unexpected_closing_tags_are_removed().

Tests: HTML API: Fix typo "Deprectated" in breadcrumbs test.

685c767

Corrects "Deprectated" to "Deprecated" in the inline comment next to BGSOUND.

Tests: HTML API: Fix typo "instriction" in comment test data.

220bef0

Corrects two occurrences of "Processing instriction" to "Processing instruction" in the data provider for comment-as-PI tests.

Tests: HTML API: Fix grammar "Verifies what when" to "Verifies that w…

e0a0e97

…hen". Corrects two BUTTON-in-scope test docblocks where "what" should have been "that".

Tests: HTML API: Fix typo "BLOCKQOUTE" in list element tests.

41f520b

Corrects three occurrences of "BLOCKQOUTE" to "BLOCKQUOTE" in assertion messages for LI, DD, and DT closing tests.

Tests: HTML API: Fix typo "Compete document" in bookmark test data.

ceebce8

Corrects "Compete" to "Complete" in the data provider key for incomplete-HTML seek tests, adjusting alignment to match.

Tests: HTML API: Fix typo "subesequent" in remove_class assertion mes…

96d81fe

…sages. Corrects two occurrences of "subesequent" to "subsequent" in the assertion messages of the remove_class() test.

Tests: HTML API: Fix grammar "why modifying" to "when modifying".

5a35fcf

Corrects "why" to "when" in the assertion message of a modifiable text transformation test.

gemini-code-assist Bot reviewed Jun 1, 2026

View reviewed changes

sirreal added 7 commits June 1, 2026 17:59

docs: fix src/wp-includes/html-api/class-wp-html-attribute-token.php

8b6b3e9

- Clarify $value_starts_at describes a byte offset, not the value itself - Clarify constructor @param $value_start as a byte offset

docs: fix src/wp-includes/html-api/class-wp-html-decoder.php

bc2ac1b

- Fix broken class name in decode_text_node() example (WP_HTML_Decode -> WP_HTML_Decoder) - Fix broken class name in decode_attribute() example (WP_HTML_Decode -> WP_HTML_Decoder)

docs: fix src/wp-includes/html-api/class-wp-html-doctype-info.php

2861d93

- Correct compatibility-mode alias: quirks mode is `BackCompat`, not `CSS1Compat`.

docs: fix src/wp-includes/html-api/class-wp-html-open-elements.php

d749176

- set_pop_handler() docblock: "pushed item" -> "popped item" - at() docblock: clarify it returns the node, not the node's name

docs: fix src/wp-includes/html-api/class-wp-html-processor.php

e10db88

- Correct bookmark_token() @return: method returns string or throws; never false. - Add missing @SInCE 6.7.0 to create_full_parser().

docs: fix src/wp-includes/html-api/class-wp-html-token.php

7ffb517

- Correct @var for $bookmark_name from string to string|null to match nullable property

sirreal added 3 commits June 1, 2026 17:59

docs: fix tests/phpunit/tests/html-api/wpHtmlTagProcessor.php

e65f38b

- Fix variable name in XSS example (`$p` -> `$processor`) - Correct description of set_attribute escaping (does not call esc_attr)

Merge branch 'html-api/docs-review-fix' into html-api/docs-fixes

9d9494b

Brings in 9 docblock correctness/staleness fixes from the docs-review-fix pipeline on top of the writing-quality pass.

sirreal commented Jun 1, 2026

View reviewed changes

Fix carriage return and line feed symbols

f3cab0d

sirreal requested a review from Copilot June 1, 2026 17:14

sirreal marked this pull request as ready for review June 1, 2026 17:14

Copilot started reviewing on behalf of sirreal June 1, 2026 17:14 View session

Copilot AI reviewed Jun 1, 2026

View reviewed changes

Comment thread tests/phpunit/tests/html-api/wpHtmlProcessorHtml5lib.php Outdated

sirreal and others added 2 commits June 1, 2026 21:46

Correct array|Generator type

251ace2

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Use preferred get_updated_html() method in docs

af2c0dc

sirreal mentioned this pull request Jun 1, 2026

HTML API: General documentation fixes WordPress/wordpress-develop#12043

Open

sirreal closed this Jun 1, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

HTML API: Docs fixes#36

HTML API: Docs fixes#36
sirreal wants to merge 35 commits into
trunkfrom
html-api/docs-fixes

sirreal commented Jun 1, 2026

Uh oh!

gemini-code-assist Bot left a comment

Uh oh!

sirreal Jun 1, 2026

Uh oh!

Uh oh!

sirreal Jun 1, 2026

Uh oh!

sirreal Jun 1, 2026

Uh oh!

sirreal Jun 1, 2026

Uh oh!

sirreal Jun 1, 2026

Uh oh!

sirreal Jun 1, 2026

Uh oh!

github-actions Bot commented Jun 1, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

sirreal commented Jun 1, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

sirreal commented Jun 1, 2026

Use of AI Tools

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

sirreal Jun 1, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

sirreal Jun 1, 2026

Choose a reason for hiding this comment

Uh oh!

sirreal Jun 1, 2026

Choose a reason for hiding this comment

Uh oh!

sirreal Jun 1, 2026

Choose a reason for hiding this comment

Uh oh!

sirreal Jun 1, 2026

Choose a reason for hiding this comment

Uh oh!

sirreal Jun 1, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot commented Jun 1, 2026

Unlinked Accounts

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

sirreal commented Jun 1, 2026

Code review

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants