Add docblocks to tests, expand comments in class docblock.

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

@@ -105,7 +105,7 @@
  *  - Formatting elements: B, BIG, CODE, EM, FONT, I, SMALL, STRIKE, STRONG, TT, U.
  *  - Heading elements: H1, H2, H3, H4, H5, H6, HGROUP.
  *  - Links: A.
- *  - Lists: DL.
+ *  - Lists: DD, DL, DT, LI, OL, LI.
  *  - Media elements: AUDIO, CANVAS, FIGCAPTION, FIGURE, IMG, MAP, PICTURE, VIDEO.
  *  - Paragraph: P.
  *  - Phrasing elements: ABBR, BDI, BDO, CITE, DATA, DEL, DFN, INS, MARK, OUTPUT, Q, SAMP, SUB, SUP, TIME, VAR.

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

@@ -227,7 +227,7 @@ public function test_in_body_button_with_button_in_scope_as_ancestor() {
 	/**
 	 * Verifies that H1 through H6 elements close an open P element.
 	 *
-	 * @ticket {TICKET_NUMBER}
+	 * @ticket 60215
 	 *
 	 * @dataProvider data_heading_elements
 	 *
@@ -272,6 +272,8 @@ public function data_heading_elements() {
 	/**
 	 * Verifies that H1 through H6 elements close an open H1 through H6 element.
 	 *
+	 * @ticket 60215
+	 *
 	 * @dataProvider data_heading_combinations
 	 *
 	 * @param string $first_heading  H1 - H6 element appearing (unclosed) before the second.

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

@@ -1,7 +1,7 @@
 <?php
 /**
  * Unit tests covering WP_HTML_Processor compliance with HTML5 semantic parsing rules
- * for the LI list item element.
+ * for the list elements, including DD, DL, DT, LI, OL, and UL.
  *
  * @package WordPress
  * @subpackage HTML-API
@@ -16,6 +16,12 @@ class Tests_HtmlApi_WpHtmlProcessorSemanticRulesListElements extends WP_UnitTest
 	/*******************************************************************
 	 * RULES FOR "IN BODY" MODE
 	 *******************************************************************/
+
+	/**
+	 * Ensures that an opening LI element implicitly closes an open LI element.
+	 *
+	 * @ticket 60215
+	 */
 	public function test_in_body_li_closes_open_li() {
 		$processor = WP_HTML_Processor::create_fragment( '<li><li><li target>' );
 
@@ -38,6 +44,11 @@ public function test_in_body_li_closes_open_li() {
 		);
 	}
 
+	/**
+	 * Ensures that an opening LI element implicitly closes other open elements with optional closing tags.
+	 *
+	 * @ticket 60215
+	 */
 	public function test_in_body_li_generates_implied_end_tags_inside_open_li() {
 		$processor = WP_HTML_Processor::create_fragment( '<li><li><div><li target>' );
 
@@ -60,6 +71,11 @@ public function test_in_body_li_generates_implied_end_tags_inside_open_li() {
 		);
 	}
 
+	/**
+	 * Ensures that when closing tags with optional tag closers, an opening LI tag doesn't close beyond a special boundary.
+	 *
+	 * @ticket 60215
+	 */
 	public function test_in_body_li_generates_implied_end_tags_inside_open_li_but_stopping_at_special_tags() {
 		$processor = WP_HTML_Processor::create_fragment( '<li><li><blockquote><li target>' );
 
@@ -82,6 +98,11 @@ public function test_in_body_li_generates_implied_end_tags_inside_open_li_but_st
 		);
 	}
 
+	/**
+	 * Ensures that an opening LI closes an open P in button scope.
+	 *
+	 * @ticket 60215
+	 */
 	public function test_in_body_li_in_li_closes_p_in_button_scope() {
 		$processor = WP_HTML_Processor::create_fragment( '<li><li><p><button><p><li target>' );
 
@@ -104,6 +125,13 @@ public function test_in_body_li_in_li_closes_p_in_button_scope() {
 		);
 	}
 
+	/**
+	 * Ensures that an opening DD closes an open DD element.
+	 *
+	 * Note that a DD closes an open DD and also an open DT.
+	 *
+	 * @ticket 60215
+	 */
 	public function test_in_body_dd_closes_open_dd() {
 		$processor = WP_HTML_Processor::create_fragment( '<dd><dd><dd target>' );
 
@@ -126,6 +154,13 @@ public function test_in_body_dd_closes_open_dd() {
 		);
 	}
 
+	/**
+	 * Ensures that an opening DD closes an open DT element.
+	 *
+	 * Note that a DD closes an open DD and also an open DT.
+	 *
+	 * @ticket 60215
+	 */
 	public function test_in_body_dd_closes_open_dt() {
 		$processor = WP_HTML_Processor::create_fragment( '<dt><dt><dd target>' );
 
@@ -148,7 +183,12 @@ public function test_in_body_dd_closes_open_dt() {
 		);
 	}
 
