From 6aa053dc01aeab4ca197091d0c9a4c3437591640 Mon Sep 17 00:00:00 2001
From: John Blackbourn <johnbillion@git.wordpress.org>
Date: Thu, 28 Apr 2022 09:46:21 +0000
Subject: [PATCH] Docs: Various docblock improvements.

See #54729

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


git-svn-id: http://core.svn.wordpress.org/trunk@52888 1a063a9b-81f0-0310-95a4-ce76da25c4cd
---
 wp-admin/includes/post.php                    |  9 ++++++--
 wp-includes/block-editor.php                  | 10 ++++-----
 ...s-wp-block-pattern-categories-registry.php |  4 ++--
 .../class-wp-block-patterns-registry.php      |  6 ++---
 wp-includes/class-wp-comment-query.php        |  4 ++--
 wp-includes/class-wp-editor.php               | 12 +++++++++-
 wp-includes/class-wp-error.php                |  2 +-
 wp-includes/class-wp-term-query.php           | 12 +++++++++-
 wp-includes/comment.php                       |  6 ++---
 wp-includes/functions.php                     |  6 ++---
 wp-includes/pluggable.php                     |  2 +-
 wp-includes/version.php                       |  2 +-
 wp-includes/wp-db.php                         | 22 ++++++++++++++-----
 13 files changed, 66 insertions(+), 31 deletions(-)

