From e744dfca9f4729ea1fa1ef750cff308ddee1be0e Mon Sep 17 00:00:00 2001
From: Jon Surrell <sirreal@users.noreply.github.com>
Date: Tue, 26 Nov 2024 19:37:26 +0100
Subject: [PATCH] Fix parse return type and return annotations

---
 .../html-api/class-wp-css-selectors.php          | 16 ++++++++++++++--
 1 file changed, 14 insertions(+), 2 deletions(-)

diff --git a/src/wp-includes/html-api/class-wp-css-selectors.php b/src/wp-includes/html-api/class-wp-css-selectors.php
index 669c74c1b676d..6a80ca2e42b7c 100644
--- a/src/wp-includes/html-api/class-wp-css-selectors.php
+++ b/src/wp-includes/html-api/class-wp-css-selectors.php
@@ -186,6 +186,8 @@ protected static function parse_hash_token( string $input, int &$offset ): ?stri
 	 * >   Reconsume the current input code point. Return result.
 	 *
 	 * https://www.w3.org/TR/css-syntax-3/#consume-name
+	 *
+	 * @return string|null
 	 */
 	protected static function parse_ident( string $input, int &$offset ): ?string {
 		if ( ! self::check_if_three_code_points_would_start_an_ident_sequence( $input, $offset ) ) {
@@ -243,6 +245,8 @@ protected static function parse_ident( string $input, int &$offset ): ?string {
 	 * This implementation will never return a <bad-string-token> because
 	 * the <bad-string-token> is not a part of the selector grammar. That
 	 * case is treated as failure to parse and null is returned.
+	 *
+	 * @return string|null
 	 */
 	protected static function parse_string( string $input, int &$offset ): ?string {
 		if ( $offset + 1 >= strlen( $input ) ) {
@@ -509,6 +513,8 @@ private function __construct( string $ident ) {
 	 * > <id-selector> = <hash-token>
 	 *
 	 * https://www.w3.org/TR/selectors/#grammar
+	 *
+	 * @return self|null
 	 */
 	public static function parse( string $input, int &$offset ): ?self {
 		$ident = self::parse_hash_token( $input, $offset );
@@ -533,6 +539,8 @@ private function __construct( string $ident ) {
 	 * > <class-selector> = '.' <ident-token>
 	 *
 	 * https://www.w3.org/TR/selectors/#grammar
+	 *
+	 * @return self|null
 	 */
 	public static function parse( string $input, int &$offset ): ?self {
 		if ( $offset + 1 >= strlen( $input ) || '.' !== $input[ $offset ] ) {
@@ -574,10 +582,12 @@ private function __construct( string $ident ) {
 	 * so this selector effectively matches * or ident.
 	 *
 	 * https://www.w3.org/TR/selectors/#grammar
+	 *
+	 * @return self|null
 	 */
 	public static function parse( string $input, int &$offset ): ?self {
 		if ( $offset >= strlen( $input ) ) {
-			return false;
+			return null;
 		}
 
 		if ( '*' === $input[ $offset ] ) {
@@ -697,11 +707,13 @@ private function __construct( string $name, ?string $matcher = null, ?string $va
 	 * Namespaces are not supported, so attribute names are effectively identifiers.
 	 *
 	 * https://www.w3.org/TR/selectors/#grammar
+	 *
+	 * @return self|null
 	 */
 	public static function parse( string $input, int &$offset ): ?self {
 		// Need at least 3 bytes [x]
 		if ( $offset + 2 >= strlen( $input ) ) {
-			return false;
+			return null;
 		}
 
 		$updated_offset = $offset;