HTML API: General documentation fixes#12043
Closed
sirreal wants to merge 44 commits into
Closed
Conversation
…docblock. Corrects "How many node are" to "How many nodes are" in the @return description.
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.
- 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
- 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
- Correct @var for $bookmark_name from string to string|null to match nullable property
- 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.
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
|
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 Core Committers: Use this line as a base for the props when committing in SVN: To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook. |
Test using WordPress PlaygroundThe 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
For more details about these limitations and more, check out the Limitations page in the WordPress Playground documentation. |
westonruter
approved these changes
Jun 9, 2026
westonruter
left a comment
westonruter
left a comment
Member
There was a problem hiding this comment.
Suggestion for richer Generator typing, but otherwise looks good.
dmsnell
reviewed
Jun 10, 2026
| * Various situations lead to parsing failure but this class will | ||
| * return `false` in all those cases. To determine why something | ||
| * failed it's possible to request the last error. This can be | ||
| * failed, it's possible to request the last error. This can be |
Member
There was a problem hiding this comment.
these are all stylistic choices I disagree with, but the proposed over-use of the comma is quite common and that’s fine 🤷♂️. grammar checkers like to alert on these and it will probably be an uphill battle against language-use competing against the machines and their systems of rules, so whatever.
Member
Author
There was a problem hiding this comment.
I'm happy to get these rolled-back.
| * ``` | ||
| * | ||
| * To prevent it, `set_attribute` calls `esc_attr()` on its given values. | ||
| * To prevent it, `set_attribute` escapes dangerous characters (`"`, `'`, `<`, `>`, `&`) using HTML character references. |
Member
There was a problem hiding this comment.
these are not "dangerous" characters and I try to avoid that terminology so that it doesn’t spread misunderstanding. how about "escapes syntax characters" instead?
Co-authored-by: Weston Ruter <westonruter@gmail.com>
sirreal
commented
Jun 16, 2026
| * isn't UTF-8, first convert the document to UTF-8, then pass in the | ||
| * converted HTML. | ||
| * | ||
| * @since 6.7.0 |
Member
Author
There was a problem hiding this comment.
pento
pushed a commit
that referenced
this pull request
Jun 16, 2026
Developed in #12043. Props jonsurrell, westonruter, dmsnell. See #64896. git-svn-id: https://develop.svn.wordpress.org/trunk@62507 602fd350-edb4-49c9-b593-d223f7449a82
markjaquith
pushed a commit
to markjaquith/WordPress
that referenced
this pull request
Jun 16, 2026
Developed in WordPress/wordpress-develop#12043. Props jonsurrell, westonruter, dmsnell. See #64896. Built from https://develop.svn.wordpress.org/trunk@62507 git-svn-id: http://core.svn.wordpress.org/trunk@61788 1a063a9b-81f0-0310-95a4-ce76da25c4cd
Member
Author
|
Merged in r62507. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Apply many documentation fixes across the HTML API. Changes include a wide range of issues from typos, mistakes, punctuation, grammar, and simple inaccuracies.
AI discovered and implemented corrections. All changes have been reviewed by me.
Trac ticket: https://core.trac.wordpress.org/ticket/64896
Use of AI Tools
AI assistance: Yes
Tool(s): Claude (primary). Codex and GitHub Copilot for review.
Used for: Detecting and applying corrections. Review.