From e2eee290905b99e3266657697d6711602d23d762 Mon Sep 17 00:00:00 2001
From: Jon Surrell <sirreal@users.noreply.github.com>
Date: Sun, 21 Jan 2024 21:06:59 +0100
Subject: [PATCH] Fix up insertion mode constants

---
 .../class-wp-html-processor-state.php         | 96 +++++++++++++++++--
 1 file changed, 90 insertions(+), 6 deletions(-)

diff --git a/src/wp-includes/html-api/class-wp-html-processor-state.php b/src/wp-includes/html-api/class-wp-html-processor-state.php
index 0245046e56ae8..f72b6ebd765c9 100644
--- a/src/wp-includes/html-api/class-wp-html-processor-state.php
+++ b/src/wp-includes/html-api/class-wp-html-processor-state.php
@@ -60,27 +60,111 @@ class WP_HTML_Processor_State {
 	const INSERTION_MODE_IN_BODY = 'insertion-mode-in-body';
 
 	/**
-	 * In body insertion mode for full HTML parser.
+	 * In select insertion mode for full HTML parser.
 	 *
 	 * @since 6.5.0
 	 *
-	 * @todo clean this up
-	 *
-	 * @see https://html.spec.whatwg.org/#parsing-main-inbody
+	 * @see https://html.spec.whatwg.org/#parsing-main-inselect
 	 * @see WP_HTML_Processor_State::$insertion_mode
 	 *
-	 * If the insertion mode is one of "in table", "in caption", "in table body", "in row", or "in cell", then switch the insertion mode to "in select in table". Otherwise, switch the insertion mode to "in select".
-	 *
 	 * @var string
 	 */
 	const INSERTION_MODE_IN_SELECT = 'insertion-mode-in-select';
+
+	/**
+	 * In select in table insertion mode for full HTML parser.
+	 *
+	 * @since 6.5.0
+	 *
+	 * @see https://html.spec.whatwg.org/#parsing-main-inselectintable
+	 * @see WP_HTML_Processor_State::$insertion_mode
+	 *
+	 * @var string
+	 */
 	const INSERTION_MODE_IN_SELECT_IN_TABLE = 'insertion-mode-in-select-in-table';
+
+	/**
+	 * In table insertion mode for full HTML parser.
+	 *
+	 * @since 6.5.0
+	 *
+	 * @see https://html.spec.whatwg.org/#parsing-main-intable
+	 * @see WP_HTML_Processor_State::$insertion_mode
+	 *
+	 * @var string
+	 */
 	const INSERTION_MODE_IN_TABLE = 'insertion-mode-in-table';
+
+	/**
+	 * In caption insertion mode for full HTML parser.
+	 *
+	 * @since 6.5.0
+	 *
+	 * @see https://html.spec.whatwg.org/#parsing-main-incaption
+	 * @see WP_HTML_Processor_State::$insertion_mode
+	 *
+	 * @var string
+	 */
 	const INSERTION_MODE_IN_CAPTION = 'insertion-mode-in-caption';
+
+	/**
+	 * In table body insertion mode for full HTML parser.
+	 *
+	 * @since 6.5.0
+	 *
+	 * @see https://html.spec.whatwg.org/#parsing-main-intablebody
+	 * @see WP_HTML_Processor_State::$insertion_mode
+	 *
+	 * @var string
+	 */
 	const INSERTION_MODE_IN_TABLE_BODY = 'insertion-mode-in-table-body';
+
+	/**
+	 * In row insertion mode for full HTML parser.
+	 *
+	 * @since 6.5.0
+	 *
+	 * @see https://html.spec.whatwg.org/#parsing-main-inrow
+	 * @see WP_HTML_Processor_State::$insertion_mode
+	 *
+	 * @var string
+	 */
 	const INSERTION_MODE_IN_ROW = 'insertion-mode-in-row';
+
+	/**
+	 * In cell insertion mode for full HTML parser.
+	 *
+	 * @since 6.5.0
+	 *
+	 * @see https://html.spec.whatwg.org/#parsing-main-incell
+	 * @see WP_HTML_Processor_State::$insertion_mode
+	 *
+	 * @var string
+	 */
 	const INSERTION_MODE_IN_CELL = 'insertion-mode-in-cell';
+
+	/**
+	 * In column group insertion mode for full HTML parser.
+	 *
+	 * @since 6.5.0
+	 *
+	 * @see https://html.spec.whatwg.org/#parsing-main-incolumngroup
+	 * @see WP_HTML_Processor_State::$insertion_mode
+	 *
+	 * @var string
+	 */
 	const INSERTION_MODE_IN_COLUMN_GROUP = 'insertion-mode-in-column-group';
+
+	/**
+	 * In frameset insertion mode for full HTML parser.
+	 *
+	 * @since 6.5.0
+	 *
+	 * @see https://html.spec.whatwg.org/#parsing-main-inframeset
+	 * @see WP_HTML_Processor_State::$insertion_mode
+	 *
+	 * @var string
+	 */
 	const INSERTION_MODE_IN_FRAMESET = 'insertion-mode-in-frameset';
 
 	/**