Explain tests that were previously asserting invalid behaviors. (formatting)

dmsnell · dmsnell · commit 9e74bceced5d · 2025-10-21T01:32:34.000-07:00
diff --git a/tests/phpunit/tests/formatting/wpAutop.php b/tests/phpunit/tests/formatting/wpAutop.php
@@ -536,6 +536,15 @@ public function data_element_sanity() {
 				"Hello <![CDATA[ <!-- a\nhttps://youtu.be/jgz0uSaOZbE\n a\n9 ]]> -->",
 				"<p>Hello <![CDATA[ <!-- a\nhttps://youtu.be/jgz0uSaOZbE\n a\n9 ]]> --></p>\n",
 			),
+			/*
+			 * CDATA sections do not exist within HTML, so even though it looks
+			 * like this should be escaping the entire “inner comment” span, there’s
+			 * actually an invalid comment starting at `<![CDATA[` and ending at
+			 * the very first `>` character, placing the end of the comment at
+			 * what looks like the end of the “normal comment” — the ` -->`. Everything
+			 * afterward is normal HTML data so the `<br>` is a real `BR` element and
+			 * the `]]>` is normal plaintext, not the CDATA terminator.
+			 */
 			array(
 				"Hello <![CDATA[ <!-- a\nhttps://youtu.be/jgz0uSaOZbE\n a\n9 --> a\n9 ]]>",
 				"<p>Hello <![CDATA[ <!-- a\nhttps://youtu.be/jgz0uSaOZbE\n a\n9 --> a<br />\n9 ]]></p>\n",
diff --git a/tests/phpunit/tests/formatting/wpHtmlSplit.php b/tests/phpunit/tests/formatting/wpHtmlSplit.php
@@ -30,6 +30,13 @@ public function data_basic_features() {
 				'abcd <!-- <html> --> efgh',
 				array( 'abcd ', '<!-- <html> -->', ' efgh' ),
 			),
+			/*
+			 * CDATA sections do not exist within HTML, so even though it looks
+			 * like this should be escaping the entire ` <html> ` span, there’s
+			 * actually an invalid comment starting at `<![CDATA[` and ending at
+			 * the very first `>` character, placing the end of the comment at
+			 * the end of `html>`. The rest is normal plaintext content.
+			 */
 			array(
 				'abcd <![CDATA[ <html> ]]> efgh',
 				array( 'abcd ', '<![CDATA[ <html>', ' ]]> efgh' ),