-	public function test_in_body_dd_generates_impdded_end_tags_inside_open_dd() {
+	/**
+	 * Ensures that an opening DD implicitly closes open elements with optional closing tags.
+	 *
+	 * @ticket 60215
+	 */
+	public function test_in_body_dd_generates_implied_end_tags_inside_open_dd() {
 		$processor = WP_HTML_Processor::create_fragment( '<dd><dd><div><dd target>' );
 
 		while (
@@ -170,7 +210,13 @@ public function test_in_body_dd_generates_impdded_end_tags_inside_open_dd() {
 		);
 	}
 
-	public function test_in_body_dd_generates_impdded_end_tags_inside_open_dd_but_stopping_at_special_tags() {
+	/**
+	 * Ensures that an opening DD implicitly closes open elements with optional closing tags,
+	 * but doesn't close beyond a special boundary.
+	 *
+	 * @ticket 60215
+	 */
+	public function test_in_body_dd_generates_implied_end_tags_inside_open_dd_but_stopping_at_special_tags() {
 		$processor = WP_HTML_Processor::create_fragment( '<dd><dd><blockquote><dd target>' );
 
 		while (
@@ -192,6 +238,11 @@ public function test_in_body_dd_generates_impdded_end_tags_inside_open_dd_but_st
 		);
 	}
 
+	/**
+	 * Ensures that an opening DD inside a DD closes a P in button scope.
+	 *
+	 * @ticket 60215
+	 */
 	public function test_in_body_dd_in_dd_closes_p_in_button_scope() {
 		$processor = WP_HTML_Processor::create_fragment( '<dd><dd><p><button><p><dd target>' );
 
@@ -214,6 +265,11 @@ public function test_in_body_dd_in_dd_closes_p_in_button_scope() {
 		);
 	}
 
+	/**
+	 * Ensures that an opening DT closes an open DT element.
+	 *
+	 * @ticket 60215
+	 */
 	public function test_in_body_dt_closes_open_dt() {
 		$processor = WP_HTML_Processor::create_fragment( '<dt><dt><dt target>' );
 
@@ -236,6 +292,11 @@ public function test_in_body_dt_closes_open_dt() {
 		);
 	}
 
+	/**
+	 * Ensures that an opening DT closes an open DD.
+	 *
+	 * @ticket 60215
+	 */
 	public function test_in_body_dt_closes_open_dd() {
 		$processor = WP_HTML_Processor::create_fragment( '<dd><dd><dt target>' );
 
@@ -258,7 +319,12 @@ public function test_in_body_dt_closes_open_dd() {
 		);
 	}
 
-	public function test_in_body_dt_generates_impdted_end_tags_inside_open_dt() {
+	/**
+	 * Ensures that an opening DT implicitly closes open elements with optional closing tags.
+	 *
+	 * @ticket 60215
+	 */
+	public function test_in_body_dt_generates_implied_end_tags_inside_open_dt() {
 		$processor = WP_HTML_Processor::create_fragment( '<dt><dt><div><dt target>' );
 
 		while (
@@ -280,7 +346,13 @@ public function test_in_body_dt_generates_impdted_end_tags_inside_open_dt() {
 		);
 	}
 
-	public function test_in_body_dt_generates_impdted_end_tags_inside_open_dt_but_stopping_at_special_tags() {
+	/**
+	 * Ensures that an opening DT implicitly closes open elements with optional closing tags,
+	 * but doesn't close beyond a special boundary.
+	 *
+	 * @ticket 60215
+	 */
+	public function test_in_body_dt_generates_implied_end_tags_inside_open_dt_but_stopping_at_special_tags() {
 		$processor = WP_HTML_Processor::create_fragment( '<dt><dt><blockquote><dt target>' );
 
 		while (
@@ -302,6 +374,11 @@ public function test_in_body_dt_generates_impdted_end_tags_inside_open_dt_but_st
 		);
 	}
 
+	/**
+	 * Ensures that an opening DT inside a DT closes a P in button scope.
+	 *
+	 * @ticket 60215
+	 */
 	public function test_in_body_dt_in_dt_closes_p_in_button_scope() {
 		$processor = WP_HTML_Processor::create_fragment( '<dt><dt><p><button><p><dt target>' );
 
@@ -324,6 +401,12 @@ public function test_in_body_dt_in_dt_closes_p_in_button_scope() {
 		);
 	}
 
+	/**
+	 * Ensures that an unexpected LI doesn't close more elements than it should, that it doesn't
+	 * close open LI elements that are beyond a special element (in this case, the UL).
+	 *
+	 * @ticket 60215
+	 */
 	public function test_unexpected_li_close_tag_is_properly_contained() {
 		$processor = WP_HTML_Processor::create_fragment( '<ul><li><ul></li><li target>a</li></ul></li></ul>' );