Skip to content

Docs: Add descriptive text to @return tags in various function DocBlocks across admin and includes files. #10863

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
huzaifaalmesbah wants to merge 5 commits into
base: trunk
Choose a base branch
from
+61 −59
Open

Docs: Add descriptive text to @return tags in various function DocBlocks across admin and includes files. #10863

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
5ddf06c
Docs: Add descriptive text to `@return` tags in various function docb…
huzaifaalmesbah Feb 4, 2026
7beb9be
Merge branch 'trunk' into fix/missing-return-descriptions
huzaifaalmesbah Feb 4, 2026
4e87637
Apply suggestions from code review by Copilot
huzaifaalmesbah Feb 4, 2026
7a409a2
Docs: Improve return type specificity for recent changes.
westonruter Feb 4, 2026
f74c237
Merge branch 'trunk' into fix/missing-return-descriptions
huzaifaalmesbah Feb 5, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 14 additions & 14 deletions src/wp-admin/includes/class-wp-debug-data.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -142,7 +142,7 @@ static function ( $section ) {
*
* @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.
Expand Down Expand Up @@ -305,7 +305,7 @@ private static function get_wp_core(): array {
*
* @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.
Expand Down Expand Up @@ -340,7 +340,7 @@ private static function get_wp_dropins(): array {
*
* @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.
Expand Down Expand Up @@ -561,7 +561,7 @@ private static function get_wp_server(): array {
* @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.
Expand Down Expand Up @@ -773,7 +773,7 @@ private static function get_wp_media(): array {
*
* @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.
Expand Down Expand Up @@ -904,7 +904,7 @@ private static function get_wp_paths_sizes(): ?array {
*
* @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(
Expand All @@ -919,7 +919,7 @@ private static function get_wp_plugins_active(): array {
*
* @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(
Expand All @@ -934,7 +934,7 @@ private static function get_wp_plugins_inactive(): array {
*
* @since 6.7.0
*
* @return array
* @return array<string, array<string, array<string, string>>> The raw plugin debug data for active and inactive plugins.
Copy link

@noruzzamans noruzzamans Feb 5, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The nested @return type looks a bit complex; is this the preferred level of detail for Core PHPDoc?

Copy link
Member Author

@huzaifaalmesbah huzaifaalmesbah Feb 5, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This uses PHPStan/Psalm-style generics, which might be more detailed.

*/
private static function get_wp_plugins_raw_data(): array {
// List all available plugins.
Expand Down Expand Up @@ -1057,7 +1057,7 @@ private static function get_wp_plugins_raw_data(): array {
*
* @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;
Expand Down Expand Up @@ -1201,7 +1201,7 @@ private static function get_wp_active_theme(): array {
*
* @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();
Expand Down Expand Up @@ -1313,7 +1313,7 @@ private static function get_wp_parent_theme(): array {
*
* @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();
Expand Down Expand Up @@ -1444,7 +1444,7 @@ private static function get_wp_themes_inactive(): array {
*
* @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.
Expand Down Expand Up @@ -1613,7 +1613,7 @@ private static function get_wp_constants(): array {
*
* @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;
Expand Down Expand Up @@ -1695,7 +1695,7 @@ private static function get_wp_database(): array {
*
* @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();
Expand Down
18 changes: 9 additions & 9 deletions src/wp-admin/includes/class-wp-list-table.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 );
Expand Down Expand Up @@ -490,7 +490,7 @@ protected function get_views_links( $link_data = array() ) {
*
* @since 3.1.0
*
* @return array
* @return array<string, string> An associative array of views.
*/
protected function get_views() {
return array();
Expand Down Expand Up @@ -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<string, string|array<string, string>> An associative array of bulk actions.
*/
protected function get_bulk_actions() {
return array();
Expand Down Expand Up @@ -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;
Expand All @@ -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 );
Expand Down Expand Up @@ -1179,7 +1179,7 @@ protected function pagination( $which ) {
* @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.' );
Expand All @@ -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<string, array<int, string|bool>|string> An associative array of sortable columns.
*/
protected function get_sortable_columns() {
return array();
Expand Down Expand Up @@ -1293,7 +1293,7 @@ protected function get_primary_column_name() {
*
* @since 3.1.0
*
* @return array
* @return array<int, array|string> Column information.
*/
protected function get_column_info() {
// $_column_headers is already set / cached.
Expand Down Expand Up @@ -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();
Expand Down
14 changes: 7 additions & 7 deletions src/wp-admin/includes/class-wp-media-list-table.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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' );
Expand Down Expand Up @@ -119,7 +119,7 @@ public function prepare_items() {
/**
* @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;
Expand Down Expand Up @@ -174,7 +174,7 @@ protected function get_views() {
}

/**
* @return array
* @return array<string, string> An associative array of bulk actions.
*/
protected function get_bulk_actions() {
$actions = array();
Expand Down Expand Up @@ -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'] ) ) {
Expand All @@ -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();
Expand Down Expand Up @@ -393,7 +393,7 @@ public function get_columns() {
}

/**
* @return array
* @return array<string, array<int, mixed>> An array of sortable columns.
*/
protected function get_sortable_columns() {
return array(
Expand Down Expand Up @@ -764,7 +764,7 @@ protected function get_default_primary_column_name() {
/**
* @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();
Expand Down
2 changes: 1 addition & 1 deletion src/wp-admin/includes/class-wp-screen.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -988,7 +988,7 @@ public function render_screen_meta() {
*
* @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;
Expand Down
4 changes: 2 additions & 2 deletions src/wp-admin/includes/class-wp-theme-install-list-table.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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' );
Expand Down Expand Up @@ -179,7 +179,7 @@ public function no_items() {
/**
* @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;
Expand Down
22 changes: 12 additions & 10 deletions src/wp-admin/includes/media.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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();
Expand Down Expand Up @@ -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();
Expand All @@ -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();
Expand All @@ -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 = '' ) {

Expand Down Expand Up @@ -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 = '' ) {
/**
Expand Down Expand Up @@ -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 = '' ) {

Expand Down Expand Up @@ -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;
Expand Down Expand Up @@ -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 );
Expand All @@ -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 ) ) {
Expand Down Expand Up @@ -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 );
Expand Down
Loading
Loading