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

@@ -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
+ * @return array|false {
- *                     there is no current user.
+ *     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 );

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,7 +134,7 @@ 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.
+		 * @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.
 		 */

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

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,7 +145,7 @@ final class WP_Block_Patterns_Registry {
 	 *
 	 * @since 5.5.0
 	 *
-	 * @return array Array of arrays containing the registered block patterns properties,
+	 * @return array[] Array of arrays containing the registered block patterns properties,
 	 *                 and per style.
 	 */
 	public function get_all_registered() {

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;

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

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.

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.
 		 */

wp-includes/comment.php

@@ -156,7 +156,7 @@ 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`
+ * @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() ) {
@@ -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;

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
+ * @param bool   $pretty       Optional. Whether you want a comma separated string instead of
- *                             array returned. Default true.
+ *                             the raw array returned. Default true.
  * @return string|array Either a string containing a reversed comma separated trace or an array
  *                      of individual calls.
  */

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;

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.

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
+	 * @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.
+	 *     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' ).
+	 * @return array|false|WP_Error {
-	 *                              False if the column has no length (for example, numeric column).
+	 *     Array of column length information, false if the column has no length (for
-	 *                              WP_Error object if there was an error.
+	 *     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 );