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

See #48303

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


git-svn-id: http://core.svn.wordpress.org/trunk@46461 1a063a9b-81f0-0310-95a4-ce76da25c4cd
---
 wp-includes/bookmark.php                      |  2 +-
 wp-includes/capabilities.php                  |  4 +--
 wp-includes/class-requests.php                |  4 +--
 wp-includes/class-wp-comment.php              |  2 +-
 wp-includes/class-wp-customize-manager.php    |  4 +--
 wp-includes/class-wp-embed.php                | 16 +++++-----
 wp-includes/class-wp-image-editor.php         |  7 ++++-
 wp-includes/class-wp-query.php                |  6 ++--
 .../class-wp-recovery-mode-email-service.php  |  2 +-
 wp-includes/class-wp-rewrite.php              |  6 ++--
 wp-includes/class-wp-theme.php                | 18 +++++------
 wp-includes/class-wp-user.php                 |  3 +-
 wp-includes/class.wp-dependencies.php         | 30 +++++++++----------
 wp-includes/class.wp-scripts.php              | 14 ++++-----
 wp-includes/class.wp-styles.php               |  8 ++---
 wp-includes/version.php                       |  2 +-
 16 files changed, 66 insertions(+), 62 deletions(-)

diff --git a/wp-includes/bookmark.php b/wp-includes/bookmark.php
index 595768f6cd..f14d80a738 100644
--- a/wp-includes/bookmark.php
+++ b/wp-includes/bookmark.php
@@ -129,7 +129,7 @@ function get_bookmark_field( $field, $bookmark, $context = 'display' ) {
  *                                    and searched in 'link_url', 'link_name' and 'link_description'.
  *                                    Default empty.
  * }
