Commit 22f5e96b85 for wordpress.org
commit 22f5e96b8549877a7d8998f66601640f59210ac0
Author: Weston Ruter <weston@xwp.co>
Date: Sat Feb 7 06:06:43 2026 +0000
Docs: Add descriptions and improved typing to `@return` tags in various admin and includes files.
Developed in https://github.com/WordPress/wordpress-develop/pull/10863
Props huzaifaalmesbah, westonruter, noruzzaman, mukesh27.
See #64224.
Built from https://develop.svn.wordpress.org/trunk@61594
git-svn-id: http://core.svn.wordpress.org/trunk@60905 1a063a9b-81f0-0310-95a4-ce76da25c4cd
diff --git a/wp-admin/includes/class-wp-debug-data.php b/wp-admin/includes/class-wp-debug-data.php
index 9f914ab882..aa0f3eb10c 100644
--- a/wp-admin/includes/class-wp-debug-data.php
+++ b/wp-admin/includes/class-wp-debug-data.php
@@ -142,7 +142,7 @@ class WP_Debug_Data {
*
* @since 6.7.0
*
- * @return array
+ * @return array<string, string|array> The debug data for the Info screen.
*/
private static function get_wp_core(): array {
// Save few function calls.
@@ -305,7 +305,7 @@ class WP_Debug_Data {
*
* @since 6.7.0
*
- * @return array
+ * @return array<string, string|bool|array> The drop-ins debug data.
*/
private static function get_wp_dropins(): array {
// Get a list of all drop-in replacements.
@@ -340,7 +340,7 @@ class WP_Debug_Data {
*
* @since 6.7.0
*
- * @return array
+ * @return array<string, string|array> The server-related debug data.
*/
private static function get_wp_server(): array {
// Populate the server debug fields.
@@ -561,7 +561,7 @@ class WP_Debug_Data {
* @since 6.7.0
*
* @throws ImagickException
- * @return array
+ * @return array<string, string|array> The media handling debug data.
*/
private static function get_wp_media(): array {
// Spare few function calls.
@@ -773,7 +773,7 @@ class WP_Debug_Data {
*
* @since 6.7.0
*
- * @return array
+ * @return array<string, string|bool|array> The must-use plugins debug data.
*/
private static function get_wp_mu_plugins(): array {
// List must use plugins if there are any.
@@ -904,7 +904,7 @@ class WP_Debug_Data {
*
* @since 6.7.0
*
- * @return array
+ * @return array<string, string|bool|array> The active plugins debug data.
*/
private static function get_wp_plugins_active(): array {
return array(
@@ -919,7 +919,7 @@ class WP_Debug_Data {
*
* @since 6.7.0
*
- * @return array
+ * @return array<string, string|bool|array> The inactive plugins debug data.
*/
private static function get_wp_plugins_inactive(): array {
return array(
@@ -934,7 +934,7 @@ class WP_Debug_Data {
*
* @since 6.7.0
*
- * @return array
+ * @return array<string, array<string, array<string, string>>> The raw plugin debug data for active and inactive plugins.
*/
private static function get_wp_plugins_raw_data(): array {
// List all available plugins.
@@ -1057,7 +1057,7 @@ class WP_Debug_Data {
*
* @global array $_wp_theme_features
*
- * @return array
+ * @return array<string, string|array> The active theme debug data.
*/
private static function get_wp_active_theme(): array {
global $_wp_theme_features;
@@ -1201,7 +1201,7 @@ class WP_Debug_Data {
*
* @since 6.7.0
*
- * @return array
+ * @return array<string, string|array> The parent theme debug data.
*/
private static function get_wp_parent_theme(): array {
$theme_updates = get_theme_updates();
@@ -1313,7 +1313,7 @@ class WP_Debug_Data {
*
* @since 6.7.0
*
- * @return array
+ * @return array<string, string|bool|array> The inactive themes debug data.
*/
private static function get_wp_themes_inactive(): array {
$active_theme = wp_get_theme();
@@ -1444,7 +1444,7 @@ class WP_Debug_Data {
*
* @since 6.7.0
*
- * @return array
+ * @return array<string, string|array> The WordPress constants debug data.
*/
private static function get_wp_constants(): array {
// Check if WP_DEBUG_LOG is set.
@@ -1613,7 +1613,7 @@ class WP_Debug_Data {
*
* @global wpdb $wpdb WordPress database abstraction object.
*
- * @return array
+ * @return array<string, string|array> The database debug data.
*/
private static function get_wp_database(): array {
global $wpdb;
@@ -1695,7 +1695,7 @@ class WP_Debug_Data {
*
* @since 6.7.0
*
- * @return array
+ * @return array<string, string|array> The debug data and other information for the Info screen.
*/
private static function get_wp_filesystem(): array {
$upload_dir = wp_upload_dir();
diff --git a/wp-admin/includes/class-wp-list-table.php b/wp-admin/includes/class-wp-list-table.php
index a679218243..e31e89a36f 100644
--- a/wp-admin/includes/class-wp-list-table.php
+++ b/wp-admin/includes/class-wp-list-table.php
@@ -352,7 +352,7 @@ class WP_List_Table {
*
* @since 3.1.0
*
- * @return bool
+ * @return bool Whether the table has items to display.
*/
public function has_items() {
return ! empty( $this->items );
@@ -490,7 +490,7 @@ class WP_List_Table {
*
* @since 3.1.0
*
- * @return array
+ * @return array<string, string> An associative array of views.
*/
protected function get_views() {
return array();
@@ -554,7 +554,7 @@ class WP_List_Table {
* @since 3.1.0
* @since 5.6.0 A bulk action can now contain an array of options in order to create an optgroup.
*
- * @return array
+ * @return array<string, string|array<string, string>> An associative array of bulk actions.
*/
protected function get_bulk_actions() {
return array();
@@ -954,7 +954,7 @@ class WP_List_Table {
*
* @since 3.1.0
*
- * @return int
+ * @return int Current page number.
*/
public function get_pagenum() {
$pagenum = isset( $_REQUEST['paged'] ) ? absint( $_REQUEST['paged'] ) : 0;
@@ -973,7 +973,7 @@ class WP_List_Table {
*
* @param string $option User option name.
* @param int $default_value Optional. The number of items to display. Default 20.
- * @return int
+ * @return int Number of items to display per page.
*/
protected function get_items_per_page( $option, $default_value = 20 ) {
$per_page = (int) get_user_option( $option );
@@ -1179,7 +1179,7 @@ class WP_List_Table {
* @since 3.1.0
* @abstract
*
- * @return array
+ * @return array<string, string> An associative array of columns.
*/
public function get_columns() {
die( 'function WP_List_Table::get_columns() must be overridden in a subclass.' );
@@ -1202,7 +1202,7 @@ class WP_List_Table {
* @since 3.1.0
* @since 6.3.0 Added 'abbr', 'orderby-text' and 'initially-sorted-column-order'.
*
- * @return array
+ * @return array<string, array<int, string|bool>|string> An associative array of sortable columns.
*/
protected function get_sortable_columns() {
return array();
@@ -1293,7 +1293,7 @@ class WP_List_Table {
*
* @since 3.1.0
*
- * @return array
+ * @return array<int, array|string> Column information.
*/
protected function get_column_info() {
// $_column_headers is already set / cached.
@@ -1376,7 +1376,7 @@ class WP_List_Table {
*
* @since 3.1.0
*
- * @return int
+ * @return int The number of visible columns.
*/
public function get_column_count() {
list ( $columns, $hidden ) = $this->get_column_info();
diff --git a/wp-admin/includes/class-wp-media-list-table.php b/wp-admin/includes/class-wp-media-list-table.php
index 2604c394be..5e26ebb9e1 100644
--- a/wp-admin/includes/class-wp-media-list-table.php
+++ b/wp-admin/includes/class-wp-media-list-table.php
@@ -53,7 +53,7 @@ class WP_Media_List_Table extends WP_List_Table {
}
/**
- * @return bool
+ * @return bool Whether the user can upload files.
*/
public function ajax_user_can() {
return current_user_can( 'upload_files' );
@@ -119,7 +119,7 @@ class WP_Media_List_Table extends WP_List_Table {
/**
* @global array $post_mime_types
* @global array $avail_post_mime_types
- * @return array
+ * @return array<string, string> An array of links for the available views.
*/
protected function get_views() {
global $post_mime_types, $avail_post_mime_types;
@@ -174,7 +174,7 @@ class WP_Media_List_Table extends WP_List_Table {
}
/**
- * @return array
+ * @return array<string, string> An associative array of bulk actions.
*/
protected function get_bulk_actions() {
$actions = array();
@@ -227,7 +227,7 @@ class WP_Media_List_Table extends WP_List_Table {
}
/**
- * @return string
+ * @return string|false The current action.
*/
public function current_action() {
if ( isset( $_REQUEST['found_post_id'] ) && isset( $_REQUEST['media'] ) ) {
@@ -246,7 +246,7 @@ class WP_Media_List_Table extends WP_List_Table {
}
/**
- * @return bool
+ * @return bool Whether the list table has items to display.
*/
public function has_items() {
return have_posts();
@@ -393,7 +393,7 @@ class WP_Media_List_Table extends WP_List_Table {
}
/**
- * @return array
+ * @return array<string, array<int, mixed>> An array of sortable columns.
*/
protected function get_sortable_columns() {
return array(
@@ -764,7 +764,7 @@ class WP_Media_List_Table extends WP_List_Table {
/**
* @param WP_Post $post
* @param string $att_title
- * @return array
+ * @return array<string, string> An array of row actions.
*/
private function _get_row_actions( $post, $att_title ) {
$actions = array();
diff --git a/wp-admin/includes/class-wp-screen.php b/wp-admin/includes/class-wp-screen.php
index 6bb8681cc6..838f0795cd 100644
--- a/wp-admin/includes/class-wp-screen.php
+++ b/wp-admin/includes/class-wp-screen.php
@@ -988,7 +988,7 @@ final class WP_Screen {
*
* @global array $wp_meta_boxes Global meta box state.
*
- * @return bool
+ * @return bool Whether to show the Screen Options tab for the current screen.
*/
public function show_screen_options() {
global $wp_meta_boxes;
diff --git a/wp-admin/includes/class-wp-theme-install-list-table.php b/wp-admin/includes/class-wp-theme-install-list-table.php
index 7e00005ba4..696b088d1d 100644
--- a/wp-admin/includes/class-wp-theme-install-list-table.php
+++ b/wp-admin/includes/class-wp-theme-install-list-table.php
@@ -19,7 +19,7 @@ class WP_Theme_Install_List_Table extends WP_Themes_List_Table {
public $features = array();
/**
- * @return bool
+ * @return bool Whether the user can install themes.
*/
public function ajax_user_can() {
return current_user_can( 'install_themes' );
@@ -179,7 +179,7 @@ class WP_Theme_Install_List_Table extends WP_Themes_List_Table {
/**
* @global array $tabs
* @global string $tab
- * @return array
+ * @return array<string, string> An array of links for the available views.
*/
protected function get_views() {
global $tabs, $tab;
diff --git a/wp-admin/includes/media.php b/wp-admin/includes/media.php
index 6a6d258ae6..7cbde12d78 100644
--- a/wp-admin/includes/media.php
+++ b/wp-admin/includes/media.php
@@ -868,7 +868,7 @@ function media_upload_form_handler() {
*
* @since 2.5.0
*
- * @return null|string
+ * @return null|string The form handler result or null.
*/
function wp_media_upload_handler() {
$errors = array();
@@ -1096,7 +1096,7 @@ function media_sideload_image( $file, $post_id = 0, $desc = null, $return_type =
*
* @since 2.5.0
*
- * @return string|null
+ * @return string|null The form handler result or null.
*/
function media_upload_gallery() {
$errors = array();
@@ -1122,7 +1122,7 @@ function media_upload_gallery() {
*
* @since 2.5.0
*
- * @return string|null
+ * @return string|null The form handler result or null.
*/
function media_upload_library() {
$errors = array();
@@ -1148,7 +1148,7 @@ function media_upload_library() {
*
* @param WP_Post $post
* @param string $checked
- * @return string
+ * @return string HTML for the image alignment radio buttons.
*/
function image_align_input_fields( $post, $checked = '' ) {
@@ -1186,7 +1186,7 @@ function image_align_input_fields( $post, $checked = '' ) {
*
* @param WP_Post $post
* @param bool|string $check
- * @return array
+ * @return array<string, string> An array of data for the image size input fields.
*/
function image_size_input_fields( $post, $check = '' ) {
/**
@@ -1264,7 +1264,7 @@ function image_size_input_fields( $post, $check = '' ) {
*
* @param WP_Post $post
* @param string $url_type
- * @return string
+ * @return string HTML markup for the link URL buttons.
*/
function image_link_input_fields( $post, $url_type = '' ) {
@@ -1313,7 +1313,7 @@ function wp_caption_input_textarea( $edit_post ) {
*
* @param array $form_fields
* @param object $post
- * @return array
+ * @return array<string, array<string, mixed>> The attachment form fields.
*/
function image_attachment_fields_to_edit( $form_fields, $post ) {
return $form_fields;
@@ -1355,7 +1355,7 @@ function media_post_single_attachment_fields_to_edit( $form_fields, $post ) {
* @param string $html
* @param int $attachment_id
* @param array $attachment
- * @return string
+ * @return string HTML markup for the media element.
*/
function image_media_send_to_editor( $html, $attachment_id, $attachment ) {
$post = get_post( $attachment_id );
@@ -1380,7 +1380,7 @@ function image_media_send_to_editor( $html, $attachment_id, $attachment ) {
*
* @param WP_Post $post
* @param array $errors
- * @return array
+ * @return array<string, array<string, mixed>> The attachment fields.
*/
function get_attachment_fields_to_edit( $post, $errors = null ) {
if ( is_int( $post ) ) {
@@ -1865,11 +1865,13 @@ function get_media_item( $attachment_id, $args = null ) {
}
/**
+ * Retrieves the media markup for an attachment.
+ *
* @since 3.5.0
*
* @param int $attachment_id
* @param array $args
- * @return array
+ * @return array<string, string> An array containing the media item and its metadata.
*/
function get_compat_media_markup( $attachment_id, $args = null ) {
$post = get_post( $attachment_id );
diff --git a/wp-admin/includes/misc.php b/wp-admin/includes/misc.php
index d5a861638a..d3a93a17b4 100644
--- a/wp-admin/includes/misc.php
+++ b/wp-admin/includes/misc.php
@@ -819,7 +819,7 @@ function set_screen_options() {
* @since 2.8.0
*
* @param string $filename The file path to the configuration file.
- * @return bool
+ * @return bool Whether the rule exists.
*/
function iis7_rewrite_rule_exists( $filename ) {
if ( ! file_exists( $filename ) ) {
@@ -852,7 +852,7 @@ function iis7_rewrite_rule_exists( $filename ) {
* @since 2.8.0
*
* @param string $filename Name of the configuration file.
- * @return bool
+ * @return bool Whether the rule was deleted.
*/
function iis7_delete_rewrite_rule( $filename ) {
// If configuration file does not exist then rules also do not exist, so there is nothing to delete.
@@ -892,7 +892,7 @@ function iis7_delete_rewrite_rule( $filename ) {
*
* @param string $filename The file path to the configuration file.
* @param string $rewrite_rule The XML fragment with URL Rewrite rule.
- * @return bool
+ * @return bool Whether the rule was added.
*/
function iis7_add_rewrite_rule( $filename, $rewrite_rule ) {
if ( ! class_exists( 'DOMDocument', false ) ) {
diff --git a/wp-admin/includes/update.php b/wp-admin/includes/update.php
index 0fd9b3c79a..f5aeea835b 100644
--- a/wp-admin/includes/update.php
+++ b/wp-admin/includes/update.php
@@ -34,7 +34,7 @@ function get_preferred_from_update_core() {
*
* @param array $options Set $options['dismissed'] to true to show dismissed upgrades too,
* set $options['available'] to false to skip not-dismissed updates.
- * @return array|false Array of the update objects on success, false on failure.
+ * @return array<object>|false Array of the update objects on success, false on failure.
*/
function get_core_updates( $options = array() ) {
$options = array_merge(
@@ -126,7 +126,7 @@ function find_core_auto_update() {
*
* @param string $version Version string to query.
* @param string $locale Locale to query.
- * @return array|false An array of checksums on success, false on failure.
+ * @return array<string, string>|false An array of checksums on success, false on failure.
*/
function get_core_checksums( $version, $locale ) {
$http_url = 'http://api.wordpress.org/core/checksums/1.0/?' . http_build_query( compact( 'version', 'locale' ), '', '&' );
@@ -178,7 +178,7 @@ function get_core_checksums( $version, $locale ) {
* @since 2.7.0
*
* @param object $update
- * @return bool
+ * @return bool True if the option was updated, false otherwise.
*/
function dismiss_core_update( $update ) {
$dismissed = get_site_option( 'dismissed_update_core' );
@@ -194,7 +194,7 @@ function dismiss_core_update( $update ) {
*
* @param string $version
* @param string $locale
- * @return bool
+ * @return bool True if the option was updated, false otherwise.
*/
function undismiss_core_update( $version, $locale ) {
$dismissed = get_site_option( 'dismissed_update_core' );
@@ -242,7 +242,7 @@ function find_core_update( $version, $locale ) {
* @since 2.3.0
*
* @param string $msg
- * @return string
+ * @return string The core update footer message.
*/
function core_update_footer( $msg = '' ) {
if ( ! current_user_can( 'update_core' ) ) {
@@ -297,7 +297,7 @@ function core_update_footer( $msg = '' ) {
* @since 2.3.0
*
* @global string $pagenow The filename of the current screen.
- * @return void|false
+ * @return void|false Void on success, false if the update nag should not be displayed.
*/
function update_nag() {
global $pagenow;
@@ -401,7 +401,7 @@ function update_right_now_message() {
*
* @since 2.9.0
*
- * @return object[]
+ * @return array<string, object> Array of plugin objects with available updates.
*/
function get_plugin_updates() {
$all_plugins = get_plugins();
@@ -446,7 +446,7 @@ function wp_plugin_update_rows() {
*
* @param string $file Plugin basename.
* @param array $plugin_data Plugin information.
- * @return void|false
+ * @return void|false Void on success, false if the plugin update is not available.
*/
function wp_plugin_update_row( $file, $plugin_data ) {
$current = get_site_transient( 'update_plugins' );
@@ -624,7 +624,7 @@ function wp_plugin_update_row( $file, $plugin_data ) {
*
* @since 2.9.0
*
- * @return WP_Theme[]
+ * @return array<string, WP_Theme> Array of theme objects with available updates.
*/
function get_theme_updates() {
$current = get_site_transient( 'update_themes' );
@@ -671,7 +671,7 @@ function wp_theme_update_rows() {
*
* @param string $theme_key Theme stylesheet.
* @param WP_Theme $theme Theme object.
- * @return void|false
+ * @return void|false Void on success, false if the theme update is not available.
*/
function wp_theme_update_row( $theme_key, $theme ) {
$current = get_site_transient( 'update_themes' );
@@ -848,7 +848,7 @@ function wp_theme_update_row( $theme_key, $theme ) {
*
* @global int $upgrading
*
- * @return void|false
+ * @return void|false Void on success, false if the maintenance nag should not be displayed.
*/
function maintenance_nag() {
global $upgrading;
diff --git a/wp-includes/class-wp-http-ixr-client.php b/wp-includes/class-wp-http-ixr-client.php
index 41d31ca9d1..71875d550f 100644
--- a/wp-includes/class-wp-http-ixr-client.php
+++ b/wp-includes/class-wp-http-ixr-client.php
@@ -51,7 +51,7 @@ class WP_HTTP_IXR_Client extends IXR_Client {
* @since 5.5.0 Formalized the existing `...$args` parameter by adding it
* to the function signature.
*
- * @return bool
+ * @return bool True if the request succeeded, false otherwise.
*/
public function query( ...$args ) {
$method = array_shift( $args );
diff --git a/wp-includes/vars.php b/wp-includes/vars.php
index 22496330c3..38e75781e1 100644
--- a/wp-includes/vars.php
+++ b/wp-includes/vars.php
@@ -158,7 +158,7 @@ $is_iis7 = $is_IIS && (int) substr( $_SERVER['SERVER_SOFTWARE'], strpos( $_SERVE
* @since 3.4.0
* @since 6.4.0 Added checking for the Sec-CH-UA-Mobile request header.
*
- * @return bool
+ * @return bool Whether the request is from a mobile device.
*/
function wp_is_mobile() {
if ( isset( $_SERVER['HTTP_SEC_CH_UA_MOBILE'] ) ) {
diff --git a/wp-includes/version.php b/wp-includes/version.php
index 77974cf898..85388db222 100644
--- a/wp-includes/version.php
+++ b/wp-includes/version.php
@@ -16,7 +16,7 @@
*
* @global string $wp_version
*/
-$wp_version = '7.0-alpha-61593';
+$wp_version = '7.0-alpha-61594';
/**
* Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.