From b7b504dc0d42e2bdfdfc4294d7b5c3bfa09c7e78 Mon Sep 17 00:00:00 2001 From: dmsnell Date: Wed, 17 Jul 2024 00:53:17 +0000 Subject: [PATCH] Fix phpdoc nullable types in some files. It was found that in several places in the HTML API and its supporting files, the wrong form of type annotation was used for optional parameters. Instead of using `?type`, this patch uses `type|type-of-default-value` instead, noting where important if the parameter is optional, and if so, what its default value is. Developed in https://github.com/WordPress/wordpress-develop/pull/7031 Discussed in https://core.trac.wordpress.org/ticket/61399 Props dmsnell, jonsurrell. See #61399. Built from https://develop.svn.wordpress.org/trunk@58742 git-svn-id: http://core.svn.wordpress.org/trunk@58144 1a063a9b-81f0-0310-95a4-ce76da25c4cd --- wp-includes/class-wp-token-map.php | 9 +++++---- wp-includes/functions.php | 5 +++-- wp-includes/html-api/class-wp-html-open-elements.php | 3 ++- wp-includes/html-api/class-wp-html-processor.php | 11 ++++++----- wp-includes/version.php | 2 +- 5 files changed, 17 insertions(+), 13 deletions(-) diff --git a/wp-includes/class-wp-token-map.php b/wp-includes/class-wp-token-map.php index a932f4cae4..524ab57fd4 100644 --- a/wp-includes/class-wp-token-map.php +++ b/wp-includes/class-wp-token-map.php @@ -520,10 +520,11 @@ class WP_Token_Map { * * @since 6.6.0 * - * @param string $text String in which to search for a lookup key. - * @param int $offset Optional. How many bytes into the string where the lookup key ought to start. Default 0. - * @param ?int &$matched_token_byte_length Optional. Holds byte-length of found token matched, otherwise not set. Default null. - * @param string $case_sensitivity Optional. Pass 'ascii-case-insensitive' to ignore ASCII case when matching. Default 'case-sensitive'. + * @param string $text String in which to search for a lookup key. + * @param int $offset Optional. How many bytes into the string where the lookup key ought to start. Default 0. + * @param int|null &$matched_token_byte_length Optional. Holds byte-length of found token matched, otherwise not set. Default null. + * @param string $case_sensitivity Optional. Pass 'ascii-case-insensitive' to ignore ASCII case when matching. Default 'case-sensitive'. + * * @return string|null Mapped value of lookup key if found, otherwise `null`. */ public function read_token( $text, $offset = 0, &$matched_token_byte_length = null, $case_sensitivity = 'case-sensitive' ) { diff --git a/wp-includes/functions.php b/wp-includes/functions.php index e99a93b80d..94155249fe 100644 --- a/wp-includes/functions.php +++ b/wp-includes/functions.php @@ -7497,8 +7497,9 @@ function get_tag_regex( $tag ) { * * @since 6.6.0 * - * @param ?string $blog_charset Slug representing a text character encoding, or "charset". - * E.g. "UTF-8", "Windows-1252", "ISO-8859-1", "SJIS". + * @param string|null $blog_charset Optional. Slug representing a text character encoding, or "charset". + * E.g. "UTF-8", "Windows-1252", "ISO-8859-1", "SJIS". + * Default value is to infer from "blog_charset" option. * @return bool Whether the slug represents the UTF-8 encoding. */ function is_utf8_charset( $blog_charset = null ) { diff --git a/wp-includes/html-api/class-wp-html-open-elements.php b/wp-includes/html-api/class-wp-html-open-elements.php index d1585cdea5..df6ba8158b 100644 --- a/wp-includes/html-api/class-wp-html-open-elements.php +++ b/wp-includes/html-api/class-wp-html-open-elements.php @@ -499,7 +499,8 @@ class WP_HTML_Open_Elements { * @since 6.4.0 * @since 6.5.0 Accepts $above_this_node to start traversal above a given node, if it exists. * - * @param ?WP_HTML_Token $above_this_node Start traversing above this node, if provided and if the node exists. + * @param WP_HTML_Token|null $above_this_node Optional. Start traversing above this node, + * if provided and if the node exists. */ public function walk_up( $above_this_node = null ) { $has_found_node = null === $above_this_node; diff --git a/wp-includes/html-api/class-wp-html-processor.php b/wp-includes/html-api/class-wp-html-processor.php index 04c387c003..679c4a7e50 100644 --- a/wp-includes/html-api/class-wp-html-processor.php +++ b/wp-includes/html-api/class-wp-html-processor.php @@ -241,14 +241,14 @@ class WP_HTML_Processor extends WP_HTML_Tag_Processor { * * @since 6.6.0 * - * @var ?WP_HTML_Stack_Event + * @var WP_HTML_Stack_Event|null */ private $current_element = null; /** * Context node if created as a fragment parser. * - * @var ?WP_HTML_Token + * @var WP_HTML_Token|null */ private $context_node = null; @@ -752,9 +752,10 @@ class WP_HTML_Processor extends WP_HTML_Tag_Processor { * this returns false for self-closing elements in the * SVG and MathML namespace. * - * @param ?WP_HTML_Token $node Node to examine instead of current node, if provided. - * @return bool Whether to expect a closer for the currently-matched node, - * or `null` if not matched on any token. + * @param WP_HTML_Token|null $node Optional. Node to examine, if provided. + * Default is to examine current node. + * @return bool|null Whether to expect a closer for the currently-matched node, + * or `null` if not matched on any token. */ public function expects_closer( $node = null ) { $token_name = $node->node_name ?? $this->get_token_name(); diff --git a/wp-includes/version.php b/wp-includes/version.php index 68cd5d06cf..755d0f60e7 100644 --- a/wp-includes/version.php +++ b/wp-includes/version.php @@ -16,7 +16,7 @@ * * @global string $wp_version */ -$wp_version = '6.7-alpha-58741'; +$wp_version = '6.7-alpha-58742'; /** * Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.