From db4f746b4aa13ce87b065038c8dfea6f7dc9253b Mon Sep 17 00:00:00 2001
From: John Blackbourn <johnbillion@git.wordpress.org>
Date: Tue, 5 Nov 2019 21:21:46 +0000
Subject: [PATCH] Docs: Improve documentation of known return types, plus other
 docs fixes.

See #48303


git-svn-id: https://develop.svn.wordpress.org/trunk@46660 602fd350-edb4-49c9-b593-d223f7449a82
---
 src/wp-includes/comment-template.php          |  2 +-
 src/wp-includes/comment.php                   | 20 ++++++---
 .../class-wp-customize-media-control.php      |  2 +-
 .../class-wp-customize-nav-menu-setting.php   |  2 +-
 src/wp-includes/embed.php                     |  7 ++-
 src/wp-includes/formatting.php                |  2 +-
 src/wp-includes/functions.php                 | 15 +++----
 src/wp-includes/functions.wp-scripts.php      |  2 +-
 src/wp-includes/functions.wp-styles.php       |  2 +-
 src/wp-includes/general-template.php          |  2 +-
 src/wp-includes/kses.php                      |  6 +--
 src/wp-includes/l10n.php                      |  8 ++--
 src/wp-includes/load.php                      |  6 +--
 src/wp-includes/media.php                     | 23 ++++++----
 src/wp-includes/meta.php                      |  2 +-
 src/wp-includes/ms-blogs.php                  | 14 ++++--
 src/wp-includes/ms-deprecated.php             |  6 +--
 src/wp-includes/ms-functions.php              | 37 +++++++++++++---
 src/wp-includes/ms-load.php                   |  2 +-
 src/wp-includes/nav-menu.php                  |  4 +-
 src/wp-includes/post-formats.php              |  4 +-
 src/wp-includes/post.php                      | 44 +++++++++++--------
 src/wp-includes/query.php                     |  2 +-
 src/wp-includes/rest-api.php                  |  6 +--
 .../rest-api/class-wp-rest-request.php        | 10 ++---
 .../rest-api/class-wp-rest-server.php         | 10 ++---
 src/wp-includes/taxonomy.php                  |  8 ++--
 src/wp-includes/theme.php                     |  8 ++--
 src/wp-includes/user.php                      | 27 +++++++-----
 src/wp-includes/wp-db.php                     |  7 ++-
 src/wp-trackback.php                          |  6 +--
 31 files changed, 177 insertions(+), 119 deletions(-)