- * @return array List of bookmark row objects.
+ * @return object[] List of bookmark row objects.
  */
 function get_bookmarks( $args = '' ) {
 	global $wpdb;
diff --git a/wp-includes/capabilities.php b/wp-includes/capabilities.php
index 2ca595d357..3903ea8f24 100644
--- a/wp-includes/capabilities.php
+++ b/wp-includes/capabilities.php
@@ -33,7 +33,7 @@
  * @param string $cap     Capability name.
  * @param int    $user_id User ID.
  * @param mixed  ...$args Optional further parameters, typically starting with an object ID.
- * @return array Actual capabilities for meta capability.
+ * @return string[] Actual capabilities for meta capability.
  */
 function map_meta_cap( $cap, $user_id, ...$args ) {
 	$caps = array();
@@ -838,7 +838,7 @@ function remove_role( $role ) {
  *
  * @global array $super_admins
  *
- * @return array List of super admin logins
+ * @return string[] List of super admin logins.
  */
 function get_super_admins() {
 	global $super_admins;
diff --git a/wp-includes/class-requests.php b/wp-includes/class-requests.php
index ea1b868f53..e9773800cb 100644
--- a/wp-includes/class-requests.php
+++ b/wp-includes/class-requests.php
@@ -789,7 +789,7 @@ class Requests {
 	 * Convert a key => value array to a 'key: value' array for headers
 	 *
 	 * @param array $array Dictionary of header values
-	 * @return array List of headers
+	 * @return string[] List of headers
 	 */
 	public static function flatten($array) {
 		$return = array();
@@ -805,7 +805,7 @@ class Requests {
 	 * @codeCoverageIgnore
 	 * @deprecated Misspelling of {@see Requests::flatten}
 	 * @param array $array Dictionary of header values
-	 * @return array List of headers
+	 * @return string[] List of headers
 	 */
 	public static function flattern($array) {
 		return self::flatten($array);
diff --git a/wp-includes/class-wp-comment.php b/wp-includes/class-wp-comment.php
index f631444f8f..70d7db2bd8 100644
--- a/wp-includes/class-wp-comment.php
+++ b/wp-includes/class-wp-comment.php
@@ -251,7 +251,7 @@ final class WP_Comment {
 	 *                                 `$meta_query`. Also accepts false, an empty array, or
 	 *                                 'none' to disable `ORDER BY` clause.
 	 * }
-	 * @return array Array of `WP_Comment` objects.
+	 * @return WP_Comment[] Array of `WP_Comment` objects.
 	 */
 	public function get_children( $args = array() ) {
 		$defaults = array(
diff --git a/wp-includes/class-wp-customize-manager.php b/wp-includes/class-wp-customize-manager.php
index 1dd4ff8aaf..d7d0835271 100644
--- a/wp-includes/class-wp-customize-manager.php
+++ b/wp-includes/class-wp-customize-manager.php
@@ -436,8 +436,8 @@ final class WP_Customize_Manager {
 	 *
 	 * @since 3.4.0
 	 *
-	 * @param mixed $ajax_message Ajax return
-	 * @param mixed $message UI message
+	 * @param string|WP_Error $ajax_message Ajax return.
+	 * @param string          $message      Optional. UI message.
 	 */
 	protected function wp_die( $ajax_message, $message = null ) {
 		if ( $this->doing_ajax() ) {
diff --git a/wp-includes/class-wp-embed.php b/wp-includes/class-wp-embed.php
index c8aec5a006..317a29841c 100644
--- a/wp-includes/class-wp-embed.php
+++ b/wp-includes/class-wp-embed.php
@@ -173,15 +173,15 @@ class WP_Embed {
 					$return = call_user_func( $handler['callback'], $matches, $attr, $url, $rawattr );
 					if ( false !== $return ) {
 						/**
-						 * Filters the returned embed handler.
+						 * Filters the returned embed HTML.
 						 *
 						 * @since 2.9.0
 						 *
 						 * @see WP_Embed::shortcode()
 						 *
-						 * @param mixed  $return The shortcode callback function to call.
-						 * @param string $url    The attempted embed URL.
-						 * @param array  $attr   An array of shortcode attributes.
+						 * @param string|false $return The HTML result of the shortcode, or false on failure.
+						 * @param string       $url    The embed URL.
+						 * @param array        $attr   An array of shortcode attributes.
 						 */
 						return apply_filters( 'embed_handler_html', $return, $url, $attr );
 					}
@@ -248,10 +248,10 @@ class WP_Embed {
 				 *
 				 * @see WP_Embed::shortcode()
 				 *
-				 * @param mixed  $cache   The cached HTML result, stored in post meta.
-				 * @param string $url     The attempted embed URL.
-				 * @param array  $attr    An array of shortcode attributes.
-				 * @param int    $post_ID Post ID.
+				 * @param string|false $cache   The cached HTML result, stored in post meta.
+				 * @param string       $url     The attempted embed URL.
+				 * @param array        $attr    An array of shortcode attributes.
+				 * @param int          $post_ID Post ID.
 				 */
 				return apply_filters( 'embed_oembed_html', $cache, $url, $attr, $post_ID );
 			}
diff --git a/wp-includes/class-wp-image-editor.php b/wp-includes/class-wp-image-editor.php
index 6b3a6d544c..7ee4440138 100644
--- a/wp-includes/class-wp-image-editor.php
+++ b/wp-includes/class-wp-image-editor.php
@@ -172,7 +172,12 @@ abstract class WP_Image_Editor {
 	 *
 	 * @since 3.5.0
 	 *
-	 * @return array {'width'=>int, 'height'=>int}
+	 * @return array {
+	 *     Dimensions of the image.
+	 *
+	 *     @type int $width  The image width.
+	 *     @type int $height The image height.
+	 * }
 	 */
 	public function get_size() {
 		return $this->size;
diff --git a/wp-includes/class-wp-query.php b/wp-includes/class-wp-query.php
index 43317ab838..9d7d1a5be7 100644
--- a/wp-includes/class-wp-query.php
+++ b/wp-includes/class-wp-query.php
@@ -1402,7 +1402,7 @@ class WP_Query {
 	 * @since 3.7.0
 	 *
 	 * @param string[] $terms Array of terms to check.
-	 * @return array Terms that are not stopwords.
+	 * @return string[] Terms that are not stopwords.
 	 */
 	protected function parse_search_terms( $terms ) {
 		$strtolower = function_exists( 'mb_strtolower' ) ? 'mb_strtolower' : 'strtolower';
@@ -1438,7 +1438,7 @@ class WP_Query {
 	 *
 	 * @since 3.7.0
 	 *
-	 * @return array Stopwords.
+	 * @return string[] Stopwords.
 	 */
 	protected function get_search_stopwords() {
 		if ( isset( $this->stopwords ) ) {
@@ -3585,7 +3585,7 @@ class WP_Query {
 	 *
 	 * @since 3.1.0
 	 *
-	 * @param mixed $post_types Optional. Post type or array of posts types to check against.
+	 * @param string|string[] $post_types Optional. Post type or array of posts types to check against.
 	 * @return bool
 	 */
 	public function is_post_type_archive( $post_types = '' ) {
diff --git a/wp-includes/class-wp-recovery-mode-email-service.php b/wp-includes/class-wp-recovery-mode-email-service.php
index 11399d24a2..5b0dd2e4db 100644
--- a/wp-includes/class-wp-recovery-mode-email-service.php
+++ b/wp-includes/class-wp-recovery-mode-email-service.php
@@ -306,7 +306,7 @@ When seeking help with this issue, you may be asked for some of the following in
 	 * @since 5.3.0
 	 *
 	 * @param array $extension The extension that caused the error.
-	 * @return array An associated array of debug information.
+	 * @return array An associative array of debug information.
 	 */
 	private function get_debug( $extension ) {
 		$theme      = wp_get_theme();
diff --git a/wp-includes/class-wp-rewrite.php b/wp-includes/class-wp-rewrite.php
index 3168322cc2..88df9d3633 100644
--- a/wp-includes/class-wp-rewrite.php
+++ b/wp-includes/class-wp-rewrite.php
@@ -463,7 +463,7 @@ class WP_Rewrite {
 	 *
 	 * @since 1.5.0
 	 *
-	 * @return array Page rewrite rules.
+	 * @return string[] Page rewrite rules.
 	 */
 	public function page_rewrite_rules() {
 		// The extra .? at the beginning prevents clashes with other regular expressions in the rules array.
@@ -1250,7 +1250,7 @@ class WP_Rewrite {
 	 *
 	 * @since 1.5.0
 	 *
-	 * @return array An associate array of matches and queries.
+	 * @return string[] An associative array of matches and queries.
 	 */
 	public function rewrite_rules() {
 		$rewrite = array();
@@ -1455,7 +1455,7 @@ class WP_Rewrite {
 	 *
 	 * @since 1.5.0
 	 *
-	 * @return array Rewrite rules.
+	 * @return string[] Array of rewrite rules keyed by their regex pattern.
 	 */
 	public function wp_rewrite_rules() {
 		$this->rules = get_option( 'rewrite_rules' );
diff --git a/wp-includes/class-wp-theme.php b/wp-includes/class-wp-theme.php
index fe8dbb142b..2697aaf521 100644
--- a/wp-includes/class-wp-theme.php
+++ b/wp-includes/class-wp-theme.php
@@ -1156,8 +1156,8 @@ final class WP_Theme implements ArrayAccess {
 	 * @param mixed $type Optional. Array of extensions to return. Defaults to all files (null).
 	 * @param int $depth Optional. How deep to search for files. Defaults to a flat scan (0 depth). -1 depth is infinite.
 	 * @param bool $search_parent Optional. Whether to return parent files. Defaults to false.
-	 * @return array Array of files, keyed by the path to the file relative to the theme's directory, with the values
-	 *               being absolute paths.
+	 * @return string[] Array of files, keyed by the path to the file relative to the theme's directory, with the values
+	 *                  being absolute paths.
 	 */
 	public function get_files( $type = null, $depth = 0, $search_parent = false ) {
 		$files = (array) self::scandir( $this->get_stylesheet_directory(), $type, $depth );
@@ -1174,7 +1174,7 @@ final class WP_Theme implements ArrayAccess {
 	 *
 	 * @since 4.7.0
 	 *
-	 * @return array Array of page templates, keyed by filename and post type,
+	 * @return string Array of page templates, keyed by filename and post type,
 	 *               with the value of the translated header name.
 	 */
 	public function get_post_templates() {
@@ -1233,7 +1233,7 @@ final class WP_Theme implements ArrayAccess {
 	 * @param WP_Post|null $post      Optional. The post being edited, provided for context.
 	 * @param string       $post_type Optional. Post type to get the templates for. Default 'page'.
 	 *                                If a post is provided, its post type is used.
-	 * @return array Array of page templates, keyed by filename, with the value of the translated header name.
+	 * @return string[] Array of template header names keyed by the template file name.
 	 */
 	public function get_page_templates( $post = null, $post_type = 'page' ) {
 		if ( $post ) {
@@ -1248,8 +1248,7 @@ final class WP_Theme implements ArrayAccess {
 		 *
 		 * @since 4.9.6
 		 *
-		 * @param string[]     $post_templates Array of page templates. Keys are filenames,
-		 *                                     values are translated names.
+		 * @param string[]     $post_templates Array of template header names keyed by the template file name.
 		 * @param WP_Theme     $this           The theme object.
 		 * @param WP_Post|null $post           The post being edited, provided for context, or null.
 		 * @param string       $post_type      Post type to get the templates for.
@@ -1265,8 +1264,7 @@ final class WP_Theme implements ArrayAccess {
 		 * @since 4.4.0 Converted to allow complete control over the `$page_templates` array.
 		 * @since 4.7.0 Added the `$post_type` parameter.
 		 *
-		 * @param string[]     $post_templates Array of page templates. Keys are filenames,
-		 *                                     values are translated names.
+		 * @param string[]     $post_templates Array of template header names keyed by the template file name.
 		 * @param WP_Theme     $this           The theme object.
 		 * @param WP_Post|null $post           The post being edited, provided for context, or null.
 		 * @param string       $post_type      Post type to get the templates for.
@@ -1289,8 +1287,8 @@ final class WP_Theme implements ArrayAccess {
 	 * @param string            $relative_path Optional. The basename of the absolute path. Used to control the
 	 *                                         returned path for the found files, particularly when this function
 	 *                                         recurses to lower depths. Default empty.
-	 * @return array|false Array of files, keyed by the path to the file relative to the `$path` directory prepended
-	 *                     with `$relative_path`, with the values being absolute paths. False otherwise.
+	 * @return string[]|false Array of files, keyed by the path to the file relative to the `$path` directory prepended
+	 *                        with `$relative_path`, with the values being absolute paths. False otherwise.
 	 */
 	private static function scandir( $path, $extensions = null, $depth = 0, $relative_path = '' ) {
 		if ( ! is_dir( $path ) ) {
diff --git a/wp-includes/class-wp-user.php b/wp-includes/class-wp-user.php
index 41dec30cbf..0042a7f489 100644
--- a/wp-includes/class-wp-user.php
+++ b/wp-includes/class-wp-user.php
@@ -864,7 +864,8 @@ class WP_User {
 	 *
 	 * @since 4.9.0
 	 *
-	 * @return array User capabilities array.
+	 * @return bool[] List of capabilities keyed by the capability name,
+	 *                e.g. array( 'edit_posts' => true, 'delete_posts' => false ).
 	 */
 	private function get_caps_data() {
 		$caps = get_user_meta( $this->ID, $this->cap_key, true );
diff --git a/wp-includes/class.wp-dependencies.php b/wp-includes/class.wp-dependencies.php
index b03f96fec7..eb14bd04f0 100644
--- a/wp-includes/class.wp-dependencies.php
+++ b/wp-includes/class.wp-dependencies.php
@@ -25,26 +25,26 @@ class WP_Dependencies {
 	public $registered = array();
 
 	/**
-	 * An array of queued _WP_Dependency handle objects.
+	 * An array of handles of queued objects.
 	 *
 	 * @since 2.6.8
-	 * @var array
+	 * @var string[]
 	 */
 	public $queue = array();
 
 	/**
-	 * An array of _WP_Dependency handle objects to queue.
+	 * An array of handles of objects to queue.
 	 *
 	 * @since 2.6.0
-	 * @var array
+	 * @var string[]
 	 */
 	public $to_do = array();
 
 	/**
-	 * An array of _WP_Dependency handle objects already queued.
+	 * An array of handles of objects already queued.
 	 *
 	 * @since 2.6.0
-	 * @var array
+	 * @var string[]
 	 */
 	public $done = array();
 
@@ -83,9 +83,9 @@ class WP_Dependencies {
 	 * @since 2.6.0
 	 * @since 2.8.0 Added the `$group` parameter.
 	 *
-	 * @param mixed $handles Optional. Items to be processed: Process queue (false), process item (string), process items (array of strings).
-	 * @param mixed $group   Group level: level (int), no groups (false).
-	 * @return array Handles of items that have been processed.
+	 * @param mixed     $handles Optional. Items to be processed: Process queue (false), process item (string), process items (array of strings).
+	 * @param int|false $group   Optional. Group level: level (int), no groups (false).
+	 * @return string[] Array of handles of items that have been processed.
 	 */
 	public function do_items( $handles = false, $group = false ) {
 		/*
@@ -136,9 +136,9 @@ class WP_Dependencies {
 	 * @since 2.6.0 Moved from `WP_Scripts`.
 	 * @since 2.8.0 Added the `$group` parameter.
 	 *
-	 * @param mixed     $handles   Item handle and argument (string) or item handles and arguments (array of strings).
-	 * @param bool      $recursion Internal flag that function is calling itself.
-	 * @param int|false $group     Group level: (int) level, (false) no groups.
+	 * @param string|string[] $handles   Item handle and argument (string) or item handles and arguments (array of strings).
+	 * @param bool            $recursion Internal flag that function is calling itself.
+	 * @param int|false       $group     Group level: (int) level, (false) no groups.
 	 * @return bool True on success, false on failure.
 	 */
 	public function all_deps( $handles, $recursion = false, $group = false ) {
@@ -270,7 +270,7 @@ class WP_Dependencies {
 	 * @since 2.1.0
 	 * @since 2.6.0 Moved from `WP_Scripts`.
 	 *
-	 * @param mixed $handles Item handle and argument (string) or item handles and arguments (array of strings).
+	 * @param string|string[] $handles Item handle and argument (string) or item handles and arguments (array of strings).
 	 * @return void
 	 */
 	public function remove( $handles ) {
@@ -290,7 +290,7 @@ class WP_Dependencies {
 	 * @since 2.1.0
 	 * @since 2.6.0 Moved from `WP_Scripts`.
 	 *
-	 * @param mixed $handles Item handle and argument (string) or item handles and arguments (array of strings).
+	 * @param string|string[] $handles Item handle and argument (string) or item handles and arguments (array of strings).
 	 */
 	public function enqueue( $handles ) {
 		foreach ( (array) $handles as $handle ) {
@@ -313,7 +313,7 @@ class WP_Dependencies {
 	 * @since 2.1.0
 	 * @since 2.6.0 Moved from `WP_Scripts`.
 	 *
-	 * @param mixed $handles Item handle and argument (string) or item handles and arguments (array of strings).
+	 * @param string|string[] $handles Item handle and argument (string) or item handles and arguments (array of strings).
 	 */
 	public function dequeue( $handles ) {
 		foreach ( (array) $handles as $handle ) {
diff --git a/wp-includes/class.wp-scripts.php b/wp-includes/class.wp-scripts.php
index 1b4abd8166..37ad372db9 100644
--- a/wp-includes/class.wp-scripts.php
+++ b/wp-includes/class.wp-scripts.php
@@ -175,11 +175,11 @@ class WP_Scripts extends WP_Dependencies {
 	 * @since 2.1.0
 	 * @since 2.8.0 Added the `$group` parameter.
 	 *
-	 * @param mixed $handles Optional. Scripts to be printed. (void) prints queue, (string) prints
-	 *                       that script, (array of strings) prints those scripts. Default false.
-	 * @param int   $group   Optional. If scripts were queued in groups prints this group number.
-	 *                       Default false.
-	 * @return array Scripts that have been printed.
+	 * @param mixed     $handles Optional. Scripts to be printed. (void) prints queue, (string) prints
+	 *                           that script, (array of strings) prints those scripts. Default false.
+	 * @param int|false $group   Optional. If scripts were queued in groups prints this group number.
+	 *                           Default false.
+	 * @return string[] Handles of scripts that have been printed.
 	 */
 	public function print_scripts( $handles = false, $group = false ) {
 		return $this->do_items( $handles, $group );
@@ -627,7 +627,7 @@ JS;
 	 *
 	 * @see WP_Dependencies::do_items()
 	 *
-	 * @return array Handles of items that have been processed.
+	 * @return string[] Handles of items that have been processed.
 	 */
 	public function do_head_items() {
 		$this->do_items( false, 0 );
@@ -641,7 +641,7 @@ JS;
 	 *
 	 * @see WP_Dependencies::do_items()
 	 *
-	 * @return array Handles of items that have been processed.
+	 * @return string[] Handles of items that have been processed.
 	 */
 	public function do_footer_items() {
 		$this->do_items( false, 1 );
diff --git a/wp-includes/class.wp-styles.php b/wp-includes/class.wp-styles.php
index 17bfef8b2e..5d89154f89 100644
--- a/wp-includes/class.wp-styles.php
+++ b/wp-includes/class.wp-styles.php
@@ -356,9 +356,9 @@ class WP_Styles extends WP_Dependencies {
 	 *
 	 * @see WP_Dependencies::all_deps()
 	 *
-	 * @param mixed     $handles   Item handle and argument (string) or item handles and arguments (array of strings).
-	 * @param bool      $recursion Internal flag that function is calling itself.
-	 * @param int|false $group     Group level: (int) level, (false) no groups.
+	 * @param string|string[] $handles   Item handle and argument (string) or item handles and arguments (array of strings).
+	 * @param bool            $recursion Internal flag that function is calling itself.
+	 * @param int|false       $group     Group level: (int) level, (false) no groups.
 	 * @return bool True on success, false on failure.
 	 */
 	public function all_deps( $handles, $recursion = false, $group = false ) {
@@ -437,7 +437,7 @@ class WP_Styles extends WP_Dependencies {
 	 *
 	 * @see WP_Dependencies::do_items()
 	 *
-	 * @return array Handles of items that have been processed.
+	 * @return string[] Handles of items that have been processed.
 	 */
 	public function do_footer_items() {
 		$this->do_items( false, 1 );
diff --git a/wp-includes/version.php b/wp-includes/version.php
index 2950336a88..2432304967 100644
--- a/wp-includes/version.php
+++ b/wp-includes/version.php
@@ -13,7 +13,7 @@
  *
  * @global string $wp_version
  */
-$wp_version = '5.4-alpha-46660';
+$wp_version = '5.4-alpha-46661';
 
 /**
  * Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.