From e193621d28344a1ecc8f6d9ee61927bb5460e91c Mon Sep 17 00:00:00 2001
From: Jon Surrell <sirreal@users.noreply.github.com>
Date: Wed, 11 Dec 2024 19:20:45 +0100
Subject: [PATCH] Fix up some todo-s

---
 .../class-wp-css-complex-selector-list.php    |  8 --------
 .../class-wp-css-compound-selector-list.php   | 14 ++++++--------
 .../class-wp-css-selector-parser-matcher.php  | 19 ++++++++++++++-----
 3 files changed, 20 insertions(+), 21 deletions(-)

diff --git a/src/wp-includes/html-api/class-wp-css-complex-selector-list.php b/src/wp-includes/html-api/class-wp-css-complex-selector-list.php
index 10af613174a35..940bd098c6c19 100644
--- a/src/wp-includes/html-api/class-wp-css-complex-selector-list.php
+++ b/src/wp-includes/html-api/class-wp-css-complex-selector-list.php
@@ -44,14 +44,6 @@ class WP_CSS_Complex_Selector_List extends WP_CSS_Compound_Selector_List {
 	 * @return static|null The selector instance, or null if the parse was unsuccessful.
 	 */
 	public static function parse( string $input, int &$offset ): ?static {
-		$input = self::normalize_selector_input( $input );
-
-		if ( '' === $input ) {
-			return null;
-		}
-
-		$offset = 0;
-
 		$selector = WP_CSS_Complex_Selector::parse( $input, $offset );
 		if ( null === $selector ) {
 			return null;
diff --git a/src/wp-includes/html-api/class-wp-css-compound-selector-list.php b/src/wp-includes/html-api/class-wp-css-compound-selector-list.php
index a6f3b87409ff6..7edafc779ac4c 100644
--- a/src/wp-includes/html-api/class-wp-css-compound-selector-list.php
+++ b/src/wp-includes/html-api/class-wp-css-compound-selector-list.php
@@ -122,6 +122,12 @@ protected function __construct( array $selectors ) {
 	 * @return static|null
 	 */
 	public static function from_selectors( string $input ): ?static {
+		$input = self::normalize_selector_input( $input );
+
+		if ( '' === $input ) {
+			return null;
+		}
+
 		$offset = 0;
 		return static::parse( $input, $offset );
 	}
@@ -137,14 +143,6 @@ public static function from_selectors( string $input ): ?static {
 	 * @return static|null The selector instance, or null if the parse was unsuccessful.
 	 */
 	public static function parse( string $input, int &$offset ): ?static {
-		$input = self::normalize_selector_input( $input );
-
-		if ( '' === $input ) {
-			return null;
-		}
-
-		$offset = 0;
-
 		$selector = WP_CSS_Compound_Selector::parse( $input, $offset );
 		if ( null === $selector ) {
 			return null;
diff --git a/src/wp-includes/html-api/class-wp-css-selector-parser-matcher.php b/src/wp-includes/html-api/class-wp-css-selector-parser-matcher.php
index 60e75820c264a..6d665c4c26cb0 100644
--- a/src/wp-includes/html-api/class-wp-css-selector-parser-matcher.php
+++ b/src/wp-includes/html-api/class-wp-css-selector-parser-matcher.php
@@ -46,7 +46,12 @@ abstract public static function parse( string $input, int &$offset ): ?static;
 	 */
 
 	/**
-	 * @todo document
+	 * Consumes whitespace from the input string.
+	 *
+	 * @param string $input The selector string.
+	 * @param int    $offset The offset into the string. The offset is passed by reference and will
+	 *                       be update to the byte after the whitespace sequence.
+	 * @return bool True if whitespace was consumed.
 	 */
 	final protected static function parse_whitespace( string $input, int &$offset ): bool {
 		$length   = strspn( $input, self::WHITESPACE_CHARACTERS, $offset );
@@ -289,7 +294,6 @@ final protected static function parse_ident( string $input, int &$offset ): ?str
 				$ident .= self::consume_escaped_codepoint( $input, $offset );
 				continue;
 			} elseif ( self::is_ident_codepoint( $input, $offset ) ) {
-				// @todo this should append and advance the correct number of bytes.
 				$ident .= $input[ $offset ];
 				++$offset;
 				continue;
@@ -338,7 +342,7 @@ final protected static function next_two_are_valid_escape( string $input, int $o
 	}
 
 	/**
-	 * Checks if the next code point is an "ident start code point".
+	 * Checks if the next code point is an "ident start code point."
 	 *
 	 * Caution! This method does not do any bounds checking, it should not be passed
 	 * a string with an offset that is out of bounds.
@@ -370,7 +374,7 @@ final protected static function is_ident_start_codepoint( string $input, int $of
 	}
 
 	/**
-	 * Checks if the next code point is an "ident code point".
+	 * Checks if the next code point is an "ident code point."
 	 *
 	 * Caution! This method does not do any bounds checking, it should not be passed
 	 * a string with an offset that is out of bounds.
@@ -461,7 +465,12 @@ final protected static function check_if_three_code_points_would_start_an_ident_
 	}
 
 	/**
-	 * @todo doc…
+	 * Normalizes selector input for processing.
+	 *
+	 * @see https://www.w3.org/TR/css-syntax-3/#input-preprocessing
+	 *
+	 * @param string $input The selector string.
+	 * @return string The normalized selector string.
 	 */
 	final protected static function normalize_selector_input( string $input ): string {
 		/*