Improve comment about script tag contents

Author: sirreal

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

@@ -3726,14 +3726,31 @@ public function set_modifiable_text( string $plaintext_content ): bool {
 		switch ( $this->get_tag() ) {
 			case 'SCRIPT':
 				/*
-				 * This is over-protective, but ensures the update doesn't break
-				 * out of the SCRIPT element. A more thorough check would need to
-				 * ensure that the script closing tag doesn't exist, and isn't
-				 * also "hidden" inside the script double-escaped state.
+				 * SCRIPT tag contents can be dangerous.
 				 *
-				 * It may seem like replacing `</script` with `<\/script` would
-				 * properly escape these things, but this could mask regex patterns
-				 * that previously worked. Resolve this by not sending `</script`
+				 * The text `</script>` could close the SCRIPT element prematurely.
+				 *
+				 * The text `<script>` could enter the "script data double escaped state", preventing the
+				 * SCRIPT element from closing as expected, for example:
+				 *
+				 *     <script>
+				 *     // If this "<!--" then "<script>" the closing tag will not be recognized.
+				 *     </script>
+				 *     <h1>This appears inside the preceding SCRIPT element.</h1>
+				 *
+				 * The relevant state transitions happen on text like:
+				 *     1. <
+				 *     2. / (optional)
+				 *     3. script (case-insensitive)
+				 *     4. One of the following characters:
+				 *        - \t
+				 *        - \n
+				 *        - \f
+				 *        - " " (U+0020 SPACE)
+				 *        - /
+				 *        - >
+				 *
+				 * @see https://html.spec.whatwg.org/multipage/parsing.html#script-data-double-escaped-state
 				 */
 				if (
 					false !== stripos( $plaintext_content, '</script' ) ||