From 0758a81a45af27cdcf73525e39b1dd871cad4c85 Mon Sep 17 00:00:00 2001 From: Jon Surrell Date: Mon, 29 Jun 2026 13:59:24 +0200 Subject: [PATCH] Docs: Clarify when to use the HTML Processor --- .../html-api/class-wp-html-tag-processor.php | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/src/wp-includes/html-api/class-wp-html-tag-processor.php b/src/wp-includes/html-api/class-wp-html-tag-processor.php index e41e1120550b5..d227844a49cb9 100644 --- a/src/wp-includes/html-api/class-wp-html-tag-processor.php +++ b/src/wp-includes/html-api/class-wp-html-tag-processor.php @@ -24,6 +24,17 @@ /** * Core class used to modify attributes in an HTML document for tags matching a query. * + * The Tag Processor scans an HTML document linearly and is designed for + * position-based work on individual tags: finding tags by name or class, + * reading and changing attributes, and preserving the rest of the input + * byte-for-byte. + * + * It does not track the parsed document tree. It provides no nesting depth, + * ancestor breadcrumbs, or guarantee that every opener is paired with a closer. + * Use {@see WP_HTML_Processor} when structure matters, such as checking whether + * one element is inside another, walking a subtree, collecting an element's text + * content, or working with implied closing tags the way a browser parser would. + * * ## Usage * * Use of this class requires three steps: