HTML API: General documentation fixes

src/wp-includes/html-api/class-wp-html-active-formatting-elements.php

@@ -67,7 +67,7 @@ public function contains_node( WP_HTML_Token $token ) {
 	 *
 	 * @since 6.4.0
 	 *
-	 * @return int How many node are in the stack of active formatting elements.
+	 * @return int How many nodes are in the stack of active formatting elements.
 	 */
 	public function count() {
 		return count( $this->stack );

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

@@ -32,7 +32,7 @@ class WP_HTML_Attribute_Token {
 	public $name;
 
 	/**
-	 * Attribute value.
+	 * Byte offset in the input HTML where the attribute value starts.
 	 *
 	 * @since 6.2.0
 	 *
@@ -101,7 +101,7 @@ class WP_HTML_Attribute_Token {
 	 * @since 6.5.0 Replaced `end` with `length` to more closely match `substr()`.
 	 *
 	 * @param string $name         Attribute name.
-	 * @param int    $value_start  Attribute value.
+	 * @param int    $value_start  Byte offset where the attribute value starts.
 	 * @param int    $value_length Number of bytes attribute value spans.
 	 * @param int    $start        The string offset where the attribute name starts.
 	 * @param int    $length       Byte length of the entire attribute name or name and value pair expression.

src/wp-includes/html-api/class-wp-html-decoder.php

@@ -83,7 +83,7 @@ public static function attribute_starts_with( $haystack, $search_text, $case_sen
 	 *
 	 * Example:
 	 *
-	 *     '“😄”' === WP_HTML_Decode::decode_text_node( '“😄&#x94' );
+	 *     '“😄”' === WP_HTML_Decoder::decode_text_node( '“😄&#x94' );
 	 *
 	 * @since 6.6.0
 	 *
@@ -103,7 +103,7 @@ public static function decode_text_node( $text ): string {
 	 *
 	 * Example:
 	 *
-	 *     '“😄”' === WP_HTML_Decode::decode_attribute( '“😄&#x94' );
+	 *     '“😄”' === WP_HTML_Decoder::decode_attribute( '“😄&#x94' );
 	 *
 	 * @since 6.6.0
 	 *

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

@@ -136,9 +136,12 @@ class WP_HTML_Doctype_Info {
 	 * (e.g. "quirks" or "no-quirks" mode), it will be inferred from the properties
 	 * of the appropriate DOCTYPE declaration, if one exists. The DOCTYPE can
 	 * indicate one of three possible document compatibility modes:
+	 * "no-quirks", "limited-quirks", or "quirks".
 	 *
-	 *  - "no-quirks" and "limited-quirks" modes (also called "standards" mode).
-	 *  - "quirks" mode (also called `CSS1Compat` mode).
+	 * Browsers expose the resulting document mode via `document.compatMode`:
+	 * - "BackCompat" indicates "quirks" mode.
+	 * - "CSS1Compat" indicates "no-quirks" or "limited-quirks" (these modes are not
+	 *   distinguished by `document.compatMode`).
 	 *
 	 * An appropriate DOCTYPE is one encountered in the "initial" insertion mode,
 	 * before the HTML element has been opened and before finding any other

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

@@ -78,7 +78,7 @@ class WP_HTML_Open_Elements {
 	 * Sets a pop handler that will be called when an item is popped off the stack of
 	 * open elements.
 	 *
-	 * The function will be called with the pushed item as its argument.
+	 * The function will be called with the popped item as its argument.
 	 *
 	 * @since 6.6.0
 	 *
@@ -103,7 +103,7 @@ public function set_push_handler( Closure $handler ): void {
 	}
 
 	/**
-	 * Returns the name of the node at the nth position on the stack
+	 * Returns the node at the nth position on the stack
 	 * of open elements, or `null` if no such position exists.
 	 *
 	 * Note that this uses a 1-based index, which represents the
@@ -114,7 +114,7 @@ public function set_push_handler( Closure $handler ): void {
 	 *
 	 * @param int $nth Retrieve the nth item on the stack, with 1 being
 	 *                 the top element, 2 being the second, etc...
-	 * @return WP_HTML_Token|null Name of the node on the stack at the given location,
+	 * @return WP_HTML_Token|null The node on the stack at the given location,
 	 *                            or `null` if the location isn't on the stack.
 	 */
 	public function at( int $nth ): ?WP_HTML_Token {
@@ -168,7 +168,7 @@ public function contains_node( WP_HTML_Token $token ): bool {
 	 *
 	 * @since 6.4.0
 	 *
-	 * @return int How many node are in the stack of open elements.
+	 * @return int How many nodes are in the stack of open elements.
 	 */
 	public function count(): int {
 		return count( $this->stack );

src/wp-includes/html-api/class-wp-html-processor.php

@@ -341,6 +341,8 @@ public static function create_fragment( $html, $context = '<body>', $encoding =
 	 * isn't UTF-8, first convert the document to UTF-8, then pass in the
 	 * converted HTML.
 	 *
+	 * @since 6.7.0
+	 *
 	 * @param string      $html                    Input HTML document to process.
 	 * @param string|null $known_definite_encoding Optional. If provided, specifies the charset used
 	 *                                             in the input byte stream. Currently must be UTF-8.
@@ -957,7 +959,7 @@ public function matches_breadcrumbs( $breadcrumbs ): bool {
 	 * token, or if it will self-close on the next step.
 	 *
 	 * Most HTML elements expect a closer, such as a P element or
-	 * a DIV element. Others, like an IMG element are void and don't
+	 * a DIV element. Others, like an IMG element, are void and don't
 	 * have a closing tag. Special elements, such as SCRIPT and STYLE,
 	 * are treated just like void tags. Text nodes and self-closing
 	 * foreign content will also act just like a void tag, immediately
@@ -5213,7 +5215,7 @@ private function step_in_foreign_content(): bool {
 	 *
 	 * @throws Exception When unable to allocate requested bookmark.
 	 *
-	 * @return string|false Name of created bookmark, or false if unable to create.
+	 * @return string Name of created bookmark.
 	 */
 	private function bookmark_token() {
 		if ( ! parent::set_bookmark( ++$this->bookmark_counter ) ) {

src/wp-includes/html-api/class-wp-html-tag-processor.php

@@ -213,7 +213,7 @@
  *
  * ### Bookmarks
  *
- * While scanning through the input HTMl document it's possible to set
+ * While scanning through the input HTML document it's possible to set
  * a named bookmark when a particular tag is found. Later on, after
  * continuing to scan other tags, it's possible to `seek` to one of
  * the set bookmarks and then proceed again from that point forward.
@@ -286,7 +286,7 @@
  *
  * For these elements the Tag Processor treats the entire sequence as one,
  * from the opening tag, including its contents, through its closing tag.
- * This means that the it's not possible to match the closing tag for a
+ * This means that it's not possible to match the closing tag for a
  * SCRIPT element unless it's unexpected; the Tag Processor already matched
  * it when it found the opening tag.
  *
@@ -298,7 +298,7 @@
  *    closing the SCRIPT from inside a JavaScript string. E.g. `console.log( '</script>' )`.
  *  - `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
  *    raw plaintext and left as-is. E.g. `1 &lt; 2 < 3` remains `1 &lt; 2 < 3`.
  *
  * #### Other tokens with modifiable text.
@@ -329,7 +329,7 @@
  *      and disallows "xml" as a name, since it's special. The Tag Processor only recognizes
  *      target names with an ASCII-representable subset of characters. It also exhibits the
  *      same constraint as with CDATA sections, in that `>` cannot exist within the token
- *      since Processing Instructions do no exist within HTML and their syntax transforms
+ *      since Processing Instructions do not exist within HTML and their syntax transforms
  *      into a bogus comment in the DOM.
  *
  * ## Design and limitations
@@ -521,7 +521,7 @@ class WP_HTML_Tag_Processor {
 	 *       - A TABLE start tag `<table>` implicitly closes any open `P` element.
 	 *
 	 *   - In `QUIRKS_MODE`:
-	 *       - CSS class and ID selectors match match in an ASCII case-insensitive manner.
+	 *       - CSS class and ID selectors match in an ASCII case-insensitive manner.
 	 *       - A TABLE start tag `<table>` opens a `TABLE` element as a child of a `P`
 	 *         element if one is open.
 	 *
@@ -614,12 +614,12 @@ class WP_HTML_Tag_Processor {
 	 * Example:
 	 *
 	 *     <div id="test">...
-	 *     012345678901234
-	 *     - token length is 14 - 0 = 14
+	 *     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
 	 *
 	 * @since 6.5.0
 	 *
@@ -926,8 +926,6 @@ public function next_tag( $query = null ): bool {
 	 *  - a DOCTYPE declaration.
 	 *  - a processing instruction, e.g. `<?xml version="1.0" ?>`.
 	 *
-	 * The Tag Processor currently only supports the tag token.
-	 *
 	 * @since 6.5.0
 	 * @since 6.7.0 Recognizes CDATA sections within foreign content.
 	 *
@@ -1073,7 +1071,7 @@ private function base_class_next_token(): bool {
 		 *
 		 * Preserve the opening tag pointers, as these will be overwritten
 		 * when finding the closing tag. They will be reset after finding
-		 * the closing to tag to point to the opening of the special atomic
+		 * the closing tag to point to the opening of the special atomic
 		 * tag sequence.
 		 */
 		$tag_name_starts_at   = $this->tag_name_starts_at;
@@ -1149,7 +1147,7 @@ private function base_class_next_token(): bool {
 	 * Example:
 	 *
 	 *     $processor = new WP_HTML_Tag_Processor( '<input type="text" value="Th' );
-	 *     false      === $processor->get_next_tag();
+	 *     false      === $processor->next_tag();
 	 *     true       === $processor->paused_at_incomplete_token();
 	 *
 	 * @since 6.5.0
@@ -2525,7 +2523,7 @@ private function apply_attributes_updates( int $shift_this_point ): int {
 		 * replacement must be made before all others which follow it
 		 * at later string indices in the input document.
 		 *
-		 * Sorting avoid making out-of-order replacements which
+		 * Sorting avoids making out-of-order replacements which
 		 * can lead to mangled output, partially-duplicated
 		 * attributes, and overwritten attributes.
 		 */
@@ -3561,9 +3559,9 @@ public function get_full_comment_text(): ?string {
 	 *     true  === $processor->next_token();                   // Text is "Apples & Oranges".
 	 *     false === $processor->subdivide_text_appropriately();
 	 *
-	 *     $processor = new WP_HTML_Tag_Processor( "&#x13; \r\n\tMore" );
-	 *     true  === $processor->next_token();                   // Text is "␤ ␤␉More".
-	 *     true  === $processor->subdivide_text_appropriately(); // Text is "␤ ␤␉".
+	 *     $processor = new WP_HTML_Tag_Processor( "&#xD; \r\n\tMore" );
+	 *     true  === $processor->next_token();                   // Text is "␍ ␊␉More".
+	 *     true  === $processor->subdivide_text_appropriately(); // Text is "␍ ␊␉".
 	 *     true  === $processor->next_token();                   // Text is "More".
 	 *     false === $processor->subdivide_text_appropriately();
 	 *
@@ -4941,7 +4939,7 @@ public function get_doctype_info(): ?WP_HTML_Doctype_Info {
 	 *     </2>
 	 *
 	 * Funky comments are tag closers with invalid tag names. Note
-	 * that in HTML these are turn into bogus comments. Nonetheless,
+	 * that in HTML these are turned into bogus comments. Nonetheless,
 	 * the Tag Processor recognizes them in a stream of HTML and
 	 * exposes them for inspection and modification.
 	 *

src/wp-includes/html-api/class-wp-html-token.php

@@ -29,7 +29,7 @@ class WP_HTML_Token {
 	 *
 	 * @since 6.4.0
 	 *
-	 * @var string
+	 * @var string|null
 	 */
 	public $bookmark_name = null;
 

tests/phpunit/tests/html-api/wpHtmlProcessor-serialize.php

@@ -261,7 +261,7 @@ public function test_unexpected_closing_tags_are_removed() {
 		$this->assertSame(
 			WP_HTML_Processor::normalize( 'one</div>two</span>three' ),
 			'onetwothree',
-			'Should have removed unpected closing tags.'
+			'Should have removed unexpected closing tags.'
 		);
 	}
 

tests/phpunit/tests/html-api/wpHtmlProcessor.php

@@ -1071,11 +1071,11 @@ public function test_ensure_next_token_method_extensibility( $html, $expected_to
 	 * @ticket 62427
 	 */
 	public function test_next_tag_lowercase_tag_name() {
-		// The upper case <DIV> is irrelevant but illustrates the case-insentivity.
+		// The upper case <DIV> is irrelevant but illustrates the case-insensitivity.
 		$processor = WP_HTML_Processor::create_fragment( '<section><DIV>' );
 		$this->assertTrue( $processor->next_tag( array( 'tag_name' => 'div' ) ) );
 
-		// The upper case <RECT> is irrelevant but illustrates the case-insentivity.
+		// The upper case <RECT> is irrelevant but illustrates the case-insensitivity.
 		$processor = WP_HTML_Processor::create_fragment( '<svg><RECT>' );
 		$this->assertTrue( $processor->next_tag( array( 'tag_name' => 'rect' ) ) );
 	}

tests/phpunit/tests/html-api/wpHtmlProcessorBreadcrumbs.php

@@ -49,7 +49,7 @@ public static function data_single_tag_of_supported_elements() {
 			'BASE',
 			'BDI',
 			'BDO',
-			'BGSOUND', // Deprectated.
+			'BGSOUND', // Deprecated.
 			'BIG',
 			'BLINK', // Deprecated.
 			'BR',

tests/phpunit/tests/html-api/wpHtmlProcessorComments.php

@@ -41,8 +41,8 @@ public static function data_comments() {
 			'Invalid HTML comment !'         => array( '<! Bang opener >', WP_HTML_Processor::COMMENT_AS_INVALID_HTML, ' Bang opener ' ),
 			'Invalid HTML comment ?'         => array( '<? Question opener >', WP_HTML_Processor::COMMENT_AS_INVALID_HTML, ' Question opener ' ),
 			'CDATA comment'                  => array( '<![CDATA[ cdata body ]]>', WP_HTML_Processor::COMMENT_AS_CDATA_LOOKALIKE, ' cdata body ' ),
-			'Processing instriction comment' => array( '<?pi-target Instruction body. ?>', WP_HTML_Processor::COMMENT_AS_PI_NODE_LOOKALIKE, ' Instruction body. ', 'pi-target' ),
-			'Processing instriction php'     => array( '<?php const HTML_COMMENT = true; ?>', WP_HTML_Processor::COMMENT_AS_PI_NODE_LOOKALIKE, ' const HTML_COMMENT = true; ', 'php' ),
+			'Processing instruction comment' => array( '<?pi-target Instruction body. ?>', WP_HTML_Processor::COMMENT_AS_PI_NODE_LOOKALIKE, ' Instruction body. ', 'pi-target' ),
+			'Processing instruction php'     => array( '<?php const HTML_COMMENT = true; ?>', WP_HTML_Processor::COMMENT_AS_PI_NODE_LOOKALIKE, ' const HTML_COMMENT = true; ', 'php' ),
 		);
 	}
 

tests/phpunit/tests/html-api/wpHtmlProcessorHtml5lib.php

@@ -132,8 +132,8 @@ public function data_external_html5lib_tests() {
 	/**
 	 * Determines whether a test case should be skipped.
 	 *
-	 * @param string $test_name     Test name.
-	 * @param string $expected_tree Expected HTML tree structure.
+	 * @param string|null $test_context_element Context element for fragment parsing, or null for full document parsing.
+	 * @param string      $test_name            Test name.
 	 *
 	 * @return bool True if the test case should be skipped. False otherwise.
 	 */
@@ -338,12 +338,16 @@ static function ( $a, $b ) {
 	}
 
 	/**
-	 * Convert a given Html5lib test file into a test triplet.
+	 * Convert a given Html5lib test file into a series of test cases.
 	 *
 	 * @param string $filename Path to `.dat` file with test cases.
 	 *
-	 * @return array|Generator Test triplets of HTML fragment context element,
-	 *                         HTML, and the DOM structure it represents.
+	 * @return Generator<int, array{
+	 *     non-negative-int, // Line number.
+	 *     string|null,      // HTML fragment context element.
+	 *     string,           // HTML.
+	 *     string,           // DOM structure it represents.
+	 * }> Test cases.
 	 */
 	public static function parse_html5_dat_testfile( $filename ) {
 		$handle = fopen( $filename, 'r', false );

tests/phpunit/tests/html-api/wpHtmlProcessorSemanticRules.php

@@ -163,7 +163,7 @@ public function test_in_body_button_with_no_button_in_scope() {
 	}
 
 	/**
-	 * Verifies what when inserting a BUTTON element, when a BUTTON is already in scope,
+	 * Verifies that when inserting a BUTTON element, when a BUTTON is already in scope,
 	 * that the open button is closed with all other elements inside of it.
 	 *
 	 * @ticket 58961
@@ -195,7 +195,7 @@ public function test_in_body_button_with_button_in_scope_as_parent() {
 	}
 
 	/**
-	 * Verifies what when inserting a BUTTON element, when a BUTTON is already in scope,
+	 * Verifies that when inserting a BUTTON element, when a BUTTON is already in scope,
 	 * that the open button is closed with all other elements inside of it, even if the
 	 * BUTTON in scope is not a direct parent of the new BUTTON element.
 	 *

tests/phpunit/tests/html-api/wpHtmlProcessorSemanticRulesListElements.php

@@ -94,7 +94,7 @@ public function test_in_body_li_generates_implied_end_tags_inside_open_li_but_st
 		$this->assertSame(
 			array( 'HTML', 'BODY', 'LI', 'BLOCKQUOTE', 'LI' ),
 			$processor->get_breadcrumbs(),
-			'LI should have left the BLOCKQOUTE open, but closed it.'
+			'LI should have left the BLOCKQUOTE open, but closed it.'
 		);
 	}
 
@@ -234,7 +234,7 @@ public function test_in_body_dd_generates_implied_end_tags_inside_open_dd_but_st
 		$this->assertSame(
 			array( 'HTML', 'BODY', 'DD', 'BLOCKQUOTE', 'DD' ),
 			$processor->get_breadcrumbs(),
-			'DD should have left the BLOCKQOUTE open, but closed it.'
+			'DD should have left the BLOCKQUOTE open, but closed it.'
 		);
 	}
 
@@ -370,7 +370,7 @@ public function test_in_body_dt_generates_implied_end_tags_inside_open_dt_but_st
 		$this->assertSame(
 			array( 'HTML', 'BODY', 'DT', 'BLOCKQUOTE', 'DT' ),
 			$processor->get_breadcrumbs(),
-			'DT should have left the BLOCKQOUTE open, but closed it.'
+			'DT should have left the BLOCKQUOTE open, but closed it.'
 		);
 	}
 

tests/phpunit/tests/html-api/wpHtmlTagProcessor-bookmark.php

@@ -518,7 +518,7 @@ public function test_can_seek_after_document_ends( $html_with_target_element ) {
 	 */
 	public static function data_incomplete_html_with_target_nodes_for_seeking() {
 		return array(
-			'Compete document'    => array( '<div><img target></div>' ),
+			'Complete document'   => array( '<div><img target></div>' ),
 			'Incomplete document' => array( '<div><img target></div' ),
 		);
 	}