From 5ddf06c94458e2d7c26374ec472746afe34c1262 Mon Sep 17 00:00:00 2001
From: Huzaifa Al Mesbah <huzaifah4m@gmail.com>
Date: Wed, 4 Feb 2026 17:14:13 +0600
Subject: [PATCH 1/3] Docs: Add descriptive text to `@return` tags in various
 function docblocks across admin and includes files.

---
 src/wp-admin/includes/class-wp-debug-data.php | 28 +++++++++----------
 src/wp-admin/includes/class-wp-list-table.php | 18 ++++++------
 .../includes/class-wp-media-list-table.php    | 14 +++++-----
 src/wp-admin/includes/class-wp-screen.php     |  2 +-
 .../class-wp-theme-install-list-table.php     |  4 +--
 src/wp-admin/includes/media.php               | 22 ++++++++-------
 src/wp-admin/includes/misc.php                |  6 ++--
 src/wp-admin/includes/update.php              | 18 ++++++------
 src/wp-includes/class-wp-http-ixr-client.php  |  2 +-
 src/wp-includes/vars.php                      |  2 +-
 10 files changed, 59 insertions(+), 57 deletions(-)

diff --git a/src/wp-admin/includes/class-wp-debug-data.php b/src/wp-admin/includes/class-wp-debug-data.php
index ceae392fd2d3b..c2c11f280a52d 100644
--- a/src/wp-admin/includes/class-wp-debug-data.php
+++ b/src/wp-admin/includes/class-wp-debug-data.php
@@ -142,7 +142,7 @@ static function ( $section ) {
 	 *
 	 * @since 6.7.0
 	 *
-	 * @return array
+	 * @return array The debug data for the Info screen.
 	 */
 	private static function get_wp_core(): array {
 		// Save few function calls.
@@ -305,7 +305,7 @@ private static function get_wp_core(): array {
 	 *
 	 * @since 6.7.0
 	 *
-	 * @return array
+	 * @return array The core debug data.
 	 */
 	private static function get_wp_dropins(): array {
 		// Get a list of all drop-in replacements.
@@ -340,7 +340,7 @@ private static function get_wp_dropins(): array {
 	 *
 	 * @since 6.7.0
 	 *
-	 * @return array
+	 * @return array The directory sizes debug data.
 	 */
 	private static function get_wp_server(): array {
 		// Populate the server debug fields.
@@ -561,7 +561,7 @@ private static function get_wp_server(): array {
 	 * @since 6.7.0
 	 *
 	 * @throws ImagickException
-	 * @return array
+	 * @return array The drop-ins debug data.
 	 */
 	private static function get_wp_media(): array {
 		// Spare few function calls.
@@ -773,7 +773,7 @@ private static function get_wp_media(): array {
 	 *
 	 * @since 6.7.0
 	 *
-	 * @return array
+	 * @return array The active theme's debug data.
 	 */
 	private static function get_wp_mu_plugins(): array {
 		// List must use plugins if there are any.
@@ -904,7 +904,7 @@ private static function get_wp_paths_sizes(): ?array {
 	 *
 	 * @since 6.7.0
 	 *
-	 * @return array
+	 * @return array The active plugins debug data.
 	 */
 	private static function get_wp_plugins_active(): array {
 		return array(
@@ -919,7 +919,7 @@ private static function get_wp_plugins_active(): array {
 	 *
 	 * @since 6.7.0
 	 *
-	 * @return array
+	 * @return array The inactive plugins debug data.
 	 */
 	private static function get_wp_plugins_inactive(): array {
 		return array(
@@ -934,7 +934,7 @@ private static function get_wp_plugins_inactive(): array {
 	 *
 	 * @since 6.7.0
 	 *
-	 * @return array
+	 * @return array The must-use plugins debug data.
 	 */
 	private static function get_wp_plugins_raw_data(): array {
 		// List all available plugins.
@@ -1057,7 +1057,7 @@ private static function get_wp_plugins_raw_data(): array {
 	 *
 	 * @global array $_wp_theme_features
 	 *
-	 * @return array
+	 * @return array The media handling debug data.
 	 */
 	private static function get_wp_active_theme(): array {
 		global $_wp_theme_features;
@@ -1201,7 +1201,7 @@ private static function get_wp_active_theme(): array {
 	 *
 	 * @since 6.7.0
 	 *
-	 * @return array
+	 * @return array The server debug data.
 	 */
 	private static function get_wp_parent_theme(): array {
 		$theme_updates = get_theme_updates();
@@ -1313,7 +1313,7 @@ private static function get_wp_parent_theme(): array {
 	 *
 	 * @since 6.7.0
 	 *
-	 * @return array
+	 * @return array The database debug data.
 	 */
 	private static function get_wp_themes_inactive(): array {
 		$active_theme  = wp_get_theme();
@@ -1444,7 +1444,7 @@ private static function get_wp_themes_inactive(): array {
 	 *
 	 * @since 6.7.0
 	 *
-	 * @return array
+	 * @return array The WordPress constants debug data.
 	 */
 	private static function get_wp_constants(): array {
 		// Check if WP_DEBUG_LOG is set.
@@ -1613,7 +1613,7 @@ private static function get_wp_constants(): array {
 	 *
 	 * @global wpdb $wpdb WordPress database abstraction object.
 	 *
-	 * @return array
+	 * @return array The file system permissions debug data.
 	 */
 	private static function get_wp_database(): array {
 		global $wpdb;
@@ -1695,7 +1695,7 @@ private static function get_wp_database(): array {
 	 *
 	 * @since 6.7.0
 	 *
-	 * @return array
+	 * @return 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/src/wp-admin/includes/class-wp-list-table.php b/src/wp-admin/includes/class-wp-list-table.php
index a67921824397a..ae6d0d97f8ae4 100644
--- a/src/wp-admin/includes/class-wp-list-table.php
+++ b/src/wp-admin/includes/class-wp-list-table.php
@@ -352,7 +352,7 @@ public function get_pagination_arg( $key ) {
 	 *
 	 * @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 @@ protected function get_views_links( $link_data = array() ) {
 	 *
 	 * @since 3.1.0
 	 *
-	 * @return array
+	 * @return array An associative array of views.
 	 */
 	protected function get_views() {
 		return array();
@@ -554,7 +554,7 @@ public function views() {
 	 * @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 An associative array of bulk actions.
 	 */
 	protected function get_bulk_actions() {
 		return array();
@@ -954,7 +954,7 @@ protected function comments_bubble( $post_id, $pending_comments ) {
 	 *
 	 * @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 @@ public function get_pagenum() {
 	 *
 	 * @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 @@ protected function pagination( $which ) {
 	 * @since 3.1.0
 	 * @abstract
 	 *
-	 * @return array
+	 * @return array 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 @@ public function get_columns() {
 	 * @since 3.1.0
 	 * @since 6.3.0 Added 'abbr', 'orderby-text' and 'initially-sorted-column-order'.
 	 *
-	 * @return array
+	 * @return array An associative array of sortable columns.
 	 */
 	protected function get_sortable_columns() {
 		return array();
@@ -1293,7 +1293,7 @@ protected function get_primary_column_name() {
 	 *
 	 * @since 3.1.0
 	 *
-	 * @return array
+	 * @return array Column information.
 	 */
 	protected function get_column_info() {
 		// $_column_headers is already set / cached.
@@ -1376,7 +1376,7 @@ protected function get_column_info() {
 	 *
 	 * @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/src/wp-admin/includes/class-wp-media-list-table.php b/src/wp-admin/includes/class-wp-media-list-table.php
index 2604c394be2f0..9e3fa9dade7bd 100644
--- a/src/wp-admin/includes/class-wp-media-list-table.php
+++ b/src/wp-admin/includes/class-wp-media-list-table.php
@@ -53,7 +53,7 @@ public function __construct( $args = array() ) {
 	}
 
 	/**
-	 * @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 @@ public function prepare_items() {
 	/**
 	 * @global array $post_mime_types
 	 * @global array $avail_post_mime_types
-	 * @return array
+	 * @return array An array of links for the available views.
 	 */
 	protected function get_views() {
 		global $post_mime_types, $avail_post_mime_types;
@@ -174,7 +174,7 @@ protected function get_views() {
 	}
 
 	/**
-	 * @return array
+	 * @return array An associative array of bulk actions.
 	 */
 	protected function get_bulk_actions() {
 		$actions = array();
@@ -227,7 +227,7 @@ protected function extra_tablenav( $which ) {
 	}
 
 	/**
-	 * @return string
+	 * @return string The current action.
 	 */
 	public function current_action() {
 		if ( isset( $_REQUEST['found_post_id'] ) && isset( $_REQUEST['media'] ) ) {
@@ -246,7 +246,7 @@ public function current_action() {
 	}
 
 	/**
-	 * @return bool
+	 * @return bool Whether the list table has items to display.
 	 */
 	public function has_items() {
 		return have_posts();
@@ -393,7 +393,7 @@ public function get_columns() {
 	}
 
 	/**
-	 * @return array
+	 * @return array An array of sortable columns.
 	 */
 	protected function get_sortable_columns() {
 		return array(
@@ -764,7 +764,7 @@ protected function get_default_primary_column_name() {
 	/**
 	 * @param WP_Post $post
 	 * @param string  $att_title
-	 * @return array
+	 * @return array An array of row actions.
 	 */
 	private function _get_row_actions( $post, $att_title ) {
 		$actions = array();
diff --git a/src/wp-admin/includes/class-wp-screen.php b/src/wp-admin/includes/class-wp-screen.php
index 6bb8681cc612d..51d477f4a80b5 100644
--- a/src/wp-admin/includes/class-wp-screen.php
+++ b/src/wp-admin/includes/class-wp-screen.php
@@ -988,7 +988,7 @@ public function render_screen_meta() {
 	 *
 	 * @global array $wp_meta_boxes Global meta box state.
 	 *
-	 * @return bool
+	 * @return bool Whether the current screen is the block editor.
 	 */
 	public function show_screen_options() {
 		global $wp_meta_boxes;
diff --git a/src/wp-admin/includes/class-wp-theme-install-list-table.php b/src/wp-admin/includes/class-wp-theme-install-list-table.php
index 7e00005ba4372..d3de66f3dbe7a 100644
--- a/src/wp-admin/includes/class-wp-theme-install-list-table.php
+++ b/src/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 @@ public function no_items() {
 	/**
 	 * @global array $tabs
 	 * @global string $tab
-	 * @return array
+	 * @return array An array of links for the available views.
 	 */
 	protected function get_views() {
 		global $tabs, $tab;
diff --git a/src/wp-admin/includes/media.php b/src/wp-admin/includes/media.php
index 6a6d258ae6e7d..c17adc6582bdc 100644
--- a/src/wp-admin/includes/media.php
+++ b/src/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 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 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 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 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/src/wp-admin/includes/misc.php b/src/wp-admin/includes/misc.php
index 6c00a0ffb1951..9fee9906b8c14 100644
--- a/src/wp-admin/includes/misc.php
+++ b/src/wp-admin/includes/misc.php
@@ -816,7 +816,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 ) ) {
@@ -849,7 +849,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.
@@ -889,7 +889,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/src/wp-admin/includes/update.php b/src/wp-admin/includes/update.php
index 0fd9b3c79a5ff..0126da652b545 100644
--- a/src/wp-admin/includes/update.php
+++ b/src/wp-admin/includes/update.php
@@ -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 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 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/src/wp-includes/class-wp-http-ixr-client.php b/src/wp-includes/class-wp-http-ixr-client.php
index 41d31ca9d14ae..71875d550fc2f 100644
--- a/src/wp-includes/class-wp-http-ixr-client.php
+++ b/src/wp-includes/class-wp-http-ixr-client.php
@@ -51,7 +51,7 @@ public function __construct( $server, $path = false, $port = false, $timeout = 1
 	 * @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/src/wp-includes/vars.php b/src/wp-includes/vars.php
index 22496330c33ff..38e75781e17ec 100644
--- a/src/wp-includes/vars.php
+++ b/src/wp-includes/vars.php
@@ -158,7 +158,7 @@
  * @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'] ) ) {

From 4e876376ac16f8bbfab82cecec88917d67ac0fd7 Mon Sep 17 00:00:00 2001
From: Huzaifa Al Mesbah <huzaifah4m@gmail.com>
Date: Thu, 5 Feb 2026 00:35:10 +0600
Subject: [PATCH 2/3] Apply suggestions from code review by Copilot

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
---
 src/wp-admin/includes/class-wp-debug-data.php | 18 +++++++++---------
 src/wp-admin/includes/class-wp-screen.php     |  2 +-
 2 files changed, 10 insertions(+), 10 deletions(-)

diff --git a/src/wp-admin/includes/class-wp-debug-data.php b/src/wp-admin/includes/class-wp-debug-data.php
index 16001252b55e4..a5641b60b0d64 100644
--- a/src/wp-admin/includes/class-wp-debug-data.php
+++ b/src/wp-admin/includes/class-wp-debug-data.php
@@ -305,7 +305,7 @@ private static function get_wp_core(): array {
 	 *
 	 * @since 6.7.0
 	 *
-	 * @return array The core debug data.
+	 * @return 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 @@ private static function get_wp_dropins(): array {
 	 *
 	 * @since 6.7.0
 	 *
-	 * @return array The directory sizes debug data.
+	 * @return array The server-related debug data.
 	 */
 	private static function get_wp_server(): array {
 		// Populate the server debug fields.
@@ -561,7 +561,7 @@ private static function get_wp_server(): array {
 	 * @since 6.7.0
 	 *
 	 * @throws ImagickException
-	 * @return array The drop-ins debug data.
+	 * @return array The media handling debug data.
 	 */
 	private static function get_wp_media(): array {
 		// Spare few function calls.
@@ -773,7 +773,7 @@ private static function get_wp_media(): array {
 	 *
 	 * @since 6.7.0
 	 *
-	 * @return array The active theme's debug data.
+	 * @return array The must-use plugins debug data.
 	 */
 	private static function get_wp_mu_plugins(): array {
 		// List must use plugins if there are any.
@@ -934,7 +934,7 @@ private static function get_wp_plugins_inactive(): array {
 	 *
 	 * @since 6.7.0
 	 *
-	 * @return array The must-use plugins debug data.
+	 * @return array 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 @@ private static function get_wp_plugins_raw_data(): array {
 	 *
 	 * @global array $_wp_theme_features
 	 *
-	 * @return array The media handling debug data.
+	 * @return array The active theme debug data.
 	 */
 	private static function get_wp_active_theme(): array {
 		global $_wp_theme_features;
@@ -1201,7 +1201,7 @@ private static function get_wp_active_theme(): array {
 	 *
 	 * @since 6.7.0
 	 *
-	 * @return array The server debug data.
+	 * @return array The parent theme debug data.
 	 */
 	private static function get_wp_parent_theme(): array {
 		$theme_updates = get_theme_updates();
@@ -1313,7 +1313,7 @@ private static function get_wp_parent_theme(): array {
 	 *
 	 * @since 6.7.0
 	 *
-	 * @return array The database debug data.
+	 * @return array The inactive themes debug data.
 	 */
 	private static function get_wp_themes_inactive(): array {
 		$active_theme  = wp_get_theme();
@@ -1613,7 +1613,7 @@ private static function get_wp_constants(): array {
 	 *
 	 * @global wpdb $wpdb WordPress database abstraction object.
 	 *
-	 * @return array The file system permissions debug data.
+	 * @return array The database debug data.
 	 */
 	private static function get_wp_database(): array {
 		global $wpdb;
diff --git a/src/wp-admin/includes/class-wp-screen.php b/src/wp-admin/includes/class-wp-screen.php
index 51d477f4a80b5..838f0795cd5d3 100644
--- a/src/wp-admin/includes/class-wp-screen.php
+++ b/src/wp-admin/includes/class-wp-screen.php
@@ -988,7 +988,7 @@ public function render_screen_meta() {
 	 *
 	 * @global array $wp_meta_boxes Global meta box state.
 	 *
-	 * @return bool Whether the current screen is the block editor.
+	 * @return bool Whether to show the Screen Options tab for the current screen.
 	 */
 	public function show_screen_options() {
 		global $wp_meta_boxes;

From 7a409a2e3d72901cc84536924358f09ac799b3c1 Mon Sep 17 00:00:00 2001
From: Weston Ruter <weston@ruter.net>
Date: Wed, 4 Feb 2026 11:54:29 -0800
Subject: [PATCH 3/3] Docs: Improve return type specificity for recent changes.

Updates function docblocks to use more specific array types (e.g. array<string, string>) instead of generic array or mixed types, while avoiding PHPStan array shapes.

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
---
 src/wp-admin/includes/class-wp-debug-data.php | 28 +++++++++----------
 src/wp-admin/includes/class-wp-list-table.php | 10 +++----
 .../includes/class-wp-media-list-table.php    |  8 +++---
 .../class-wp-theme-install-list-table.php     |  2 +-
 src/wp-admin/includes/media.php               |  8 +++---
 src/wp-admin/includes/update.php              |  8 +++---
 6 files changed, 32 insertions(+), 32 deletions(-)

diff --git a/src/wp-admin/includes/class-wp-debug-data.php b/src/wp-admin/includes/class-wp-debug-data.php
index a5641b60b0d64..aa0f3eb10ce45 100644
--- a/src/wp-admin/includes/class-wp-debug-data.php
+++ b/src/wp-admin/includes/class-wp-debug-data.php
@@ -142,7 +142,7 @@ static function ( $section ) {
 	 *
 	 * @since 6.7.0
 	 *
-	 * @return array The debug data for the Info screen.
+	 * @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 @@ private static function get_wp_core(): array {
 	 *
 	 * @since 6.7.0
 	 *
-	 * @return array The drop-ins debug data.
+	 * @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 @@ private static function get_wp_dropins(): array {
 	 *
 	 * @since 6.7.0
 	 *
-	 * @return array The server-related debug data.
+	 * @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 @@ private static function get_wp_server(): array {
 	 * @since 6.7.0
 	 *
 	 * @throws ImagickException
-	 * @return array The media handling debug data.
+	 * @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 @@ private static function get_wp_media(): array {
 	 *
 	 * @since 6.7.0
 	 *
-	 * @return array The must-use plugins debug data.
+	 * @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 @@ private static function get_wp_paths_sizes(): ?array {
 	 *
 	 * @since 6.7.0
 	 *
-	 * @return array The active plugins debug data.
+	 * @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 @@ private static function get_wp_plugins_active(): array {
 	 *
 	 * @since 6.7.0
 	 *
-	 * @return array The inactive plugins debug data.
+	 * @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 @@ private static function get_wp_plugins_inactive(): array {
 	 *
 	 * @since 6.7.0
 	 *
-	 * @return array The raw plugin debug data for active and inactive plugins.
+	 * @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 @@ private static function get_wp_plugins_raw_data(): array {
 	 *
 	 * @global array $_wp_theme_features
 	 *
-	 * @return array The active theme debug data.
+	 * @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 @@ private static function get_wp_active_theme(): array {
 	 *
 	 * @since 6.7.0
 	 *
-	 * @return array The parent theme debug data.
+	 * @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 @@ private static function get_wp_parent_theme(): array {
 	 *
 	 * @since 6.7.0
 	 *
-	 * @return array The inactive themes debug data.
+	 * @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 @@ private static function get_wp_themes_inactive(): array {
 	 *
 	 * @since 6.7.0
 	 *
-	 * @return array The WordPress constants debug data.
+	 * @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 @@ private static function get_wp_constants(): array {
 	 *
 	 * @global wpdb $wpdb WordPress database abstraction object.
 	 *
-	 * @return array The database debug data.
+	 * @return array<string, string|array> The database debug data.
 	 */
 	private static function get_wp_database(): array {
 		global $wpdb;
@@ -1695,7 +1695,7 @@ private static function get_wp_database(): array {
 	 *
 	 * @since 6.7.0
 	 *
-	 * @return array The debug data and other information for the Info screen.
+	 * @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/src/wp-admin/includes/class-wp-list-table.php b/src/wp-admin/includes/class-wp-list-table.php
index ae6d0d97f8ae4..e31e89a36fb5a 100644
--- a/src/wp-admin/includes/class-wp-list-table.php
+++ b/src/wp-admin/includes/class-wp-list-table.php
@@ -490,7 +490,7 @@ protected function get_views_links( $link_data = array() ) {
 	 *
 	 * @since 3.1.0
 	 *
-	 * @return array An associative array of views.
+	 * @return array<string, string> An associative array of views.
 	 */
 	protected function get_views() {
 		return array();
@@ -554,7 +554,7 @@ public function views() {
 	 * @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 An associative array of bulk actions.
+	 * @return array<string, string|array<string, string>> An associative array of bulk actions.
 	 */
 	protected function get_bulk_actions() {
 		return array();
@@ -1179,7 +1179,7 @@ protected function pagination( $which ) {
 	 * @since 3.1.0
 	 * @abstract
 	 *
-	 * @return array An associative array of columns.
+	 * @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 @@ public function get_columns() {
 	 * @since 3.1.0
 	 * @since 6.3.0 Added 'abbr', 'orderby-text' and 'initially-sorted-column-order'.
 	 *
-	 * @return array An associative array of sortable columns.
+	 * @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 @@ protected function get_primary_column_name() {
 	 *
 	 * @since 3.1.0
 	 *
-	 * @return array Column information.
+	 * @return array<int, array|string> Column information.
 	 */
 	protected function get_column_info() {
 		// $_column_headers is already set / cached.
diff --git a/src/wp-admin/includes/class-wp-media-list-table.php b/src/wp-admin/includes/class-wp-media-list-table.php
index 9e3fa9dade7bd..86f2cd7061685 100644
--- a/src/wp-admin/includes/class-wp-media-list-table.php
+++ b/src/wp-admin/includes/class-wp-media-list-table.php
@@ -119,7 +119,7 @@ public function prepare_items() {
 	/**
 	 * @global array $post_mime_types
 	 * @global array $avail_post_mime_types
-	 * @return array An array of links for the available views.
+	 * @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 @@ protected function get_views() {
 	}
 
 	/**
-	 * @return array An associative array of bulk actions.
+	 * @return array<string, string> An associative array of bulk actions.
 	 */
 	protected function get_bulk_actions() {
 		$actions = array();
@@ -393,7 +393,7 @@ public function get_columns() {
 	}
 
 	/**
-	 * @return array An array of sortable columns.
+	 * @return array<string, array<int, mixed>> An array of sortable columns.
 	 */
 	protected function get_sortable_columns() {
 		return array(
@@ -764,7 +764,7 @@ protected function get_default_primary_column_name() {
 	/**
 	 * @param WP_Post $post
 	 * @param string  $att_title
-	 * @return array An array of row actions.
+	 * @return array<string, string> An array of row actions.
 	 */
 	private function _get_row_actions( $post, $att_title ) {
 		$actions = array();
diff --git a/src/wp-admin/includes/class-wp-theme-install-list-table.php b/src/wp-admin/includes/class-wp-theme-install-list-table.php
index d3de66f3dbe7a..696b088d1d716 100644
--- a/src/wp-admin/includes/class-wp-theme-install-list-table.php
+++ b/src/wp-admin/includes/class-wp-theme-install-list-table.php
@@ -179,7 +179,7 @@ public function no_items() {
 	/**
 	 * @global array $tabs
 	 * @global string $tab
-	 * @return array An array of links for the available views.
+	 * @return array<string, string> An array of links for the available views.
 	 */
 	protected function get_views() {
 		global $tabs, $tab;
diff --git a/src/wp-admin/includes/media.php b/src/wp-admin/includes/media.php
index c17adc6582bdc..7cbde12d787f1 100644
--- a/src/wp-admin/includes/media.php
+++ b/src/wp-admin/includes/media.php
@@ -1186,7 +1186,7 @@ function image_align_input_fields( $post, $checked = '' ) {
  *
  * @param WP_Post     $post
  * @param bool|string $check
- * @return array An array of data for the image size input fields.
+ * @return array<string, string> An array of data for the image size input fields.
  */
 function image_size_input_fields( $post, $check = '' ) {
 	/**
@@ -1313,7 +1313,7 @@ function wp_caption_input_textarea( $edit_post ) {
  *
  * @param array  $form_fields
  * @param object $post
- * @return array The attachment form fields.
+ * @return array<string, array<string, mixed>> The attachment form fields.
  */
 function image_attachment_fields_to_edit( $form_fields, $post ) {
 	return $form_fields;
@@ -1380,7 +1380,7 @@ function image_media_send_to_editor( $html, $attachment_id, $attachment ) {
  *
  * @param WP_Post $post
  * @param array   $errors
- * @return array The attachment fields.
+ * @return array<string, array<string, mixed>> The attachment fields.
  */
 function get_attachment_fields_to_edit( $post, $errors = null ) {
 	if ( is_int( $post ) ) {
@@ -1871,7 +1871,7 @@ function get_media_item( $attachment_id, $args = null ) {
  *
  * @param int   $attachment_id
  * @param array $args
- * @return array An array containing the media item and its metadata.
+ * @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/src/wp-admin/includes/update.php b/src/wp-admin/includes/update.php
index 0126da652b545..f5aeea835bd12 100644
--- a/src/wp-admin/includes/update.php
+++ b/src/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' ), '', '&' );
@@ -401,7 +401,7 @@ function update_right_now_message() {
  *
  * @since 2.9.0
  *
- * @return object[] Array of plugin objects with available updates.
+ * @return array<string, object> Array of plugin objects with available updates.
  */
 function get_plugin_updates() {
 	$all_plugins     = get_plugins();
@@ -624,7 +624,7 @@ function wp_plugin_update_row( $file, $plugin_data ) {
  *
  * @since 2.9.0
  *
- * @return WP_Theme[] Array of theme objects with available updates.
+ * @return array<string, WP_Theme> Array of theme objects with available updates.
  */
 function get_theme_updates() {
 	$current = get_site_transient( 'update_themes' );