diff --git a/wp-admin/includes/post.php b/wp-admin/includes/post.php
index c13f2f7592..f3300fcf1e 100644
--- a/wp-admin/includes/post.php
+++ b/wp-admin/includes/post.php
@@ -1661,8 +1661,13 @@ function wp_check_post_lock( $post_id ) {
  * @since 2.5.0
  *
  * @param int|WP_Post $post_id ID or object of the post being edited.
- * @return array|false Array of the lock time and user ID. False if the post does not exist, or
- *                     there is no current user.
+ * @return array|false {
+ *     Array of the lock time and user ID. False if the post does not exist, or there
+ *     is no current user.
+ *
+ *     @type int $0 The current time as a Unix timestamp.
+ *     @type int $1 The ID of the current user.
+ * }
  */
 function wp_set_post_lock( $post_id ) {
 	$post = get_post( $post_id );
diff --git a/wp-includes/block-editor.php b/wp-includes/block-editor.php
index f7aa838b9b..8ad8b4a573 100644
--- a/wp-includes/block-editor.php
+++ b/wp-includes/block-editor.php
@@ -109,7 +109,7 @@ function get_block_categories( $post_or_block_editor_context ) {
  *
  * @param WP_Block_Editor_Context $block_editor_context The current block editor context.
  *
- * @return bool|array Array of block type slugs, or boolean to enable/disable all.
+ * @return bool|string[] Array of block type slugs, or boolean to enable/disable all.
  */
 function get_allowed_block_types( $block_editor_context ) {
 	$allowed_block_types = true;
@@ -119,7 +119,7 @@ function get_allowed_block_types( $block_editor_context ) {
 	 *
 	 * @since 5.8.0
 	 *
-	 * @param bool|array              $allowed_block_types  Array of block type slugs, or boolean to enable/disable all.
+	 * @param bool|string[]           $allowed_block_types  Array of block type slugs, or boolean to enable/disable all.
 	 *                                                      Default true (all registered block types supported).
 	 * @param WP_Block_Editor_Context $block_editor_context The current block editor context.
 	 */
@@ -134,9 +134,9 @@ function get_allowed_block_types( $block_editor_context ) {
 		 * @since 5.0.0
 		 * @deprecated 5.8.0 Use the {@see 'allowed_block_types_all'} filter instead.
 		 *
-		 * @param bool|array $allowed_block_types Array of block type slugs, or boolean to enable/disable all.
-		 *                                        Default true (all registered block types supported)
-		 * @param WP_Post    $post                The post resource data.
+		 * @param bool|string[] $allowed_block_types Array of block type slugs, or boolean to enable/disable all.
+		 *                                           Default true (all registered block types supported)
+		 * @param WP_Post       $post                The post resource data.
 		 */
 		$allowed_block_types = apply_filters_deprecated( 'allowed_block_types', array( $allowed_block_types, $post ), '5.8.0', 'allowed_block_types_all' );
 	}
diff --git a/wp-includes/class-wp-block-pattern-categories-registry.php b/wp-includes/class-wp-block-pattern-categories-registry.php
index 9891214d3d..b223dbf4a2 100644
--- a/wp-includes/class-wp-block-pattern-categories-registry.php
+++ b/wp-includes/class-wp-block-pattern-categories-registry.php
@@ -15,7 +15,7 @@ final class WP_Block_Pattern_Categories_Registry {
 	 * Registered block pattern categories array.
 	 *
 	 * @since 5.5.0
-	 * @var array
+	 * @var array[]
 	 */
 	private $registered_categories = array();
 
@@ -103,7 +103,7 @@ final class WP_Block_Pattern_Categories_Registry {
 	 *
 	 * @since 5.5.0
 	 *
-	 * @return array Array of arrays containing the registered pattern categories properties.
+	 * @return array[] Array of arrays containing the registered pattern categories properties.
 	 */
 	public function get_all_registered() {
 		return array_values( $this->registered_categories );
diff --git a/wp-includes/class-wp-block-patterns-registry.php b/wp-includes/class-wp-block-patterns-registry.php
index d84f7c775a..e08d10bc28 100644
--- a/wp-includes/class-wp-block-patterns-registry.php
+++ b/wp-includes/class-wp-block-patterns-registry.php
@@ -17,7 +17,7 @@ final class WP_Block_Patterns_Registry {
 	 * Registered block patterns array.
 	 *
 	 * @since 5.5.0
-	 * @var array
+	 * @var array[]
 	 */
 	private $registered_patterns = array();
 
@@ -145,8 +145,8 @@ final class WP_Block_Patterns_Registry {
 	 *
 	 * @since 5.5.0
 	 *
-	 * @return array Array of arrays containing the registered block patterns properties,
-	 *               and per style.
+	 * @return array[] Array of arrays containing the registered block patterns properties,
+	 *                 and per style.
 	 */
 	public function get_all_registered() {
 		return array_values( $this->registered_patterns );
diff --git a/wp-includes/class-wp-comment-query.php b/wp-includes/class-wp-comment-query.php
index 09e8b9e72b..f9f1c1ca1e 100644
--- a/wp-includes/class-wp-comment-query.php
+++ b/wp-includes/class-wp-comment-query.php
@@ -93,7 +93,7 @@ class WP_Comment_Query {
 	 * List of comments located by the query.
 	 *
 	 * @since 4.0.0
-	 * @var array
+	 * @var int[]|WP_Comment[]
 	 */
 	public $comments;
 
@@ -374,7 +374,7 @@ class WP_Comment_Query {
 	 *
 	 * @global wpdb $wpdb WordPress database abstraction object.
 	 *
-	 * @return int|array List of comments or number of found comments if `$count` argument is true.
+	 * @return int|int[]|WP_Comment[] List of comments or number of found comments if `$count` argument is true.
 	 */
 	public function get_comments() {
 		global $wpdb;
diff --git a/wp-includes/class-wp-editor.php b/wp-includes/class-wp-editor.php
index f12004b3e9..9a772d909c 100644
--- a/wp-includes/class-wp-editor.php
+++ b/wp-includes/class-wp-editor.php
@@ -1751,7 +1751,17 @@ final class _WP_Editors {
 	 * @since 3.1.0
 	 *
 	 * @param array $args Optional. Accepts 'pagenum' and 's' (search) arguments.
-	 * @return array|false Results.
+	 * @return array|false $results {
+	 *     An array of associative arrays of query results, false if there are none.
+	 *
+	 *     @type array ...$0 {
+	 *         @type int    $ID        Post ID.
+	 *         @type string $title     The trimmed, escaped post title.
+	 *         @type string $permalink Post permalink.
+	 *         @type string $info      A 'Y/m/d'-formatted date for 'post' post type,
+	 *                                 the 'singular_name' post type label otherwise.
+	 *     }
+	 * }
 	 */
 	public static function wp_link_query( $args = array() ) {
 		$pts      = get_post_types( array( 'public' => true ), 'objects' );
diff --git a/wp-includes/class-wp-error.php b/wp-includes/class-wp-error.php
index 8cb2c3c58e..d34c70a2e9 100644
--- a/wp-includes/class-wp-error.php
+++ b/wp-includes/class-wp-error.php
@@ -103,7 +103,7 @@ class WP_Error {
 	 * @since 2.1.0
 	 *
 	 * @param string|int $code Optional. Retrieve messages matching code, if exists.
-	 * @return array Error strings on success, or empty array if there are none.
+	 * @return string[] Error strings on success, or empty array if there are none.
 	 */
 	public function get_error_messages( $code = '' ) {
 		// Return all messages if no code specified.
diff --git a/wp-includes/class-wp-term-query.php b/wp-includes/class-wp-term-query.php
index 7e4c06c0df..8adacd8324 100644
--- a/wp-includes/class-wp-term-query.php
+++ b/wp-includes/class-wp-term-query.php
@@ -699,7 +699,17 @@ class WP_Term_Query {
 		 *
 		 * @since 3.1.0
 		 *
-		 * @param string[] $clauses    Array of query SQL clauses.
+		 * @param string[] $clauses {
+		 *     Associative array of the clauses for the query.
+		 *
+		 *     @type string $fields   The SELECT clause of the query.
+		 *     @type string $join     The JOIN clause of the query.
+		 *     @type string $where    The WHERE clause of the query.
+		 *     @type string $distinct The DISTINCT clause of the query.
+		 *     @type string $orderby  The ORDER BY clause of the query.
+		 *     @type string $order    The ORDER clause of the query.
+		 *     @type string $limits   The LIMIT clause of the query.
+		 * }
 		 * @param string[] $taxonomies An array of taxonomy names.
 		 * @param array    $args       An array of term query arguments.
 		 */
diff --git a/wp-includes/comment.php b/wp-includes/comment.php
index a6ca1b7470..0d5de2681d 100644
--- a/wp-includes/comment.php
+++ b/wp-includes/comment.php
@@ -156,8 +156,8 @@ function check_comment( $author, $email, $url, $comment, $user_ip, $user_agent,
  *
  * @param int   $post_id The ID of the post.
  * @param array $args    Optional. See WP_Comment_Query::__construct() for information on accepted arguments.
- * @return int|array The approved comments, or number of comments if `$count`
- *                   argument is true.
+ * @return WP_Comment[]|int[]|int The approved comments, or number of comments if `$count`
+ *                                argument is true.
  */
 function get_approved_comments( $post_id, $args = array() ) {
 	if ( ! $post_id ) {
@@ -237,7 +237,7 @@ function get_comment( $comment = null, $output = OBJECT ) {
  *
  * @param string|array $args Optional. Array or string of arguments. See WP_Comment_Query::__construct()
  *                           for information on accepted arguments. Default empty.
- * @return int|array List of comments or number of found comments if `$count` argument is true.
+ * @return WP_Comment[]|int[]|int List of comments or number of found comments if `$count` argument is true.
  */
 function get_comments( $args = '' ) {
 	$query = new WP_Comment_Query;
diff --git a/wp-includes/functions.php b/wp-includes/functions.php
index 7fb2fcabe2..579c2f0851 100644
--- a/wp-includes/functions.php
+++ b/wp-includes/functions.php
@@ -6918,7 +6918,7 @@ function wp_allowed_protocols() {
 }
 
 /**
- * Return a comma-separated string of functions that have been called to get
+ * Returns a comma-separated string or array of functions that have been called to get
  * to the current point in code.
  *
  * @since 3.4.0
@@ -6929,8 +6929,8 @@ function wp_allowed_protocols() {
  *                             when you want to just give info about the callee. Default null.
  * @param int    $skip_frames  Optional. A number of stack frames to skip - useful for unwinding
  *                             back to the source of the issue. Default 0.
- * @param bool   $pretty       Optional. Whether or not you want a comma separated string or raw
- *                             array returned. Default true.
+ * @param bool   $pretty       Optional. Whether you want a comma separated string instead of
+ *                             the raw array returned. Default true.
  * @return string|array Either a string containing a reversed comma separated trace or an array
  *                      of individual calls.
  */
diff --git a/wp-includes/pluggable.php b/wp-includes/pluggable.php
index fdbfdea250..51532b734e 100644
--- a/wp-includes/pluggable.php
+++ b/wp-includes/pluggable.php
@@ -127,7 +127,7 @@ if ( ! function_exists( 'cache_users' ) ) :
 	 *
 	 * @global wpdb $wpdb WordPress database abstraction object.
 	 *
-	 * @param array $user_ids User ID numbers list
+	 * @param int[] $user_ids User ID numbers list
 	 */
 	function cache_users( $user_ids ) {
 		global $wpdb;
diff --git a/wp-includes/version.php b/wp-includes/version.php
index 0b6f5f57cd..dd6524c2fe 100644
--- a/wp-includes/version.php
+++ b/wp-includes/version.php
@@ -16,7 +16,7 @@
  *
  * @global string $wp_version
  */
-$wp_version = '6.0-beta3-53298';
+$wp_version = '6.0-beta3-53299';
 
 /**
  * Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.
diff --git a/wp-includes/wp-db.php b/wp-includes/wp-db.php
index 28575f2872..b514599097 100644
--- a/wp-includes/wp-db.php
+++ b/wp-includes/wp-db.php
@@ -1851,9 +1851,16 @@ class wpdb {
 	 * @since 4.9.0
 	 *
 	 * @param string $host The DB_HOST setting to parse.
-	 * @return array|false Array containing the host, the port, the socket and
-	 *                     whether it is an IPv6 address, in that order.
-	 *                     False if $host couldn't be parsed.
+	 * @return array|false {
+	 *     Array containing the host, the port, the socket and
+	 *     whether it is an IPv6 address, in that order.
+	 *     False if the host couldn't be parsed.
+	 *
+	 *     @type string      $0 Host name.
+	 *     @type string|null $1 Port.
+	 *     @type string|null $2 Socket.
+	 *     @type bool        $3 Whether it is an IPv6 address.
+	 * }
 	 */
 	public function parse_db_host( $host ) {
 		$port    = null;
@@ -3043,9 +3050,12 @@ class wpdb {
 	 *
 	 * @param string $table  Table name.
 	 * @param string $column Column name.
-	 * @return array|false|WP_Error array( 'length' => (int), 'type' => 'byte' | 'char' ).
-	 *                              False if the column has no length (for example, numeric column).
-	 *                              WP_Error object if there was an error.
+	 * @return array|false|WP_Error {
+	 *     Array of column length information, false if the column has no length (for
+	 *     example, numeric column), WP_Error object if there was an error.
+	 *
+	 *     @type int    $length The column length.
+	 *     @type string $type   One of 'byte' or 'char'.
 	 */
 	public function get_col_length( $table, $column ) {
 		$tablekey  = strtolower( $table );