Docs: Add descriptions and improved typing to @return tags in various admin and includes files.

Developed in WordPress#10863

Props huzaifaalmesbah, westonruter, noruzzaman, mukesh27.
See #64224.


git-svn-id: https://develop.svn.wordpress.org/trunk@61594 602fd350-edb4-49c9-b593-d223f7449a82

Author: westonruter

src/wp-admin/includes/class-wp-debug-data.php

@@ -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.
@@ -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.
@@ -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.
@@ -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.
@@ -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.
@@ -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(
@@ -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(
@@ -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.
 	 */
 	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<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
+	 * @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
+	 * @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
+	 * @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
+	 * @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
+	 * @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();

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<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
+	 * @return array<string, string|array<string, string>> 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<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
+	 * @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
+	 * @return array<int, array|string> 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();

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<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
+	 * @return array<string, string> 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|false 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<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
+	 * @return array<string, string> An array of row actions.
 	 */
 	private function _get_row_actions( $post, $att_title ) {
 		$actions = array();

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 to show the Screen Options tab for the current screen.
 	 */
 	public function show_screen_options() {
 		global $wp_meta_boxes;

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<string, string> An array of links for the available views.
 	 */
 	protected function get_views() {
 		global $tabs, $tab;

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<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 );