Commit 10c297f120 for wordpress.org
commit 10c297f120ea1035b2d68e656ac7099bc43b2b84
Author: westonruter <westonruter@git.wordpress.org>
Date: Tue Nov 3 02:41:57 2026 +0000
Build/Test Tools: Type `T[]` hash elements and `Required.` keys.
The `HashNotationVisitor` derived shapes only for a bare `array`, `object`, or class. A list of arrays declared as `array[]` and documented by a single `...$0` entry, as the blocks `parse_blocks()` returns are, therefore stayed `array<array>`, and every key read from an element was `mixed`.
Such a `T[]` now takes the shape when its entry has a hash of its own and is typed as that `T`. The two types are compared as parsed, so class names and keywords match in any case, while shape keys and string literals must match exactly. A hash on a template type or type alias is left untranslated, since whether it needs an array or an object shape depends on what the name stands for.
Keys of a `@param` hash are optional, which is wrong for a value whose keys are always set, such as a parsed block, and there was no way to say otherwise. A `Required.` sentence opening or closing a key's description, as core already writes it in many hashes, now makes the key required. Unlike `Optional.`, it must be capitalized, since prose mistaken for it would report an error at every call leaving the key out.
The sharper types exposed docblocks contradicting the code, which are corrected: the `type` of each settings error is always set, and neither the `user_id` of `wp_initialize_site()` nor the `href` of a preloaded image is required. The blocks `resolve_pattern_blocks()` takes and returns are documented with the block hash, and the display arguments of `WP_Widget_Categories::widget()` are marked required, removing errors deferred when they were documented as a hash in r64413.
At level 10, this fixes 64 errors and makes 15 existing issues visible, for 49 fewer errors overall.
Developed in https://github.com/WordPress/wordpress-develop/pull/14457.
Follow-up to r63420, r64413.
Props westonruter, lancewillett.
See #62762, #65817, #65890.
Built from https://develop.svn.wordpress.org/trunk@65217
git-svn-id: http://core.svn.wordpress.org/trunk@64366 1a063a9b-81f0-0310-95a4-ce76da25c4cd
diff --git a/wp-admin/includes/template.php b/wp-admin/includes/template.php
index 973e7486db..9e996fc37c 100644
--- a/wp-admin/includes/template.php
+++ b/wp-admin/includes/template.php
@@ -1907,7 +1907,7 @@ function add_settings_error( $setting, $code, $message, $type = 'error' ) {
* @type string $code Slug-name to identify the error. Used as part of 'id' attribute in HTML output.
* @type string $message The formatted message text to display to the user (will be shown inside styled
* `<div>` and `<p>` tags).
- * @type string $type Optional. Message type, controls HTML class. Possible values include 'error',
+ * @type string $type Message type, controls HTML class. Possible values include 'error',
* 'success', 'warning', 'info'. Default 'error'.
* }
* }
diff --git a/wp-includes/blocks.php b/wp-includes/blocks.php
index 626e7b7f14..309f1db97a 100644
--- a/wp-includes/blocks.php
+++ b/wp-includes/blocks.php
@@ -1928,8 +1928,40 @@ function traverse_and_serialize_block( $block, $pre_callback = null, $post_callb
* @since 6.6.0
* @since 7.0.0 Adds metadata to attributes of single-pattern container blocks.
*
- * @param array $blocks An array blocks.
- * @return array An array of blocks with patterns replaced by their content.
+ * @param array[] $blocks {
+ * An array of blocks.
+ *
+ * @type array ...$0 {
+ * An associative array of a single parsed block object. See {@see WP_Block_Parser_Block}.
+ *
+ * @type string|null $blockName Required. Name of block.
+ * @type array $attrs Required. Attributes from block comment delimiters.
+ * @type array[] $innerBlocks Required. List of inner blocks. An array of arrays that
+ * have the same structure as this one.
+ * @type string $innerHTML Required. HTML from inside block comment delimiters.
+ * @type array $innerContent Required. List of string fragments and null markers where
+ * inner blocks were found.
+ * }
+ * }
+ * @return array[] {
+ * An array of blocks with patterns replaced by their content.
+ *
+ * @type array ...$0 {
+ * An associative array of a single parsed block object. See {@see WP_Block_Parser_Block}.
+ *
+ * @type string|null $blockName Name of block.
+ * @type array $attrs Attributes from block comment delimiters.
+ * @type array[] $innerBlocks List of inner blocks. An array of arrays that
+ * have the same structure as this one.
+ * @type string $innerHTML HTML from inside block comment delimiters.
+ * @type array $innerContent List of string fragments and null markers where
+ * inner blocks were found.
+ * @type mixed ...$key Any other keys a block passed in carries, which
+ * are kept, except where a `core/pattern` block is
+ * replaced by its pattern's blocks, or removed as
+ * recursive.
+ * }
+ * }
*/
function resolve_pattern_blocks( $blocks ) {
static $inner_content;
diff --git a/wp-includes/general-template.php b/wp-includes/general-template.php
index 9826ab0633..914b0bff3b 100644
--- a/wp-includes/general-template.php
+++ b/wp-includes/general-template.php
@@ -4073,7 +4073,8 @@ function wp_preload_resources() {
* @type array ...$0 {
* Array of resource attributes.
*
- * @type string $href URL to include in resource preloads. Required.
+ * @type string $href URL to include in resource preloads. May be omitted
+ * for an image preloaded by its `$imagesrcset`.
* @type string $as How the browser should treat the resource
* (`script`, `style`, `image`, `document`, etc).
* @type string $crossorigin Indicates the CORS policy of the specified resource.
diff --git a/wp-includes/ms-site.php b/wp-includes/ms-site.php
index 342058156b..71b9823728 100644
--- a/wp-includes/ms-site.php
+++ b/wp-includes/ms-site.php
@@ -646,7 +646,9 @@ function wp_validate_site_data( $errors, $data, $old_site = null ) {
* @param array $args {
* Optional. Arguments to modify the initialization behavior.
*
- * @type int $user_id Required. User ID for the site administrator.
+ * @type int $user_id User ID for the site administrator. Default 0, in which
+ * case the site is created without an administrator
+ * and with an empty admin email address.
* @type string $title Site title. Default is 'Site %d' where %d is the
* site ID.
* @type array $options Custom option $key => $value pairs to use. Default
diff --git a/wp-includes/version.php b/wp-includes/version.php
index 41b980f3eb..f5c5412830 100644
--- a/wp-includes/version.php
+++ b/wp-includes/version.php
@@ -16,7 +16,7 @@
*
* @global string $wp_version
*/
-$wp_version = '7.2-beta3-65216';
+$wp_version = '7.2-beta3-65217';
/**
* Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.
diff --git a/wp-includes/widgets/class-wp-widget-categories.php b/wp-includes/widgets/class-wp-widget-categories.php
index e26d607c4d..d506212777 100644
--- a/wp-includes/widgets/class-wp-widget-categories.php
+++ b/wp-includes/widgets/class-wp-widget-categories.php
@@ -41,10 +41,10 @@ class WP_Widget_Categories extends WP_Widget {
* @param array $args {
* Display arguments.
*
- * @type string $before_widget HTML markup to prepend to each widget in the sidebar.
- * @type string $after_widget HTML markup to append to each widget in the sidebar.
- * @type string $before_title HTML markup to prepend to the widget title when displayed.
- * @type string $after_title HTML markup to append to the widget title when displayed.
+ * @type string $before_widget Required. HTML markup to prepend to each widget in the sidebar.
+ * @type string $after_widget Required. HTML markup to append to each widget in the sidebar.
+ * @type string $before_title Required. HTML markup to prepend to the widget title when displayed.
+ * @type string $after_title Required. HTML markup to append to the widget title when displayed.
* }
* @param array $instance {
* Settings for the current Categories widget instance.