Changeset 58742

Timestamp:

07/17/2024 12:51:34 AM (8 months ago)

Author:

dmsnell

Message:

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.

Location:

trunk

Files:

• src/wp-includes/class-wp-token-map.php (modified) (1 diff)
• src/wp-includes/functions.php (modified) (1 diff)
• src/wp-includes/html-api/class-wp-html-open-elements.php (modified) (1 diff)
• src/wp-includes/html-api/class-wp-html-processor.php (modified) (3 diffs)
• tests/phpunit/tests/html-api/wpHtmlProcessorHtml5lib.php (modified) (1 diff)

trunk/src/wp-includes/class-wp-token-map.php

@@ -521 +521 @@
      * @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`.
      */

trunk/src/wp-includes/functions.php

@@ -7498 +7498 @@
  * @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.
  */

trunk/src/wp-includes/html-api/class-wp-html-open-elements.php

@@ -500 +500 @@
      * @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 ) {

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

@@ -242 +242 @@
      * @since 6.6.0
      *
-     * @var ?WP_HTML_Stack_Event
+     * @var WP_HTML_Stack_Event|null
      */
     private $current_element = null;
@@ -249 +249 @@
      * Context node if created as a fragment parser.
      *
-     * @var ?WP_HTML_Token
+     * @var WP_HTML_Token|null
      */
     private $context_node = null;
@@ -753 +753 @@
      *       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 ) {

trunk/tests/phpunit/tests/html-api/wpHtmlProcessorHtml5lib.php

@@ -276 +276 @@
          * Represents which section of the test case is being parsed.
          *
-         * @var ?string
+         * @var string|null
          */
         $state = null;