Docs: Document more parameters and properties using typed array notation.

See #41756

Built from https://develop.svn.wordpress.org/trunk@42875


git-svn-id: http://core.svn.wordpress.org/trunk@42705 1a063a9b-81f0-0310-95a4-ce76da25c4cd

wp-admin/includes/dashboard.php

@@ -79,7 +79,7 @@ function wp_dashboard_setup() {
 		 *
 		 * @since 3.1.0
 		 *
-		 * @param array $dashboard_widgets An array of dashboard widgets.
+		 * @param string[] $dashboard_widgets An array of dashboard widget IDs.
 		 */
 		$dashboard_widgets = apply_filters( 'wp_network_dashboard_widgets', array() );
 	} elseif ( is_user_admin() ) {
@@ -96,7 +96,7 @@ function wp_dashboard_setup() {
 		 *
 		 * @since 3.1.0
 		 *
-		 * @param array $dashboard_widgets An array of dashboard widgets.
+		 * @param string[] $dashboard_widgets An array of dashboard widget IDs.
 		 */
 		$dashboard_widgets = apply_filters( 'wp_user_dashboard_widgets', array() );
 	} else {
@@ -113,7 +113,7 @@ function wp_dashboard_setup() {
 		 *
 		 * @since 2.5.0
 		 *
-		 * @param array $dashboard_widgets An array of dashboard widgets.
+		 * @param string[] $dashboard_widgets An array of dashboard widget IDs.
 		 */
 		$dashboard_widgets = apply_filters( 'wp_dashboard_widgets', array() );
 	}
@@ -314,7 +314,7 @@ function wp_dashboard_right_now() {
 	 *
 	 * @since 3.8.0
 	 *
-	 * @param array $items Array of extra 'At a Glance' widget items.
+	 * @param string[] $items Array of extra 'At a Glance' widget items.
 	 */
 	$elements = apply_filters( 'dashboard_glance_items', array() );
 
@@ -555,7 +555,7 @@ function wp_dashboard_quick_press( $error_msg = false ) {
  *
  * @since 2.7.0
  *
- * @param array $drafts
+ * @param WP_Post[] $drafts Optional. Array of posts to display. Default false.
  */
 function wp_dashboard_recent_drafts( $drafts = false ) {
 	if ( ! $drafts ) {
@@ -671,7 +671,7 @@ function _wp_dashboard_recent_comments_row( &$comment, $show_date = true ) {
 		 *
 		 * @since 2.6.0
 		 *
-		 * @param array      $actions An array of comment actions. Default actions include:
+		 * @param string[]   $actions An array of comment actions. Default actions include:
 		 *                            'Approve', 'Unapprove', 'Edit', 'Reply', 'Spam',
 		 *                            'Delete', and 'Trash'.
 		 * @param WP_Comment $comment The comment object.

wp-admin/includes/export.php

@@ -340,7 +340,7 @@ function export_wp( $args = array() ) {
 	 *
 	 * @global wpdb $wpdb WordPress database abstraction object.
 	 *
-	 * @param array $post_ids Array of post IDs to filter the query by. Optional.
+	 * @param int[] $post_ids Optional. Array of post IDs to filter the query by.
 	 */
 	function wxr_authors_list( array $post_ids = null ) {
 		global $wpdb;

wp-admin/includes/media.php

@@ -2609,7 +2609,7 @@ foreach ( $post_mime_types as $mime_type => $label ) {
  *
  * @since 3.1.0
  *
- * @param array $type_links An array of list items containing mime type link HTML.
+ * @param string[] $type_links An array of list items containing mime type link HTML.
  */
 echo implode( ' | </li>', apply_filters( 'media_upload_mime_type_links', $type_links ) ) . '</li>';
 unset( $type_links );

wp-admin/includes/misc.php

@@ -556,7 +556,7 @@ function wp_doc_link_parse( $content ) {
 	 *
 	 * @since 2.8.0
 	 *
-	 * @param array $ignore_functions Functions and classes to be ignored.
+	 * @param string[] $ignore_functions Array of names of functions and classes to be ignored.
 	 */
 	$ignore_functions = apply_filters( 'documentation_ignore_functions', $ignore_functions );
 

wp-admin/includes/ms.php

@@ -126,8 +126,8 @@ function wpmu_delete_blog( $blog_id, $drop = false ) {
 		 *
 		 * @since MU (3.0.0)
 		 *
-		 * @param array $tables  The site tables to be dropped.
+		 * @param string[] $tables  Array of names of the site tables to be dropped.
-		 * @param int   $blog_id The ID of the site to drop tables for.
+		 * @param int      $blog_id The ID of the site to drop tables for.
 		 */
 		$drop_tables = apply_filters( 'wpmu_drop_tables', $tables, $blog_id );
 
@@ -665,8 +665,8 @@ function format_code_lang( $code = '' ) {
 	 *
 	 * @since MU (3.0.0)
 	 *
-	 * @param array  $lang_codes Key/value pair of language codes where key is the short version.
+	 * @param string[] $lang_codes Array of key/value pairs of language codes where key is the short version.
-	 * @param string $code       A two-letter designation of the language.
+	 * @param string   $code       A two-letter designation of the language.
 	 */
 	$lang_codes = apply_filters( 'lang_codes', $lang_codes, $code );
 	return strtr( $code, $lang_codes );
@@ -760,8 +760,8 @@ function check_import_new_users( $permission ) {
  *
  * @since 3.0.0
  *
- * @param array  $lang_files Optional. An array of the language files. Default empty array.
+ * @param string[] $lang_files Optional. An array of the language files. Default empty array.
- * @param string $current    Optional. The current language code. Default empty.
+ * @param string   $current    Optional. The current language code. Default empty.
  */
 function mu_dropdown_languages( $lang_files = array(), $current = '' ) {
 	$flag   = false;
@@ -796,9 +796,9 @@ function mu_dropdown_languages( $lang_files = array(), $current = '' ) {
 	 *
 	 * @since MU (3.0.0)
 	 *
-	 * @param array $output     HTML output of the dropdown.
+	 * @param string[] $output     Array of HTML output for the dropdown.
-	 * @param array $lang_files Available language files.
+	 * @param string[] $lang_files Array of available language files.
-	 * @param string $current   The current language code.
+	 * @param string   $current    The current language code.
 	 */
 	$output = apply_filters( 'mu_dropdown_languages', $output, $lang_files, $current );
 

wp-admin/includes/plugin.php

@@ -210,7 +210,7 @@ function get_plugin_files( $plugin ) {
 		 *
 		 * @since 4.9.0
 		 *
-		 * @param array $exclusions Array of excluded directories and files.
+		 * @param string[] $exclusions Array of excluded directories and files.
 		 */
 		$exclusions = (array) apply_filters( 'plugin_files_exclusions', array( 'CVS', 'node_modules', 'vendor', 'bower_components' ) );
 

wp-admin/includes/post.php

@@ -1267,7 +1267,7 @@ function postbox_classes( $id, $page ) {
 	 *
 	 * @since 3.2.0
 	 *
-	 * @param array $classes An array of postbox classes.
+	 * @param string[] $classes An array of postbox classes.
 	 */
 	$classes = apply_filters( "postbox_classes_{$page}_{$id}", $classes );
 	return implode( ' ', $classes );

wp-admin/includes/revision.php

@@ -130,7 +130,7 @@ function wp_get_revision_ui_diff( $post, $compare_from, $compare_to ) {
 	 *
 	 * @since 4.1.0
 	 *
-	 * @param array   $return       Revision UI fields. Each item is an array of id, name and diff.
+	 * @param array[] $return       Array of revision UI fields. Each item is an array of id, name, and diff.
 	 * @param WP_Post $compare_from The revision post to compare from.
 	 * @param WP_Post $compare_to   The revision post to compare to.
 	 */

wp-admin/includes/taxonomy.php

@@ -70,8 +70,8 @@ function wp_create_category( $cat_name, $parent = 0 ) {
  *
  * @since 2.0.0
  *
- * @param array $categories List of categories to create.
+ * @param string[] $categories Array of category names to create.
- * @param int   $post_id    Optional. The post ID. Default empty.
+ * @param int      $post_id    Optional. The post ID. Default empty.
  * @return array List of categories to create for the given post.
  */
 function wp_create_categories( $categories, $post_id = '' ) {

wp-admin/includes/template.php

@@ -29,8 +29,8 @@ require_once( ABSPATH . 'wp-admin/includes/class-wp-internal-pointers.php' );
  *                                     $selected_cats must not be an array. Default 0.
  * @param int    $descendants_and_self Optional. ID of the category to output along with its descendants.
  *                                     Default 0.
- * @param array  $selected_cats        Optional. List of categories to mark as checked. Default false.
+ * @param int[]  $selected_cats        Optional. Array of category IDs to mark as checked. Default false.
- * @param array  $popular_cats         Optional. List of categories to receive the "popular-category" class.
+ * @param int[]  $popular_cats         Optional. Array of category IDs to receive the "popular-category" class.
  *                                     Default false.
  * @param object $walker               Optional. Walker object to use to build the output.
  *                                     Default is a Walker_Category_Checklist instance.
@@ -64,8 +64,8 @@ function wp_category_checklist( $post_id = 0, $descendants_and_self = 0, $select
  *
  *     @type int    $descendants_and_self ID of the category to output along with its descendants.
  *                                        Default 0.
- *     @type array  $selected_cats        List of categories to mark as checked. Default false.
+ *     @type int[]  $selected_cats        Array of category IDs to mark as checked. Default false.
- *     @type array  $popular_cats         List of categories to receive the "popular-category" class.
+ *     @type int[]  $popular_cats         Array of category IDs to receive the "popular-category" class.
  *                                        Default false.
  *     @type object $walker               Walker object to use to build the output.
  *                                        Default is a Walker_Category_Checklist instance.
@@ -1897,8 +1897,8 @@ function _post_states( $post ) {
 	 * @since 2.8.0
 	 * @since 3.6.0 Added the `$post` parameter.
 	 *
-	 * @param array   $post_states An array of post display states.
+	 * @param string[] $post_states An array of post display states.
-	 * @param WP_Post $post        The current post object.
+	 * @param WP_Post  $post        The current post object.
 	 */
 	$post_states = apply_filters( 'display_post_states', $post_states, $post );
 
@@ -1973,9 +1973,9 @@ function _media_states( $post ) {
 	 * @since 3.2.0
 	 * @since 4.8.0 Added the `$post` parameter.
 	 *
-	 * @param array   $media_states An array of media states. Default 'Header Image',
+	 * @param string[] $media_states An array of media states. Default 'Header Image',
-	 *                              'Background Image', 'Site Icon', 'Logo'.
+	 *                               'Background Image', 'Site Icon', 'Logo'.
-	 * @param WP_Post $post         The current attachment object.
+	 * @param WP_Post  $post         The current attachment object.
 	 */
 	$media_states = apply_filters( 'display_media_states', $media_states, $post );
 

wp-admin/includes/theme.php

@@ -569,8 +569,8 @@ function themes_api( $action, $args = array() ) {
  *
  * @since 3.8.0
  *
- * @param array $themes Optional. Array of WP_Theme objects to prepare.
+ * @param WP_Theme[] $themes Optional. Array of theme objects to prepare.
- *                      Defaults to all allowed themes.
+ *                           Defaults to all allowed themes.
  *
  * @return array An associative array of theme data, sorted by name.
  */
@@ -585,9 +585,9 @@ function wp_prepare_themes_for_js( $themes = null ) {
 	 *
 	 * @since 4.2.0
 	 *
-	 * @param array      $prepared_themes An associative array of theme data. Default empty array.
+	 * @param array           $prepared_themes An associative array of theme data. Default empty array.
-	 * @param null|array $themes          An array of WP_Theme objects to prepare, if any.
+	 * @param WP_Theme[]|null $themes          An array of theme objects to prepare, if any.
-	 * @param string     $current_theme   The current theme slug.
+	 * @param string          $current_theme   The current theme slug.
 	 */
 	$prepared_themes = (array) apply_filters( 'pre_prepare_themes_for_js', array(), $themes, $current_theme );
 

wp-admin/includes/upgrade.php

@@ -2393,11 +2393,11 @@ function deslash( $content ) {
  *
  * @global wpdb  $wpdb
  *
- * @param string|array $queries Optional. The query to run. Can be multiple queries
+ * @param string[]|string $queries Optional. The query to run. Can be multiple queries
- *                              in an array, or a string of queries separated by
+ *                                 in an array, or a string of queries separated by
- *                              semicolons. Default empty.
+ *                                 semicolons. Default empty string.
- * @param bool         $execute Optional. Whether or not to execute the query right away.
+ * @param bool            $execute Optional. Whether or not to execute the query right away.
- *                              Default true.
+ *                                 Default true.
  * @return array Strings containing the results of the various update queries.
  */
 function dbDelta( $queries = '', $execute = true ) {
@@ -2418,7 +2418,7 @@ function dbDelta( $queries = '', $execute = true ) {
 	 *
 	 * @since 3.3.0
 	 *
-	 * @param array $queries An array of dbDelta SQL queries.
+	 * @param string[] $queries An array of dbDelta SQL queries.
 	 */
 	$queries = apply_filters( 'dbdelta_queries', $queries );
 
@@ -2449,7 +2449,7 @@ function dbDelta( $queries = '', $execute = true ) {
 	 *
 	 * @since 3.3.0
 	 *
-	 * @param array $cqueries An array of dbDelta create SQL queries.
+	 * @param string[] $cqueries An array of dbDelta create SQL queries.
 	 */
 	$cqueries = apply_filters( 'dbdelta_create_queries', $cqueries );
 
@@ -2460,7 +2460,7 @@ function dbDelta( $queries = '', $execute = true ) {
 	 *
 	 * @since 3.3.0
 	 *
-	 * @param array $iqueries An array of dbDelta insert or update SQL queries.
+	 * @param string[] $iqueries An array of dbDelta insert or update SQL queries.
 	 */
 	$iqueries = apply_filters( 'dbdelta_insert_queries', $iqueries );
 

wp-admin/includes/user.php

@@ -254,7 +254,7 @@ function edit_user( $user_id = 0 ) {
  *
  * @since 2.8.0
  *
- * @return array
+ * @return array[] Array of arrays containing role information.
  */
 function get_editable_roles() {
 	$all_roles = wp_roles()->roles;
@@ -264,7 +264,7 @@ function get_editable_roles() {
 	 *
 	 * @since 2.8.0
 	 *
-	 * @param array $all_roles List of roles.
+	 * @param array[] $all_roles Array of arrays containing role information.
 	 */
 	$editable_roles = apply_filters( 'editable_roles', $all_roles );
 
@@ -377,8 +377,8 @@ function wp_delete_user( $id, $reassign = null ) {
 		 *
 		 * @since 3.4.0
 		 *
-		 * @param array $post_types_to_delete Post types to delete.
+		 * @param string[] $post_types_to_delete Array of post types to delete.
-		 * @param int   $id                   User ID.
+		 * @param int      $id                   User ID.
 		 */
 		$post_types_to_delete = apply_filters( 'post_types_to_delete_with_user', $post_types_to_delete, $id );
 		$post_types_to_delete = implode( "', '", $post_types_to_delete );

wp-admin/maint/repair.php

@@ -89,7 +89,7 @@ if ( ! defined( 'WP_ALLOW_REPAIR' ) || ! WP_ALLOW_REPAIR ) {
 	 *
 	 * @since 3.0.0
 	 *
-	 * @param array $tables Array of prefixed table names to be repaired.
+	 * @param string[] $tables Array of prefixed table names to be repaired.
 	 */
 	$tables = array_merge( $tables, (array) apply_filters( 'tables_to_repair', array() ) );
 

wp-admin/network/settings.php

@@ -450,7 +450,7 @@ if ( isset( $_GET['updated'] ) ) {
 			 *
 			 * @since MU (3.0.0)
 			 *
-			 * @param array $admin_menus The menu items available.
+			 * @param string[] $admin_menus Associative array of the menu items available.
 			 */
 			$menu_items   = apply_filters( 'mu_menu_items', array( 'plugins' => __( 'Plugins' ) ) );
 			$fieldset_end = '';

wp-admin/options-discussion.php

@@ -268,7 +268,7 @@ $avatar_defaults = array(
  *
  * @since 2.6.0
  *
- * @param array $avatar_defaults Array of default avatars.
+ * @param string[] $avatar_defaults Associative array of default avatars.
  */
 $avatar_defaults = apply_filters( 'avatar_defaults', $avatar_defaults );
 $default         = get_option( 'avatar_default', 'mystery' );

wp-admin/options-general.php

@@ -324,7 +324,7 @@ if ( empty( $tzstring ) ) { // Create a UTC+- zone if no timezone string exists
 	 * @since 2.7.0
 	 * @since 4.0.0 Added ISO date standard YYYY-MM-DD format.
 	 *
-	 * @param array $default_date_formats Array of default date formats.
+	 * @param string[] $default_date_formats Array of default date formats.
 	 */
 	$date_formats = array_unique( apply_filters( 'date_formats', array( __( 'F j, Y' ), 'Y-m-d', 'm/d/Y', 'd/m/Y' ) ) );
 
@@ -361,7 +361,7 @@ foreach ( $date_formats as $format ) {
 	 *
 	 * @since 2.7.0
 	 *
-	 * @param array $default_time_formats Array of default time formats.
+	 * @param string[] $default_time_formats Array of default time formats.
 	 */
 	$time_formats = array_unique( apply_filters( 'time_formats', array( __( 'g:i a' ), 'g:i A', 'H:i' ) ) );
 

wp-admin/options-permalink.php

@@ -256,7 +256,7 @@ $structures = array(
 				 *
 				 * @since 4.8.0
 				 *
-				 * @param array $available_tags A key => value pair of available permalink structure tags.
+				 * @param string[] $available_tags An array of key => value pairs of available permalink structure tags.
 				 */
 				$available_tags = apply_filters( 'available_permalink_structure_tags', $available_tags );
 

wp-admin/plugins.php

@@ -567,7 +567,7 @@ if ( strlen( $s ) ) {
  *
  * @since 3.0.0
  *
- * @param array $plugins_all An array containing all installed plugins.
+ * @param array[] $plugins_all An array of arrays containing information on all installed plugins.
  */
 do_action( 'pre_current_active_plugins', $plugins['all'] );
 ?>

wp-admin/theme-install.php

@@ -143,7 +143,7 @@ include( ABSPATH . 'wp-admin/admin-header.php' );
 	 *
 	 * @since 2.8.0
 	 *
-	 * @param array $tabs The tabs shown on the Add Themes screen. Default is 'upload'.
+	 * @param string[] $tabs Associative array of the tabs shown on the Add Themes screen. Default is 'upload'.
 	 */
 	$tabs = apply_filters( 'install_themes_tabs', array( 'upload' => __( 'Upload Theme' ) ) );
 	if ( ! empty( $tabs['upload'] ) && current_user_can( 'upload_themes' ) ) {

wp-admin/users.php

@@ -317,7 +317,7 @@ foreach ( $userids as $id ) {
 	 * @since 4.5.0 The `$userids` parameter was added.
 	 *
 	 * @param WP_User $current_user WP_User object for the current user.
-	 * @param array   $userids      Array of IDs for users being deleted.
+	 * @param int[]   $userids      Array of IDs for users being deleted.
 	 */
 	do_action( 'delete_user_form', $current_user, $userids );
 	?>

wp-includes/capabilities.php

@@ -324,12 +324,12 @@ function map_meta_cap( $cap, $user_id ) {
 				 * @since 3.3.0 As `auth_post_meta_{$meta_key}`.
 				 * @since 4.6.0
 				 *
-				 * @param bool   $allowed   Whether the user can add the object meta. Default false.
+				 * @param bool     $allowed   Whether the user can add the object meta. Default false.
-				 * @param string $meta_key  The meta key.
+				 * @param string   $meta_key  The meta key.
-				 * @param int    $object_id Object ID.
+				 * @param int      $object_id Object ID.
-				 * @param int    $user_id   User ID.
+				 * @param int      $user_id   User ID.
-				 * @param string $cap       Capability name.
+				 * @param string   $cap       Capability name.
-				 * @param array  $caps      User capabilities.
+				 * @param string[] $caps      Array of the user's capabilities.
 				 */
 				$allowed = apply_filters( "auth_{$object_type}_meta_{$meta_key}", false, $meta_key, $object_id, $user_id, $cap, $caps );
 
@@ -345,12 +345,12 @@ function map_meta_cap( $cap, $user_id ) {
 				 * @since 4.6.0 As `auth_post_{$post_type}_meta_{$meta_key}`.
 				 * @since 4.7.0
 				 *
-				 * @param bool   $allowed   Whether the user can add the object meta. Default false.
+				 * @param bool     $allowed   Whether the user can add the object meta. Default false.
-				 * @param string $meta_key  The meta key.
+				 * @param string   $meta_key  The meta key.
-				 * @param int    $object_id Object ID.
+				 * @param int      $object_id Object ID.
-				 * @param int    $user_id   User ID.
+				 * @param int      $user_id   User ID.
-				 * @param string $cap       Capability name.
+				 * @param string   $cap       Capability name.
-				 * @param array  $caps      User capabilities.
+				 * @param string[] $caps      Array of the user's capabilities.
 				 */
 				$allowed = apply_filters( "auth_{$object_type}_{$sub_type}_meta_{$meta_key}", $allowed, $meta_key, $object_id, $user_id, $cap, $caps );
 
@@ -572,10 +572,10 @@ function map_meta_cap( $cap, $user_id ) {
 	 *
 	 * @since 2.8.0
 	 *
-	 * @param array  $caps    Returns the user's actual capabilities.
+	 * @param string[] $caps    Array of the user's capabilities.
-	 * @param string $cap     Capability name.
+	 * @param string   $cap     Capability name.
-	 * @param int    $user_id The user ID.
+	 * @param int      $user_id The user ID.
-	 * @param array  $args    Adds the context to the cap. Typically the object ID.
+	 * @param array    $args    Adds the context to the cap. Typically the object ID.
 	 */
 	return apply_filters( 'map_meta_cap', $caps, $cap, $user_id, $args );
 }
@@ -912,8 +912,8 @@ function revoke_super_admin( $user_id ) {
  *
  * @since 4.9.0
  *
- * @param array $allcaps An array of all the user's capabilities.
+ * @param bool[] $allcaps An array of all the user's capabilities.
- * @return array Filtered array of the user's capabilities.
+ * @return bool[] Filtered array of the user's capabilities.
  */
 function wp_maybe_grant_install_languages_cap( $allcaps ) {
 	if ( ! empty( $allcaps['update_core'] ) || ! empty( $allcaps['install_plugins'] ) || ! empty( $allcaps['install_themes'] ) ) {

wp-includes/category-template.php

@@ -71,7 +71,7 @@ function get_category_parents( $id, $link = false, $separator = '/', $nicename =
  * @since 0.71
  *
  * @param int $id Optional, default to current post ID. The post ID.
- * @return array Array of WP_Term objects, one for each category assigned to the post.
+ * @return WP_Term[] Array of WP_Term objects, one for each category assigned to the post.
  */
 function get_the_category( $id = false ) {
 	$categories = get_the_terms( $id, 'category' );
@@ -91,8 +91,8 @@ function get_the_category( $id = false ) {
 	 * @since 3.1.0
 	 * @since 4.4.0 Added `$id` parameter.
 	 *
-	 * @param array $categories An array of categories to return for the post.
+	 * @param WP_Term[] $categories An array of categories to return for the post.
-	 * @param int   $id         ID of the post.
+	 * @param int|false $id         ID of the post.
 	 */
 	return apply_filters( 'get_the_categories', $categories, $id );
 }
@@ -141,9 +141,9 @@ function get_the_category_list( $separator = '', $parents = '', $post_id = false
 	 *
 	 * @since 4.4.0
 	 *
-	 * @param array    $categories An array of the post's categories.
+	 * @param WP_Term[] $categories An array of the post's categories.
-	 * @param int|bool $post_id    ID of the post we're retrieving categories for. When `false`, we assume the
+	 * @param int|bool  $post_id    ID of the post we're retrieving categories for. When `false`, we assume the
-	 *                             current post in the loop.
+	 *                              current post in the loop.
 	 */
 	$categories = apply_filters( 'the_category_list', get_the_category( $post_id ), $post_id );
 
@@ -762,7 +762,7 @@ function default_topic_count_scale( $count ) {
  * @since 2.3.0
  * @since 4.8.0 Added the `show_count` argument.
  *
- * @param array $tags Array of WP_Term objects to generate the tag cloud for.
+ * @param WP_Term[]    $tags Array of WP_Term objects to generate the tag cloud for.
  * @param string|array $args {
  *     Optional. Array or string of arguments for generating a tag cloud.
  *
@@ -850,8 +850,8 @@ function wp_generate_tag_cloud( $tags, $args = '' ) {
 	 *
 	 * @since 2.8.0
 	 *
-	 * @param array $tags Ordered array of terms.
+	 * @param WP_Term[] $tags Ordered array of terms.
-	 * @param array $args An array of tag cloud arguments.
+	 * @param array     $args An array of tag cloud arguments.
 	 */
 	$tags_sorted = apply_filters( 'tag_cloud_sort', $tags, $args );
 	if ( empty( $tags_sorted ) ) {
@@ -1004,7 +1004,7 @@ function wp_generate_tag_cloud( $tags, $args = '' ) {
 		 * @param array|string $return String containing the generated HTML tag cloud output
 		 *                             or an array of tag links if the 'format' argument
 		 *                             equals 'array'.
-		 * @param array        $tags   An array of terms used in the tag cloud.
+		 * @param WP_Term[]    $tags   An array of terms used in the tag cloud.
 		 * @param array        $args   An array of wp_generate_tag_cloud() arguments.
 		 */
 		return apply_filters( 'wp_generate_tag_cloud', $return, $tags, $args );
@@ -1122,7 +1122,7 @@ function get_the_tags( $id = 0 ) {
 	 *
 	 * @see get_the_terms()
 	 *
-	 * @param array $terms An array of tags for the given post.
+	 * @param WP_Term[] $terms An array of tags for the given post.
 	 */
 	return apply_filters( 'get_the_tags', get_the_terms( $id, 'post_tag' ) );
 }
@@ -1213,10 +1213,10 @@ function term_description( $term = 0, $deprecated = null ) {
  *
  * @since 2.5.0
  *
- * @param int|object $post Post ID or object.
+ * @param int|WP_Post $post     Post ID or object.
- * @param string $taxonomy Taxonomy name.
+ * @param string      $taxonomy Taxonomy name.
- * @return array|false|WP_Error Array of WP_Term objects on success, false if there are no terms
+ * @return WP_Term[]|false|WP_Error Array of WP_Term objects on success, false if there are no terms
- *                              or the post does not exist, WP_Error on failure.
+ *                                  or the post does not exist, WP_Error on failure.
  */
 function get_the_terms( $post, $taxonomy ) {
 	if ( ! $post = get_post( $post ) ) {
@@ -1237,9 +1237,9 @@ function get_the_terms( $post, $taxonomy ) {
 	 *
 	 * @since 3.1.0
 	 *
-	 * @param array|WP_Error $terms    List of attached terms, or WP_Error on failure.
+	 * @param WP_Term[]|WP_Error $terms    Array of attached terms, or WP_Error on failure.
-	 * @param int            $post_id  Post ID.
+	 * @param int                $post_id  Post ID.
-	 * @param string         $taxonomy Name of the taxonomy.
+	 * @param string             $taxonomy Name of the taxonomy.
 	 */
 	$terms = apply_filters( 'get_the_terms', $terms, $post->ID, $taxonomy );
 
@@ -1291,7 +1291,7 @@ function get_the_term_list( $id, $taxonomy, $before = '', $sep = '', $after = ''
 	 *
 	 * @since 2.5.0
 	 *
-	 * @param array $links An array of term links.
+	 * @param string[] $links An array of term links.
 	 */
 	$term_links = apply_filters( "term_links-{$taxonomy}", $links );
 

wp-includes/category.php

@@ -273,7 +273,7 @@ function sanitize_category_field( $field, $value, $cat_id, $context ) {
  * @see get_terms() For list of arguments to pass.
  *
  * @param string|array $args Tag arguments to use when retrieving tags.
- * @return array List of tags.
+ * @return WP_Term[]|int $tags Array of 'post_tag' term objects, or a count thereof.
  */
 function get_tags( $args = '' ) {
 	$tags = get_terms( 'post_tag', $args );
@@ -288,8 +288,8 @@ function get_tags( $args = '' ) {
 	 *
 	 * @since 2.3.0
 	 *
-	 * @param array $tags Array of 'post_tag' term objects.
+	 * @param WP_Term[]|int $tags Array of 'post_tag' term objects, or a count thereof.
-	 * @param array $args An array of arguments. @see get_terms()
+	 * @param array         $args An array of arguments. @see get_terms()
 	 */
 	$tags = apply_filters( 'get_tags', $tags, $args );
 	return $tags;

wp-includes/class-oembed.php

@@ -215,7 +215,7 @@ class WP_oEmbed {
 		 *
 		 * @since 2.9.0
 		 *
-		 * @param array $providers An array of popular oEmbed providers.
+		 * @param array[] $providers An array of arrays containing data about popular oEmbed providers.
 		 */
 		$this->providers = apply_filters( 'oembed_providers', $providers );
 
@@ -446,9 +446,9 @@ class WP_oEmbed {
 			 *
 			 * @since 2.9.0
 			 *
-			 * @param array $format Array of oEmbed link types. Accepts 'application/json+oembed',
+			 * @param string[] $format Array of oEmbed link types. Accepts 'application/json+oembed',
-			 *                      'text/xml+oembed', and 'application/xml+oembed' (incorrect,
+			 *                         'text/xml+oembed', and 'application/xml+oembed' (incorrect,
-			 *                      used by at least Vimeo).
+			 *                         used by at least Vimeo).
 			 */
 			$linktypes = apply_filters(
 				'oembed_linktypes', array(

wp-includes/class-walker-nav-menu.php

@@ -68,7 +68,7 @@ class Walker_Nav_Menu extends Walker {
 		 *
 		 * @since 4.8.0
 		 *
-		 * @param array    $classes The CSS classes that are applied to the menu `<ul>` element.
+		 * @param string[] $classes Array of the CSS classes that are applied to the menu `<ul>` element.
 		 * @param stdClass $args    An object of `wp_nav_menu()` arguments.
 		 * @param int      $depth   Depth of menu item. Used for padding.
 		 */
@@ -145,7 +145,7 @@ class Walker_Nav_Menu extends Walker {
 		 * @since 3.0.0
 		 * @since 4.1.0 The `$depth` parameter was added.
 		 *
-		 * @param array    $classes The CSS classes that are applied to the menu item's `<li>` element.
+		 * @param string[] $classes Array of the CSS classes that are applied to the menu item's `<li>` element.
 		 * @param WP_Post  $item    The current menu item.
 		 * @param stdClass $args    An object of wp_nav_menu() arguments.
 		 * @param int      $depth   Depth of menu item. Used for padding.

wp-includes/class-walker-page.php

@@ -141,12 +141,11 @@ class Walker_Page extends Walker {
 		 *
 		 * @see wp_list_pages()
 		 *
-		 * @param array   $css_class    An array of CSS classes to be applied
+		 * @param string[] $css_class    An array of CSS classes to be applied to each list item.
-		 *                              to each list item.
+		 * @param WP_Post  $page         Page data object.
-		 * @param WP_Post $page         Page data object.
+		 * @param int      $depth        Depth of page, used for padding.
-		 * @param int     $depth        Depth of page, used for padding.
+		 * @param array    $args         An array of arguments.
-		 * @param array   $args         An array of arguments.
+		 * @param int      $current_page ID of the current page.
-		 * @param int     $current_page ID of the current page.
 		 */
 		$css_classes = implode( ' ', apply_filters( 'page_css_class', $css_class, $page, $depth, $args, $current_page ) );
 

wp-includes/class-wp-comment-query.php

@@ -449,8 +449,8 @@ class WP_Comment_Query {
 		 *
 		 * @since 3.1.0
 		 *
-		 * @param array            $_comments An array of comments.
+		 * @param WP_Comment[]     $_comments An array of comments.
-		 * @param WP_Comment_Query $this     Current instance of WP_Comment_Query (passed by reference).
+		 * @param WP_Comment_Query $this      Current instance of WP_Comment_Query (passed by reference).
 		 */
 		$_comments = apply_filters_ref_array( 'the_comments', array( $_comments, &$this ) );
 
@@ -849,8 +849,8 @@ class WP_Comment_Query {
 		 *
 		 * @since 3.1.0
 		 *
-		 * @param array            $pieces A compacted array of comment query clauses.
+		 * @param string[]         $pieces An associative array of comment query clauses.
-		 * @param WP_Comment_Query $this  Current instance of WP_Comment_Query (passed by reference).
+		 * @param WP_Comment_Query $this   Current instance of WP_Comment_Query (passed by reference).
 		 */
 		$clauses = apply_filters_ref_array( 'comments_clauses', array( compact( $pieces ), &$this ) );
 
@@ -932,7 +932,7 @@ class WP_Comment_Query {
 	 *
 	 * @global wpdb $wpdb WordPress database abstraction object.
 	 *
-	 * @param array $comments Array of top-level comments whose descendants should be filled in.
+	 * @param WP_Comment[] $comments Array of top-level comments whose descendants should be filled in.
 	 * @return array
 	 */
 	protected function fill_descendants( $comments ) {

wp-includes/class-wp-customize-manager.php

@@ -346,7 +346,7 @@ final class WP_Customize_Manager {
 		 *
 		 * @see WP_Customize_Manager::__construct()
 		 *
-		 * @param array                $components List of core components to load.
+		 * @param string[]             $components Array of core components to load.
 		 * @param WP_Customize_Manager $this       WP_Customize_Manager instance.
 		 */
 		$components = apply_filters( 'customize_loaded_components', $this->components, $this );
@@ -3094,11 +3094,11 @@ final class WP_Customize_Manager {
 	 * @see WP_Customize_Manager::save_changeset_post()
 	 * @see _wp_translate_postdata()
 	 *
-	 * @param array  $caps    Returns the user's actual capabilities.
+	 * @param string[] $caps    Array of the user's capabilities.
-	 * @param string $cap     Capability name.
+	 * @param string   $cap     Capability name.
-	 * @param int    $user_id The user ID.
+	 * @param int      $user_id The user ID.
-	 * @param array  $args    Adds the context to the cap. Typically the object ID.
+	 * @param array    $args    Adds the context to the cap. Typically the object ID.
-	 * @return array Capabilities.
+	 * @return array   Capabilities.
 	 */
 	public function grant_edit_post_capability_for_changeset( $caps, $cap, $user_id, $args ) {
 		if ( 'edit_post' === $cap && ! empty( $args[0] ) && 'customize_changeset' === get_post_type( $args[0] ) ) {
@@ -4506,7 +4506,7 @@ final class WP_Customize_Manager {
 		 *
 		 * @since 3.4.0
 		 *
-		 * @param array $allowed_urls An array of allowed URLs.
+		 * @param string[] $allowed_urls An array of allowed URLs.
 		 */
 		$allowed_urls = array_unique( apply_filters( 'customize_allowed_urls', $allowed_urls ) );
 
@@ -4619,7 +4619,7 @@ final class WP_Customize_Manager {
 		 *
 		 * @since 4.2.0
 		 *
-		 * @param array                $nonces Array of refreshed nonces for save and
+		 * @param string[]             $nonces Array of refreshed nonces for save and
 		 *                                     preview actions.
 		 * @param WP_Customize_Manager $this   WP_Customize_Manager instance.
 		 */

wp-includes/class-wp-customize-nav-menus.php

@@ -75,8 +75,8 @@ final class WP_Customize_Nav_Menus {
 	 *
 	 * @since 4.5.0
 	 *
-	 * @param array $nonces Array of nonces.
+	 * @param string[] $nonces Array of nonces.
-	 * @return array $nonces Modified array of nonces.
+	 * @return string[] $nonces Modified array of nonces.
 	 */
 	public function filter_nonces( $nonces ) {
 		$nonces['customize-menus'] = wp_create_nonce( 'customize-menus' );

wp-includes/class-wp-customize-widgets.php

@@ -905,8 +905,8 @@ final class WP_Customize_Widgets {
 	 *
 	 * @since 3.9.0
 	 *
-	 * @param array $widget_ids Array of widget IDs.
+	 * @param string[] $widget_ids Array of widget IDs.
-	 * @return array Array of sanitized widget IDs.
+	 * @return string[] Array of sanitized widget IDs.
 	 */
 	public function sanitize_sidebar_widgets( $widget_ids ) {
 		$widget_ids           = array_map( 'strval', (array) $widget_ids );

wp-includes/class-wp-theme.php

@@ -1536,7 +1536,7 @@ final class WP_Theme implements ArrayAccess {
 	 *
 	 * @since 3.4.0
 	 *
-	 * @param array $themes Array of themes to sort (passed by reference).
+	 * @param WP_Theme[] $themes Array of theme objects to sort (passed by reference).
 	 */
 	public static function sort_by_name( &$themes ) {
 		if ( 0 === strpos( get_user_locale(), 'en_' ) ) {

wp-includes/version.php

@@ -4,7 +4,7 @@
  *
  * @global string $wp_version
  */
-$wp_version = '5.0-alpha-42873';
+$wp_version = '5.0-alpha-42875';
 
 /**
  * Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.