diff --git a/src/wp-includes/comment-template.php b/src/wp-includes/comment-template.php
index d08f5cf62e..42f3ef2023 100644
--- a/src/wp-includes/comment-template.php
+++ b/src/wp-includes/comment-template.php
@@ -452,7 +452,7 @@ function comment_class( $class = '', $comment = null, $post_id = null, $echo = t
  * @param string|array   $class      Optional. One or more classes to add to the class list. Default empty.
  * @param int|WP_Comment $comment_id Comment ID or WP_Comment object. Default current comment.
  * @param int|WP_Post    $post_id    Post ID or WP_Post object. Default current post.
- * @return array An array of classes.
+ * @return string[] An array of classes.
  */
 function get_comment_class( $class = '', $comment_id = null, $post_id = null ) {
 	global $comment_alt, $comment_depth, $comment_thread_alt;
diff --git a/src/wp-includes/comment.php b/src/wp-includes/comment.php
index 78413c3c3e..b4997d8798 100644
--- a/src/wp-includes/comment.php
+++ b/src/wp-includes/comment.php
@@ -251,7 +251,7 @@ function get_comments( $args = '' ) {
  *
  * @since 2.7.0
  *
- * @return array List of comment statuses.
+ * @return string[] List of comment status labels keyed by status.
  */
 function get_comment_statuses() {
 	$status = array(
@@ -1163,7 +1163,7 @@ function get_page_of_comment( $comment_ID, $args = array() ) {
  *
  * @global wpdb $wpdb WordPress database abstraction object.
  *
- * @return array Maximum character length for the comment form fields.
+ * @return int[] Array of maximum lengths keyed by field name.
  */
 function wp_get_comment_fields_max_lengths() {
 	global $wpdb;
@@ -1206,7 +1206,7 @@ function wp_get_comment_fields_max_lengths() {
 	 *
 	 * @since 4.5.0
 	 *
-	 * @param array $lengths Associative array `'field_name' => 'maximum length'`.
+	 * @param int[] $lengths Array of maximum lengths keyed by field name.
 	 */
 	return apply_filters( 'wp_get_comment_fields_max_lengths', $lengths );
 }
@@ -1778,7 +1778,13 @@ function _clear_modified_cache_on_transition_comment_status( $new_status, $old_s
  *
  * @since 2.0.4
  *
- * @return array Comment author, email, url respectively.
+ * @return array {
+ *     An array of current commenter variables.
+ *
+ *     @type string $comment_author       The name of the current commenter, or an empty string.
+ *     @type string $comment_author_email The email address of the current commenter, or an empty string.
+ *     @type string $comment_author_url   The URL address of the current commenter, or an empty string.
+ * }
  */
 function wp_get_current_commenter() {
 	// Cookies should already be sanitized.
@@ -1806,9 +1812,9 @@ function wp_get_current_commenter() {
 	 * @param array $comment_author_data {
 	 *     An array of current commenter variables.
 	 *
-	 *     @type string $comment_author       The name of the author of the comment. Default empty.
-	 *     @type string $comment_author_email The email address of the `$comment_author`. Default empty.
-	 *     @type string $comment_author_url   The URL address of the `$comment_author`. Default empty.
+	 *     @type string $comment_author       The name of the current commenter, or an empty string.
+	 *     @type string $comment_author_email The email address of the current commenter, or an empty string.
+	 *     @type string $comment_author_url   The URL address of the current commenter, or an empty string.
 	 * }
 	 */
 	return apply_filters( 'wp_get_current_commenter', compact( 'comment_author', 'comment_author_email', 'comment_author_url' ) );
diff --git a/src/wp-includes/customize/class-wp-customize-media-control.php b/src/wp-includes/customize/class-wp-customize-media-control.php
index 55f7b9b698..2856f3435a 100644
--- a/src/wp-includes/customize/class-wp-customize-media-control.php
+++ b/src/wp-includes/customize/class-wp-customize-media-control.php
@@ -207,7 +207,7 @@ class WP_Customize_Media_Control extends WP_Customize_Control {
 	 *
 	 * @since 4.9.0
 	 *
-	 * @return array An associative array of default button labels.
+	 * @return string[] An associative array of default button labels keyed by the button name.
 	 */
 	public function get_default_button_labels() {
 		// Get just the mime type and strip the mime subtype if present.
diff --git a/src/wp-includes/customize/class-wp-customize-nav-menu-setting.php b/src/wp-includes/customize/class-wp-customize-nav-menu-setting.php
index ac63a21a29..e6d74fd3b3 100644
--- a/src/wp-includes/customize/class-wp-customize-nav-menu-setting.php
+++ b/src/wp-includes/customize/class-wp-customize-nav-menu-setting.php
@@ -381,7 +381,7 @@ class WP_Customize_Nav_Menu_Setting extends WP_Customize_Setting {
 	 * @since 4.3.0
 	 *
 	 * @param array $nav_menu_options Nav menu options including auto_add.
-	 * @return array (Kaybe) modified nav menu options.
+	 * @return array (Maybe) modified nav menu options.
 	 */
 	public function filter_nav_menu_options( $nav_menu_options ) {
 		if ( $this->_previewed_blog_id !== get_current_blog_id() ) {
diff --git a/src/wp-includes/embed.php b/src/wp-includes/embed.php
index 2646a05556..a1e4b5e10d 100644
--- a/src/wp-includes/embed.php
+++ b/src/wp-includes/embed.php
@@ -58,7 +58,12 @@ function wp_embed_unregister_handler( $id, $priority = 10 ) {
  *
  * @param string $url Optional. The URL that should be embedded. Default empty.
  *
- * @return array Default embed parameters.
+ * @return array {
+ *     Indexed array of the embed width and height in pixels.
+ *
+ *     @type int $0 The embed width.
+ *     @type int $1 The embed height.
+ * }
  */
 function wp_embed_defaults( $url = '' ) {
 	if ( ! empty( $GLOBALS['content_width'] ) ) {
diff --git a/src/wp-includes/formatting.php b/src/wp-includes/formatting.php
index aed4819042..f7d248294c 100644
--- a/src/wp-includes/formatting.php
+++ b/src/wp-includes/formatting.php
@@ -622,7 +622,7 @@ function wpautop( $pee, $br = true ) {
  * @since 4.2.4
  *
  * @param string $input The text which has to be formatted.
- * @return array The formatted text.
+ * @return string[] Array of the formatted text.
  */
 function wp_html_split( $input ) {
 	return preg_split( get_html_split_regex(), $input, -1, PREG_SPLIT_DELIM_CAPTURE );
diff --git a/src/wp-includes/functions.php b/src/wp-includes/functions.php
index 995268fd41..3ac199e1f0 100644
--- a/src/wp-includes/functions.php
+++ b/src/wp-includes/functions.php
@@ -766,7 +766,7 @@ function xmlrpc_removepostdata( $content ) {
  * @since 3.7.0
  *
  * @param string $content Content to extract URLs from.
- * @return array URLs found in passed string.
+ * @return string[] Array of URLs found in passed string.
  */
 function wp_extract_urls( $content ) {
 	preg_match_all(
@@ -2487,7 +2487,7 @@ function wp_unique_filename( $dir, $filename, $unique_filename_callback = null )
  *
  * @param string       $name       Filename.
  * @param null|string  $deprecated Never used. Set to null.
- * @param mixed        $bits       File content
+ * @param string       $bits       File content
  * @param string       $time       Optional. Time formatted in 'yyyy/mm'. Default null.
  * @return array
  */
@@ -3003,7 +3003,7 @@ function wp_get_mime_types() {
  *
  * @since 4.6.0
  *
- * @return array Array of file extensions types keyed by the type of file.
+ * @return array[] Multi-dimensional array of file extensions types keyed by the type of file.
  */
 function wp_get_ext_types() {
 
@@ -3014,8 +3014,7 @@ function wp_get_ext_types() {
 	 *
 	 * @see wp_ext2type()
 	 *
-	 * @param array $ext2type Multi-dimensional array with extensions for a default set
-	 *                        of file types.
+	 * @param array[] $ext2type Multi-dimensional array of file extensions types keyed by the type of file.
 	 */
 	return apply_filters(
 		'ext2type',
@@ -4262,7 +4261,7 @@ function wp_parse_list( $list ) {
  * @since 3.0.0
  *
  * @param array|string $list List of ids.
- * @return array Sanitized array of IDs.
+ * @return int[] Sanitized array of IDs.
  */
 function wp_parse_id_list( $list ) {
 	$list = wp_parse_list( $list );
@@ -4276,7 +4275,7 @@ function wp_parse_id_list( $list ) {
  * @since 4.7.0
  *
  * @param  array|string $list List of slugs.
- * @return array Sanitized array of slugs.
+ * @return string[] Sanitized array of slugs.
  */
 function wp_parse_slug_list( $list ) {
 	$list = wp_parse_list( $list );
@@ -5842,7 +5841,7 @@ function wp_scheduled_delete() {
  * @param array  $default_headers List of headers, in the format `array( 'HeaderKey' => 'Header Name' )`.
  * @param string $context         Optional. If specified adds filter hook {@see 'extra_$context_headers'}.
  *                                Default empty.
- * @return array Array of file headers in `HeaderKey => Header Value` format.
+ * @return string[] Array of file header values keyed by header name.
  */
 function get_file_data( $file, $default_headers, $context = '' ) {
 	// We don't need to write to the file, so just open for reading.
diff --git a/src/wp-includes/functions.wp-scripts.php b/src/wp-includes/functions.wp-scripts.php
index c9acb98712..f7f88de2ae 100644
--- a/src/wp-includes/functions.wp-scripts.php
+++ b/src/wp-includes/functions.wp-scripts.php
@@ -65,7 +65,7 @@ function _wp_scripts_maybe_doing_it_wrong( $function ) {
  * @since 2.1.0
  *
  * @param string|bool|array $handles Optional. Scripts to be printed. Default 'false'.
- * @return array On success, a processed array of WP_Dependencies items; otherwise, an empty array.
+ * @return string[] On success, an array of handles of processed WP_Dependencies items; otherwise, an empty array.
  */
 function wp_print_scripts( $handles = false ) {
 	/**
diff --git a/src/wp-includes/functions.wp-styles.php b/src/wp-includes/functions.wp-styles.php
index 90ffff1e6b..a60a9d6224 100644
--- a/src/wp-includes/functions.wp-styles.php
+++ b/src/wp-includes/functions.wp-styles.php
@@ -37,7 +37,7 @@ function wp_styles() {
  * @since 2.6.0
  *
  * @param string|bool|array $handles Styles to be printed. Default 'false'.
- * @return array On success, a processed array of WP_Dependencies items; otherwise, an empty array.
+ * @return string[] On success, an array of handles of processed WP_Dependencies items; otherwise, an empty array.
  */
 function wp_print_styles( $handles = false ) {
 	if ( '' === $handles ) { // for wp_head
diff --git a/src/wp-includes/general-template.php b/src/wp-includes/general-template.php
index b88954081e..b8de168861 100644
--- a/src/wp-includes/general-template.php
+++ b/src/wp-includes/general-template.php
@@ -3286,7 +3286,7 @@ function wp_resource_hints() {
  *
  * @since 4.6.0
  *
- * @return array A list of unique hosts of enqueued scripts and styles.
+ * @return string[] A list of unique hosts of enqueued scripts and styles.
  */
 function wp_dependencies_unique_hosts() {
 	global $wp_scripts, $wp_styles;
diff --git a/src/wp-includes/kses.php b/src/wp-includes/kses.php
index 07edc91ea9..9c57c3a8e5 100644
--- a/src/wp-includes/kses.php
+++ b/src/wp-includes/kses.php
@@ -948,7 +948,7 @@ function wp_kses_split( $string, $allowed_html, $allowed_protocols ) {
 }
 
 /**
- * Helper function listing HTML attributes containing a URL.
+ * Returns an array of HTML attribute names whose value contains a URL.
  *
  * This function returns a list of all HTML attributes that must contain
  * a URL according to the HTML specification.
@@ -959,7 +959,7 @@ function wp_kses_split( $string, $allowed_html, $allowed_protocols ) {
  *
  * @since 5.0.1
  *
- * @return array HTML attributes that must include a URL.
+ * @return string[] HTML attribute names whose value contains a URL.
  */
 function wp_kses_uri_attributes() {
 	$uri_attributes = array(
@@ -990,7 +990,7 @@ function wp_kses_uri_attributes() {
 	 *
 	 * @since 5.0.1
 	 *
-	 * @param array $uri_attributes HTML attributes requiring validation as a URL.
+	 * @param string[] $uri_attributes HTML attribute names whose value contains a URL.
 	 */
 	$uri_attributes = apply_filters( 'wp_kses_uri_attributes', $uri_attributes );
 
diff --git a/src/wp-includes/l10n.php b/src/wp-includes/l10n.php
index ce9aa7ec29..0fbc57f3c4 100644
--- a/src/wp-includes/l10n.php
+++ b/src/wp-includes/l10n.php
@@ -1297,7 +1297,7 @@ function translate_user_role( $name, $domain = 'default' ) {
  *
  * @param string $dir A directory to search for language files.
  *                    Default WP_LANG_DIR.
- * @return array An array of language codes or an empty array if no languages are present. Language codes are formed by stripping the .mo extension from the language file names.
+ * @return string[] An array of language codes or an empty array if no languages are present. Language codes are formed by stripping the .mo extension from the language file names.
  */
 function get_available_languages( $dir = null ) {
 	$languages = array();
@@ -1318,8 +1318,8 @@ function get_available_languages( $dir = null ) {
 	 *
 	 * @since 4.7.0
 	 *
-	 * @param array  $languages An array of available language codes.
-	 * @param string $dir       The directory where the language files were found.
+	 * @param string[] $languages An array of available language codes.
+	 * @param string   $dir       The directory where the language files were found.
 	 */
 	return apply_filters( 'get_available_languages', $languages, $dir );
 }
@@ -1386,7 +1386,7 @@ function wp_get_installed_translations( $type ) {
  * @since 3.7.0
  *
  * @param string $po_file Path to PO file.
- * @return array PO file headers.
+ * @return string[] Array of PO file header values keyed by header name.
  */
 function wp_get_pomo_file_data( $po_file ) {
 	$headers = get_file_data(
diff --git a/src/wp-includes/load.php b/src/wp-includes/load.php
index fe1213a74f..d8e80fb178 100644
--- a/src/wp-includes/load.php
+++ b/src/wp-includes/load.php
@@ -625,7 +625,7 @@ function wp_not_installed() {
  * @since 3.0.0
  * @access private
  *
- * @return array Files to include.
+ * @return string[] Array of absolute paths of files to include.
  */
 function wp_get_mu_plugins() {
 	$mu_plugins = array();
@@ -736,7 +736,7 @@ function wp_skip_paused_plugins( array $plugins ) {
  * @since 5.1.0
  * @access private
  *
- * @return array Array of paths to theme directories.
+ * @return string[] Array of absolute paths to theme directories.
  */
 function wp_get_active_and_valid_themes() {
 	global $pagenow;
@@ -775,7 +775,7 @@ function wp_get_active_and_valid_themes() {
  * @since 5.2.0
  *
  * @param string[] $themes Array of absolute theme directory paths.
- * @return string[] Filtered array of themes, without any paused themes.
+ * @return string[] Filtered array of absolute paths to themes, without any paused themes.
  */
 function wp_skip_paused_themes( array $themes ) {
 	$paused_themes = wp_paused_themes()->get_all();
diff --git a/src/wp-includes/media.php b/src/wp-includes/media.php
index 4ead3ab8cd..861e6e27bf 100644
--- a/src/wp-includes/media.php
+++ b/src/wp-includes/media.php
@@ -845,11 +845,11 @@ function image_get_intermediate_size( $post_id, $size = 'thumbnail' ) {
 }
 
 /**
- * Gets the available intermediate image sizes.
+ * Gets the available intermediate image size names.
  *
  * @since 3.0.0
  *
- * @return array Returns a filtered array of image size strings.
+ * @return string[] An array of image size names.
  */
 function get_intermediate_image_sizes() {
 	$default_sizes    = array( 'thumbnail', 'medium', 'medium_large', 'large' );
@@ -864,8 +864,8 @@ function get_intermediate_image_sizes() {
 	 *
 	 * @since 2.5.0
 	 *
-	 * @param array $default_sizes An array of intermediate image sizes. Defaults
-	 *                             are 'thumbnail', 'medium', 'medium_large', 'large'.
+	 * @param string[] $default_sizes An array of intermediate image size names. Defaults
+	 *                                are 'thumbnail', 'medium', 'medium_large', 'large'.
 	 */
 	return apply_filters( 'intermediate_image_sizes', $default_sizes );
 }
@@ -2436,7 +2436,7 @@ function wp_get_audio_extensions() {
  *
  * @param WP_Post $attachment The current attachment, provided for context.
  * @param string  $context    Optional. The context. Accepts 'edit', 'display'. Default 'display'.
- * @return array Key/value pairs of field keys to labels.
+ * @return string[] Key/value pairs of field keys to labels.
  */
 function wp_get_attachment_id3_keys( $attachment, $context = 'display' ) {
 	$fields = array(
@@ -3046,7 +3046,7 @@ function adjacent_image_link( $prev = true, $size = 'thumbnail', $text = false )
  * @param string           $output     Output type. 'names' to return an array of taxonomy names,
  *                                     or 'objects' to return an array of taxonomy objects.
  *                                     Default is 'names'.
- * @return array Empty array on failure. List of taxonomies on success.
+ * @return string[]|WP_Taxonomy[] List of taxonomies or taxonomy names. Empty array on failure.
  */
 function get_attachment_taxonomies( $attachment, $output = 'names' ) {
 	if ( is_int( $attachment ) ) {
@@ -3159,7 +3159,12 @@ function wp_imagecreatetruecolor( $width, $height ) {
  * @param int $example_height The height of an example embed.
  * @param int $max_width      The maximum allowed width.
  * @param int $max_height     The maximum allowed height.
- * @return array The maximum possible width and height based on the example ratio.
+ * @return int[] {
+ *     An array of maximum width and height values.
+ *
+ *     @type int $0 The maximum width in pixels.
+ *     @type int $1 The maximum height in pixels.
+ * }
  */
 function wp_expand_dimensions( $example_width, $example_height, $max_width, $max_height ) {
 	$example_width  = (int) $example_width;
@@ -4226,7 +4231,7 @@ function get_post_galleries_images( $post = 0 ) {
  * @see get_post_gallery()
  *
  * @param int|WP_Post $post Optional. Post ID or WP_Post object. Default is global `$post`.
- * @return array A list of a gallery's image srcs in order.
+ * @return string[] A list of a gallery's image srcs in order.
  */
 function get_post_gallery_images( $post = 0 ) {
 	$gallery = get_post_gallery( $post, false );
@@ -4312,7 +4317,7 @@ function attachment_url_to_postid( $url ) {
  *
  * @since 4.0.0
  *
- * @return array The relevant CSS file URLs.
+ * @return string[] The relevant CSS file URLs.
  */
 function wpview_media_sandbox_styles() {
 	$version        = 'ver=' . get_bloginfo( 'version' );
diff --git a/src/wp-includes/meta.php b/src/wp-includes/meta.php
index 5770645e09..c7627fb26e 100644
--- a/src/wp-includes/meta.php
+++ b/src/wp-includes/meta.php
@@ -1317,7 +1317,7 @@ function unregister_meta_key( $object_type, $meta_key, $object_subtype = '' ) {
  *
  * @param string $object_type    The type of object. Post, comment, user, term.
  * @param string $object_subtype Optional. The subtype of the object type.
- * @return array List of registered meta keys.
+ * @return string[] List of registered meta keys.
  */
 function get_registered_meta_keys( $object_type, $object_subtype = '' ) {
 	global $wp_meta_keys;
diff --git a/src/wp-includes/ms-blogs.php b/src/wp-includes/ms-blogs.php
index 2874f7e1f0..5de82cb7f4 100644
--- a/src/wp-includes/ms-blogs.php
+++ b/src/wp-includes/ms-blogs.php
@@ -859,9 +859,17 @@ function _update_posts_count_on_transition_post_status( $new_status, $old_status
  *
  * @since 5.3.0
  *
- * @param int $network_id The network to get counts for.  Default is the current network id.
- * @return array Includes a grand total 'all' and an array of counts indexed by
- *                status strings: public, archived, mature, spam, deleted.
+ * @param int $network_id Optional. The network to get counts for. Default is the current network ID.
+ * @return int[] {
+ *     Numbers of sites grouped by site status.
+ *
+ *     @type int $all      The total number of sites.
+ *     @type int $public   The number of public sites.
+ *     @type int $archived The number of archived sites.
+ *     @type int $mature   The number of mature sites.
+ *     @type int $spam     The number of spam sites.
+ *     @type int $deleted  The number of deleted sites.
+ * }
  */
 function wp_count_sites( $network_id = null ) {
 	if ( empty( $network_id ) ) {
diff --git a/src/wp-includes/ms-deprecated.php b/src/wp-includes/ms-deprecated.php
index 0ceab16eda..131c6da0cd 100644
--- a/src/wp-includes/ms-deprecated.php
+++ b/src/wp-includes/ms-deprecated.php
@@ -472,10 +472,8 @@ function get_admin_users_for_domain( $domain = '', $path = '' ) {
  *     @type int       $limit      Number of sites to limit the query to. Default 100.
  *     @type int       $offset     Exclude the first x sites. Used in combination with the $limit parameter. Default 0.
  * }
- * @return array An empty array if the installation is considered "large" via wp_is_large_network(). Otherwise,
- *               an associative array of site data arrays, each containing the site (network) ID, blog ID,
- *               site domain and path, dates registered and modified, and the language ID. Also, boolean
- *               values for whether the site is public, archived, mature, spam, and/or deleted.
+ * @return array[] An empty array if the installation is considered "large" via wp_is_large_network(). Otherwise,
+ *                 an associative array of WP_Site data as arrays.
  */
 function wp_get_sites( $args = array() ) {
 	_deprecated_function( __FUNCTION__, '4.6.0', 'get_sites()' );
diff --git a/src/wp-includes/ms-functions.php b/src/wp-includes/ms-functions.php
index a87f44175a..2f16281754 100644
--- a/src/wp-includes/ms-functions.php
+++ b/src/wp-includes/ms-functions.php
@@ -12,7 +12,12 @@
  *
  * @since MU (3.0.0)
  *
- * @return array Site and user count for the network.
+ * @return int[] {
+ *     Site and user count for the network.
+ *
+ *     @type int $blogs Number of sites on the network.
+ *     @type int $users Number of users on the network.
+ * }
  */
 function get_sitestats() {
 	$stats = array(
@@ -443,7 +448,14 @@ function is_email_address_unsafe( $user_email ) {
  *
  * @param string $user_name  The login name provided by the user.
  * @param string $user_email The email provided by the user.
- * @return array Contains username, email, and error messages.
+ * @return array {
+ *     The array of user name, email, and the error messages.
+ *
+ *     @type string   $user_name     Sanitized and unique username.
+ *     @type string   $orig_username Original username.
+ *     @type string   $user_email    User email address.
+ *     @type WP_Error $errors        WP_Error object containing any errors found.
+ * }
  */
 function wpmu_validate_user_signup( $user_name, $user_email ) {
 	global $wpdb;
@@ -559,7 +571,7 @@ function wpmu_validate_user_signup( $user_name, $user_email ) {
 	 * @since MU (3.0.0)
 	 *
 	 * @param array $result {
-	 *     The array of user name, email and the error messages.
+	 *     The array of user name, email, and the error messages.
 	 *
 	 *     @type string   $user_name     Sanitized and unique username.
 	 *     @type string   $orig_username Original username.
@@ -592,7 +604,16 @@ function wpmu_validate_user_signup( $user_name, $user_email ) {
  * @param string         $blogname   The blog name provided by the user. Must be unique.
  * @param string         $blog_title The blog title provided by the user.
  * @param WP_User|string $user       Optional. The user object to check against the new site name.
- * @return array Contains the new site data and error messages.
+ * @return array {
+ *     Array of domain, path, blog name, blog title, user and error messages.
+ *
+ *     @type string         $domain     Domain for the site.
+ *     @type string         $path       Path for the site. Used in subdirectory installations.
+ *     @type string         $blogname   The unique site name (slug).
+ *     @type string         $blog_title Blog title.
+ *     @type string|WP_User $user       By default, an empty string. A user object if provided.
+ *     @type WP_Error       $errors     WP_Error containing any errors found.
+ * }
  */
 function wpmu_validate_blog_signup( $blogname, $blog_title, $user = '' ) {
 	global $wpdb, $domain;
@@ -1973,7 +1994,11 @@ function global_terms( $term_id, $deprecated = '' ) {
  * @since MU (3.0.0)
  *
  * @param array|string $deprecated Not used.
- * @return array The current site's domain
+ * @return string[] {
+ *     An array containing the current site's domain.
+ *
+ *     @type string $0 The current site's domain.
+ * }
  */
 function redirect_this_site( $deprecated = '' ) {
 	return array( get_network()->domain );
@@ -2577,7 +2602,7 @@ function wp_is_large_network( $using = 'sites', $network_id = null ) {
  *
  * @since 4.4.0
  *
- * @return array Array of reserved subdirectory names.
+ * @return string[] Array of reserved names.
  */
 function get_subdirectory_reserved_names() {
 	$names = array(
diff --git a/src/wp-includes/ms-load.php b/src/wp-includes/ms-load.php
index a846f7026f..c2ed6a28c2 100644
--- a/src/wp-includes/ms-load.php
+++ b/src/wp-includes/ms-load.php
@@ -32,7 +32,7 @@ function is_subdomain_install() {
  * @access private
  * @since 3.1.0
  *
- * @return array Files to include.
+ * @return string[] Array of absolute paths to files to include.
  */
 function wp_get_active_network_plugins() {
 	$active_plugins = (array) get_site_option( 'active_sitewide_plugins', array() );
diff --git a/src/wp-includes/nav-menu.php b/src/wp-includes/nav-menu.php
index 7b6435597b..0f7fa8d459 100644
--- a/src/wp-includes/nav-menu.php
+++ b/src/wp-includes/nav-menu.php
@@ -600,7 +600,7 @@ function wp_update_nav_menu_item( $menu_id = 0, $menu_item_db_id = 0, $menu_item
  *
  * @param array $args Optional. Array of arguments passed on to get_terms().
  *                    Default empty array.
- * @return array Menu objects.
+ * @return WP_Term[] An array of menu objects.
  */
 function wp_get_nav_menus( $args = array() ) {
 	$defaults = array(
@@ -984,7 +984,7 @@ function wp_setup_nav_menu_item( $menu_item ) {
  * @param int    $object_id   The ID of the original object.
  * @param string $object_type The type of object, such as "taxonomy" or "post_type."
  * @param string $taxonomy    If $object_type is "taxonomy", $taxonomy is the name of the tax that $object_id belongs to
- * @return array The array of menu item IDs; empty array if none;
+ * @return int[] The array of menu item IDs; empty array if none;
  */
 function wp_get_associated_nav_menu_items( $object_id = 0, $object_type = 'post_type', $taxonomy = '' ) {
 	$object_id     = (int) $object_id;
diff --git a/src/wp-includes/post-formats.php b/src/wp-includes/post-formats.php
index 44d363a713..7b5b145699 100644
--- a/src/wp-includes/post-formats.php
+++ b/src/wp-includes/post-formats.php
@@ -90,7 +90,7 @@ function set_post_format( $post, $format ) {
  *
  * @since 3.1.0
  *
- * @return array The array of translated post format names.
+ * @return string[] Array of post format labels keyed by format slug.
  */
 function get_post_format_strings() {
 	$strings = array(
@@ -113,7 +113,7 @@ function get_post_format_strings() {
  *
  * @since 3.1.0
  *
- * @return array The array of post format slugs as both keys and values.
+ * @return string[] The array of post format slugs as both keys and values.
  */
 function get_post_format_slugs() {
 	$slugs = array_keys( get_post_format_strings() );
diff --git a/src/wp-includes/post.php b/src/wp-includes/post.php
index 1ba7dfb41f..387ef2b951 100644
--- a/src/wp-includes/post.php
+++ b/src/wp-includes/post.php
@@ -706,7 +706,13 @@ function get_children( $args = '', $output = OBJECT ) {
  * @since 1.0.0
  *
  * @param string $post Post content.
- * @return array Post before ('main'), after ('extended'), and custom read more ('more_text').
+ * @return string[] {
+ *     Extended entry info.
+ *
+ *     @type string $main      Content before the more tag.
+ *     @type string $extended  Content after the more tag.
+ *     @type string $more_text Custom read more text, or empty string.
+ * }
  */
 function get_extended( $post ) {
 	//Match the new style more links.
@@ -790,7 +796,7 @@ function get_post( $post = null, $output = OBJECT, $filter = 'raw' ) {
  * @since 2.5.0
  *
  * @param int|WP_Post $post Post ID or post object.
- * @return array Ancestor IDs or empty array if none are found.
+ * @return int[] Ancestor IDs or empty array if none are found.
  */
 function get_post_ancestors( $post ) {
 	$post = get_post( $post );
@@ -930,7 +936,7 @@ function get_post_status( $post = null ) {
  *
  * @since 2.5.0
  *
- * @return array List of post statuses.
+ * @return string[] Array of post status labels keyed by their status.
  */
 function get_post_statuses() {
 	$status = array(
@@ -951,7 +957,7 @@ function get_post_statuses() {
  *
  * @since 2.5.0
  *
- * @return array List of page statuses.
+ * @return string[] Array of page status labels keyed by their status.
  */
 function get_page_statuses() {
 	$status = array(
@@ -1916,7 +1922,7 @@ function post_type_supports( $post_type, $feature ) {
  *                               only one element from the array needs to match; 'and'
  *                               means all elements must match; 'not' means no elements may
  *                               match. Default 'and'.
- * @return array A list of post type names.
+ * @return string[] A list of post type names.
  */
 function get_post_types_by_support( $feature, $operator = 'and' ) {
 	global $_wp_post_type_features;
@@ -4706,7 +4712,7 @@ function add_ping( $post_id, $uri ) {
  * @since 1.5.0
  *
  * @param int $post_id Post ID.
- * @return array List of enclosures.
+ * @return string[] Array of enclosures for the given post.
  */
 function get_enclosed( $post_id ) {
 	$custom_fields = get_post_custom( $post_id );
@@ -4833,7 +4839,7 @@ function trackback_url_list( $tb_list, $post_id ) {
  *
  * @global wpdb $wpdb WordPress database abstraction object.
  *
- * @return array List of page IDs.
+ * @return string[] List of page IDs as strings.
  */
 function get_all_page_ids() {
 	global $wpdb;
@@ -4855,12 +4861,12 @@ function get_all_page_ids() {
  * @since 1.5.1
  * @deprecated 3.5.0 Use get_post()
  *
- * @param mixed  $page   Page object or page ID. Passed by reference.
- * @param string $output Optional. The required return type. One of OBJECT, ARRAY_A, or ARRAY_N, which correspond to
- *                       a WP_Post object, an associative array, or a numeric array, respectively. Default OBJECT.
- * @param string $filter Optional. How the return value should be filtered. Accepts 'raw',
- *                       'edit', 'db', 'display'. Default 'raw'.
- * @return WP_Post|array|null WP_Post (or array) on success, or null on failure.
+ * @param int|WP_Post $page   Page object or page ID. Passed by reference.
+ * @param string      $output Optional. The required return type. One of OBJECT, ARRAY_A, or ARRAY_N, which correspond to
+ *                            a WP_Post object, an associative array, or a numeric array, respectively. Default OBJECT.
+ * @param string      $filter Optional. How the return value should be filtered. Accepts 'raw',
+ *                            'edit', 'db', 'display'. Default 'raw'.
+ * @return WP_Post|array|null WP_Post or array on success, null on failure.
  */
 function get_page( $page, $output = OBJECT, $filter = 'raw' ) {
 	return get_post( $page, $output, $filter );
@@ -6293,12 +6299,12 @@ function get_private_posts_cap_sql( $post_type ) {
  * @see get_private_posts_cap_sql()
  * @global wpdb $wpdb WordPress database abstraction object.
  *
- * @param array|string   $post_type   Single post type or an array of post types.
- * @param bool           $full        Optional. Returns a full WHERE statement instead of just
- *                                    an 'andalso' term. Default true.
- * @param int            $post_author Optional. Query posts having a single author ID. Default null.
- * @param bool           $public_only Optional. Only return public posts. Skips cap checks for
- *                                    $current_user.  Default false.
+ * @param string|string[] $post_type   Single post type or an array of post types.
+ * @param bool            $full        Optional. Returns a full WHERE statement instead of just
+ *                                     an 'andalso' term. Default true.
+ * @param int             $post_author Optional. Query posts having a single author ID. Default null.
+ * @param bool            $public_only Optional. Only return public posts. Skips cap checks for
+ *                                     $current_user.  Default false.
  * @return string SQL WHERE code that can be added to a query.
  */
 function get_posts_by_author_sql( $post_type, $full = true, $post_author = null, $public_only = false ) {
diff --git a/src/wp-includes/query.php b/src/wp-includes/query.php
index 75c93d6aa1..ae2ff97c46 100644
--- a/src/wp-includes/query.php
+++ b/src/wp-includes/query.php
@@ -91,7 +91,7 @@ function set_query_var( $var, $value ) {
  * @global WP_Query $wp_query WordPress Query object.
  *
  * @param array|string $query Array or string of WP_Query arguments.
- * @return array List of post objects.
+ * @return WP_Post[]|int[] Array of post objects or post IDs.
  */
 function query_posts( $query ) {
 	$GLOBALS['wp_query'] = new WP_Query();
diff --git a/src/wp-includes/rest-api.php b/src/wp-includes/rest-api.php
index ae4f609ac0..1d223531de 100644
--- a/src/wp-includes/rest-api.php
+++ b/src/wp-includes/rest-api.php
@@ -1165,7 +1165,7 @@ function rest_is_boolean( $maybe_bool ) {
  *
  * @param mixed $id_or_email The Gravatar to retrieve a URL for. Accepts a user_id, gravatar md5 hash,
  *                           user email, WP_User object, WP_Post object, or WP_Comment object.
- * @return array Gravatar url for each size.
+ * @return array Avatar URLs keyed by size. Each value can be a URL string or boolean false.
  */
 function rest_get_avatar_urls( $id_or_email ) {
 	$avatar_sizes = rest_get_avatar_sizes();
@@ -1183,7 +1183,7 @@ function rest_get_avatar_urls( $id_or_email ) {
  *
  * @since 4.7.0
  *
- * @return array List of pixel sizes for avatars. Default `[ 24, 48, 96 ]`.
+ * @return int[] List of pixel sizes for avatars. Default `[ 24, 48, 96 ]`.
  */
 function rest_get_avatar_sizes() {
 	/**
@@ -1194,7 +1194,7 @@ function rest_get_avatar_sizes() {
 	 *
 	 * @since 4.4.0
 	 *
-	 * @param array $sizes An array of int values that are the pixel sizes for avatars.
+	 * @param int[] $sizes An array of int values that are the pixel sizes for avatars.
 	 *                     Default `[ 24, 48, 96 ]`.
 	 */
 	return apply_filters( 'rest_avatar_sizes', array( 24, 48, 96 ) );
diff --git a/src/wp-includes/rest-api/class-wp-rest-request.php b/src/wp-includes/rest-api/class-wp-rest-request.php
index 1661ce724e..a8932ebb51 100644
--- a/src/wp-includes/rest-api/class-wp-rest-request.php
+++ b/src/wp-includes/rest-api/class-wp-rest-request.php
@@ -330,7 +330,7 @@ class WP_REST_Request implements ArrayAccess {
 	 *
 	 * @since 4.4.0
 	 *
-	 * @return array List of types to check, in order of priority.
+	 * @return string[] Array of types to check, in order of priority.
 	 */
 	protected function get_parameter_order() {
 		$order = array();
@@ -366,12 +366,8 @@ class WP_REST_Request implements ArrayAccess {
 		 *
 		 * @since 4.4.0
 		 *
-		 * @param array           $order {
-		 *    An array of types to check, in order of priority.
-		 *
-		 * @param string $type The type to check.
-		 * }
-		 * @param WP_REST_Request $this The request object.
+		 * @param string[]        $order Array of types to check, in order of priority.
+		 * @param WP_REST_Request $this  The request object.
 		 */
 		return apply_filters( 'rest_request_parameter_order', $order, $this );
 	}
diff --git a/src/wp-includes/rest-api/class-wp-rest-server.php b/src/wp-includes/rest-api/class-wp-rest-server.php
index 8b09076da0..de09c6c52e 100644
--- a/src/wp-includes/rest-api/class-wp-rest-server.php
+++ b/src/wp-includes/rest-api/class-wp-rest-server.php
@@ -780,7 +780,7 @@ class WP_REST_Server {
 	 *
 	 * @since 4.4.0
 	 *
-	 * @return array List of registered namespaces.
+	 * @return string[] List of registered namespaces.
 	 */
 	public function get_namespaces() {
 		return array_keys( $this->namespaces );
@@ -1017,7 +1017,7 @@ class WP_REST_Server {
 	 *
 	 *     @type string $context Context.
 	 * }
-	 * @return array Index entity
+	 * @return WP_REST_Response The API root index data.
 	 */
 	public function get_index( $request ) {
 		// General site data.
@@ -1100,7 +1100,7 @@ class WP_REST_Server {
 	 *
 	 * @param array  $routes  Routes to get data for.
 	 * @param string $context Optional. Context for data. Accepts 'view' or 'help'. Default 'view'.
-	 * @return array Route data to expose in indexes.
+	 * @return array[] Route data to expose in indexes, keyed by route.
 	 */
 	public function get_data_for_routes( $routes, $context = 'view' ) {
 		$available = array();
@@ -1131,8 +1131,8 @@ class WP_REST_Server {
 		 *
 		 * @since 4.4.0
 		 *
-		 * @param array $available Map of route to route data.
-		 * @param array $routes    Internal route data as an associative array.
+		 * @param array[] $available Route data to expose in indexes, keyed by route.
+		 * @param array   $routes    Internal route data as an associative array.
 		 */
 		return apply_filters( 'rest_route_data', $available, $routes );
 	}
diff --git a/src/wp-includes/taxonomy.php b/src/wp-includes/taxonomy.php
index 5120c0f43c..2d35d410f9 100644
--- a/src/wp-includes/taxonomy.php
+++ b/src/wp-includes/taxonomy.php
@@ -4377,12 +4377,12 @@ function get_the_taxonomies( $post = 0, $args = array() ) {
 }
 
 /**
- * Retrieve all taxonomies of a post with just the names.
+ * Retrieve all taxonomy names for the given post.
  *
  * @since 2.5.0
  *
  * @param int|WP_Post $post Optional. Post ID or WP_Post object. Default is global $post.
- * @return array An array of all taxonomy names for the given post.
+ * @return string[] An array of all taxonomy names for the given post.
  */
 function get_post_taxonomies( $post = 0 ) {
 	$post = get_post( $post );
@@ -4492,7 +4492,7 @@ function is_object_in_taxonomy( $object_type, $taxonomy ) {
  *                              ancestors. Accepts a post type or a taxonomy name. Default empty.
  * @param string $resource_type Optional. Type of resource $object_type is. Accepts 'post_type'
  *                              or 'taxonomy'. Default empty.
- * @return array An array of ancestors from lowest to highest in the hierarchy.
+ * @return int[] An array of IDs of ancestors from lowest to highest in the hierarchy.
  */
 function get_ancestors( $object_id = 0, $object_type = '', $resource_type = '' ) {
 	$object_id = (int) $object_id;
@@ -4529,7 +4529,7 @@ function get_ancestors( $object_id = 0, $object_type = '', $resource_type = '' )
 	 * @since 3.1.0
 	 * @since 4.1.1 Introduced the `$resource_type` parameter.
 	 *
-	 * @param array  $ancestors     An array of object ancestors.
+	 * @param int[]  $ancestors     An array of IDs of object ancestors.
 	 * @param int    $object_id     Object ID.
 	 * @param string $object_type   Type of object.
 	 * @param string $resource_type Type of resource $object_type is.
diff --git a/src/wp-includes/theme.php b/src/wp-includes/theme.php
index 23b1c12a41..824422cb91 100644
--- a/src/wp-includes/theme.php
+++ b/src/wp-includes/theme.php
@@ -1973,13 +1973,13 @@ function remove_editor_styles() {
 }
 
 /**
- * Retrieve any registered editor stylesheets
+ * Retrieve any registered editor stylesheet URLs.
  *
  * @since 4.0.0
  *
  * @global array $editor_styles Registered editor stylesheets
  *
- * @return array If registered, a list of editor stylesheet URLs.
+ * @return string[] If registered, a list of editor stylesheet URLs.
  */
 function get_editor_stylesheets() {
 	$stylesheets = array();
@@ -2019,11 +2019,11 @@ function get_editor_stylesheets() {
 	}
 
 	/**
-	 * Filters the array of stylesheets applied to the editor.
+	 * Filters the array of URLs of stylesheets applied to the editor.
 	 *
 	 * @since 4.3.0
 	 *
-	 * @param array $stylesheets Array of stylesheets to be applied to the editor.
+	 * @param string[] $stylesheets Array of URLs of stylesheets to be applied to the editor.
 	 */
 	return apply_filters( 'editor_stylesheets', $stylesheets );
 }
diff --git a/src/wp-includes/user.php b/src/wp-includes/user.php
index 44b802b5fa..f1a2c0a49b 100644
--- a/src/wp-includes/user.php
+++ b/src/wp-includes/user.php
@@ -395,10 +395,10 @@ function count_user_posts( $userid, $post_type = 'post', $public_only = false )
  *
  * @global wpdb $wpdb WordPress database abstraction object.
  *
- * @param array        $users       Array of user IDs.
- * @param string|array $post_type   Optional. Single post type or array of post types to check. Defaults to 'post'.
- * @param bool         $public_only Optional. Only return counts for public posts.  Defaults to false.
- * @return array Amount of posts each user has written.
+ * @param int[]           $users       Array of user IDs.
+ * @param string|string[] $post_type   Optional. Single post type or array of post types to check. Defaults to 'post'.
+ * @param bool            $public_only Optional. Only return counts for public posts.  Defaults to false.
+ * @return string[] Amount of posts each user has written, as strings, keyed by user ID.
  */
 function count_many_users_posts( $users, $post_type = 'post', $public_only = false ) {
 	global $wpdb;
@@ -865,7 +865,12 @@ function update_user_meta( $user_id, $meta_key, $meta_value, $prev_value = '' )
  * @param string   $strategy Optional. The computational strategy to use when counting the users.
  *                           Accepts either 'time' or 'memory'. Default 'time'.
  * @param int|null $site_id  Optional. The site ID to count users for. Defaults to the current site.
- * @return array Includes a grand total and an array of counts indexed by role strings.
+ * @return array {
+ *     User counts.
+ *
+ *     @type int   $total_users Total number of users on the site.
+ *     @type int[] $avail_roles Array of user counts keyed by user role.
+ * }
  */
 function count_users( $strategy = 'time', $site_id = null ) {
 	global $wpdb;
@@ -2171,7 +2176,7 @@ function wp_create_user( $username, $password, $email = '' ) {
  * @access private
  *
  * @param WP_User $user WP_User instance.
- * @return array List of user keys to be populated in wp_update_user().
+ * @return string[] List of user keys to be populated in wp_update_user().
  */
 function _get_additional_user_keys( $user ) {
 	$keys = array( 'first_name', 'last_name', 'nickname', 'description', 'rich_editing', 'syntax_highlighting', 'comment_shortcuts', 'admin_color', 'use_ssl', 'show_admin_bar_front', 'locale' );
@@ -2186,7 +2191,7 @@ function _get_additional_user_keys( $user ) {
  * @since 3.7.0
  *
  * @param WP_User $user Optional. WP_User object.
- * @return array Array of contact methods and their labels.
+ * @return string[] Array of contact method labels keyed by contact method.
  */
 function wp_get_user_contact_methods( $user = null ) {
 	$methods = array();
@@ -2203,8 +2208,8 @@ function wp_get_user_contact_methods( $user = null ) {
 	 *
 	 * @since 2.9.0
 	 *
-	 * @param array   $methods Array of contact methods and their labels.
-	 * @param WP_User $user    WP_User object.
+	 * @param string[] $methods Array of contact method labels keyed by contact method.
+	 * @param WP_User  $user    WP_User object.
 	 */
 	return apply_filters( 'user_contactmethods', $methods, $user );
 }
@@ -2218,7 +2223,7 @@ function wp_get_user_contact_methods( $user = null ) {
  * @access private
  *
  * @param WP_User $user Optional. WP_User object. Default null.
- * @return array Array of contact methods and their labels.
+ * @return string[] Array of contact method labels keyed by contact method.
  */
 function _wp_get_user_contactmethods( $user = null ) {
 	return wp_get_user_contact_methods( $user );
@@ -2660,7 +2665,7 @@ function wp_destroy_all_sessions() {
  * @since 4.9.0 The `$site_id` parameter was added to support multisite.
  *
  * @param int|null $site_id Optional. The site ID to get users with no role for. Defaults to the current site.
- * @return array Array of user IDs.
+ * @return string[] Array of user IDs as strings.
  */
 function wp_get_users_with_no_role( $site_id = null ) {
 	global $wpdb;
diff --git a/src/wp-includes/wp-db.php b/src/wp-includes/wp-db.php
index 1be0412e33..c354df2f6b 100644
--- a/src/wp-includes/wp-db.php
+++ b/src/wp-includes/wp-db.php
@@ -742,7 +742,12 @@ class wpdb {
 	 *
 	 * @param string $charset The character set to check.
 	 * @param string $collate The collation to check.
-	 * @return array The most appropriate character set and collation to use.
+	 * @return array {
+	 *     The most appropriate character set and collation to use.
+	 *
+	 *     @type string $charset Character set.
+	 *     @type string $collate Collation.
+	 * }
 	 */
 	public function determine_charset( $charset, $collate ) {
 		if ( ( $this->use_mysqli && ! ( $this->dbh instanceof mysqli ) ) || empty( $this->dbh ) ) {
diff --git a/src/wp-trackback.php b/src/wp-trackback.php
index 6bc8495a9f..f12b11658e 100644
--- a/src/wp-trackback.php
+++ b/src/wp-trackback.php
@@ -20,9 +20,9 @@ if ( empty( $wp ) ) {
  *
  * @since 0.71
  *
- * @param mixed  $error         Whether there was an error.
- *                              Default '0'. Accepts '0' or '1', true or false.
- * @param string $error_message Error message if an error occurred.
+ * @param int|bool $error         Whether there was an error.
+ *                                Default '0'. Accepts '0' or '1', true or false.
+ * @param string   $error_message Error message if an error occurred.
  */
 function trackback_response( $error = 0, $error_message = '' ) {
 	header( 'Content-Type: text/xml; charset=' . get_option( 'blog_charset' ) );