HTML API: Correct and improve documentation issues.

Developed in #12043.

Props jonsurrell, westonruter, dmsnell.
See #64896.


git-svn-id: https://develop.svn.wordpress.org/trunk@62507 602fd350-edb4-49c9-b593-d223f7449a82

Author: sirreal

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' ) ) );
 	}