From 5ef972680a95b8169e94372b8ebffbc3d51d03e2 Mon Sep 17 00:00:00 2001
From: John Blackbourn <johnbillion@git.wordpress.org>
Date: Mon, 8 May 2023 22:37:24 +0000
Subject: [PATCH] Docs: A host of corrections and improvements to inline
 documentation.

See #57840

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


git-svn-id: http://core.svn.wordpress.org/trunk@55244 1a063a9b-81f0-0310-95a4-ce76da25c4cd
---
 ...ss-wp-application-passwords-list-table.php |  2 +-
 .../includes/class-wp-comments-list-table.php |  2 +-
 .../includes/class-wp-links-list-table.php    |  2 +-
 .../includes/class-wp-media-list-table.php    |  2 +-
 .../includes/class-wp-ms-sites-list-table.php |  2 +-
 .../class-wp-ms-themes-list-table.php         |  2 +-
 .../includes/class-wp-ms-users-list-table.php |  2 +-
 .../class-wp-plugin-install-list-table.php    |  2 +-
 .../includes/class-wp-plugins-list-table.php  |  3 +-
 .../includes/class-wp-posts-list-table.php    |  2 +-
 .../includes/class-wp-terms-list-table.php    |  2 +-
 .../includes/class-wp-themes-list-table.php   |  2 +-
 wp-includes/block-template-utils.php          |  1 -
 .../class-wp-application-passwords.php        | 18 ++++++++-
 wp-includes/class-wp-block-supports.php       |  2 +-
 wp-includes/class-wp-date-query.php           | 12 +++---
 wp-includes/class-wp-meta-query.php           |  6 +--
 wp-includes/class-wp-tax-query.php            |  6 +--
 wp-includes/class-wp-user-query.php           |  7 ++--
 wp-includes/class-wp-user.php                 |  2 +-
 wp-includes/class-wpdb.php                    | 15 +++----
 wp-includes/comment.php                       |  2 +-
 wp-includes/deprecated.php                    | 40 +++++++++----------
 wp-includes/functions.wp-scripts.php          |  2 +-
 wp-includes/post.php                          |  2 +-
 wp-includes/version.php                       |  2 +-
 26 files changed, 79 insertions(+), 63 deletions(-)

diff --git a/wp-admin/includes/class-wp-application-passwords-list-table.php b/wp-admin/includes/class-wp-application-passwords-list-table.php
index 84297236b8..6c0bf26f76 100644
--- a/wp-admin/includes/class-wp-application-passwords-list-table.php
+++ b/wp-admin/includes/class-wp-application-passwords-list-table.php
@@ -21,7 +21,7 @@ class WP_Application_Passwords_List_Table extends WP_List_Table {
 	 *
 	 * @since 5.6.0
 	 *
-	 * @return array
+	 * @return string[] Array of column titles keyed by their column name.
 	 */
 	public function get_columns() {
 		return array(
diff --git a/wp-admin/includes/class-wp-comments-list-table.php b/wp-admin/includes/class-wp-comments-list-table.php
index b6bf9c8f19..8ffdddad18 100644
--- a/wp-admin/includes/class-wp-comments-list-table.php
+++ b/wp-admin/includes/class-wp-comments-list-table.php
@@ -458,7 +458,7 @@ class WP_Comments_List_Table extends WP_List_Table {
 	/**
 	 * @global int $post_id
 	 *
-	 * @return array
+	 * @return string[] Array of column titles keyed by their column name.
 	 */
 	public function get_columns() {
 		global $post_id;
diff --git a/wp-admin/includes/class-wp-links-list-table.php b/wp-admin/includes/class-wp-links-list-table.php
index b455733489..0025cb05ed 100644
--- a/wp-admin/includes/class-wp-links-list-table.php
+++ b/wp-admin/includes/class-wp-links-list-table.php
@@ -124,7 +124,7 @@ class WP_Links_List_Table extends WP_List_Table {
 	}
 
 	/**
-	 * @return array
+	 * @return string[] Array of column titles keyed by their column name.
 	 */
 	public function get_columns() {
 		return array(
diff --git a/wp-admin/includes/class-wp-media-list-table.php b/wp-admin/includes/class-wp-media-list-table.php
index 69f9484cf8..965305d9dd 100644
--- a/wp-admin/includes/class-wp-media-list-table.php
+++ b/wp-admin/includes/class-wp-media-list-table.php
@@ -320,7 +320,7 @@ class WP_Media_List_Table extends WP_List_Table {
 	}
 
 	/**
-	 * @return array
+	 * @return string[] Array of column titles keyed by their column name.
 	 */
 	public function get_columns() {
 		$posts_columns       = array();
diff --git a/wp-admin/includes/class-wp-ms-sites-list-table.php b/wp-admin/includes/class-wp-ms-sites-list-table.php
index 8984793e5c..d61e671a03 100644
--- a/wp-admin/includes/class-wp-ms-sites-list-table.php
+++ b/wp-admin/includes/class-wp-ms-sites-list-table.php
@@ -359,7 +359,7 @@ class WP_MS_Sites_List_Table extends WP_List_Table {
 	}
 
 	/**
-	 * @return array
+	 * @return string[] Array of column titles keyed by their column name.
 	 */
 	public function get_columns() {
 		$sites_columns = array(
diff --git a/wp-admin/includes/class-wp-ms-themes-list-table.php b/wp-admin/includes/class-wp-ms-themes-list-table.php
index fe861065b8..8245b5a7e8 100644
--- a/wp-admin/includes/class-wp-ms-themes-list-table.php
+++ b/wp-admin/includes/class-wp-ms-themes-list-table.php
@@ -322,7 +322,7 @@ class WP_MS_Themes_List_Table extends WP_List_Table {
 	}
 
 	/**
-	 * @return array
+	 * @return string[] Array of column titles keyed by their column name.
 	 */
 	public function get_columns() {
 		$columns = array(
diff --git a/wp-admin/includes/class-wp-ms-users-list-table.php b/wp-admin/includes/class-wp-ms-users-list-table.php
index d31a89980a..a97b507ffd 100644
--- a/wp-admin/includes/class-wp-ms-users-list-table.php
+++ b/wp-admin/includes/class-wp-ms-users-list-table.php
@@ -185,7 +185,7 @@ class WP_MS_Users_List_Table extends WP_List_Table {
 	}
 
 	/**
-	 * @return array
+	 * @return string[] Array of column titles keyed by their column name.
 	 */
 	public function get_columns() {
 		$users_columns = array(
diff --git a/wp-admin/includes/class-wp-plugin-install-list-table.php b/wp-admin/includes/class-wp-plugin-install-list-table.php
index 04013393ee..714a4fdd64 100644
--- a/wp-admin/includes/class-wp-plugin-install-list-table.php
+++ b/wp-admin/includes/class-wp-plugin-install-list-table.php
@@ -424,7 +424,7 @@ class WP_Plugin_Install_List_Table extends WP_List_Table {
 	}
 
 	/**
-	 * @return array
+	 * @return string[] Array of column titles keyed by their column name.
 	 */
 	public function get_columns() {
 		return array();
diff --git a/wp-admin/includes/class-wp-plugins-list-table.php b/wp-admin/includes/class-wp-plugins-list-table.php
index d57f06ad84..28107f3b3f 100644
--- a/wp-admin/includes/class-wp-plugins-list-table.php
+++ b/wp-admin/includes/class-wp-plugins-list-table.php
@@ -451,7 +451,8 @@ class WP_Plugins_List_Table extends WP_List_Table {
 
 	/**
 	 * @global string $status
-	 * @return array
+	 *
+	 * @return string[] Array of column titles keyed by their column name.
 	 */
 	public function get_columns() {
 		global $status;
diff --git a/wp-admin/includes/class-wp-posts-list-table.php b/wp-admin/includes/class-wp-posts-list-table.php
index c142f8802a..4c68dc8175 100644
--- a/wp-admin/includes/class-wp-posts-list-table.php
+++ b/wp-admin/includes/class-wp-posts-list-table.php
@@ -651,7 +651,7 @@ class WP_Posts_List_Table extends WP_List_Table {
 	}
 
 	/**
-	 * @return array
+	 * @return string[] Array of column titles keyed by their column name.
 	 */
 	public function get_columns() {
 		$post_type = $this->screen->post_type;
diff --git a/wp-admin/includes/class-wp-terms-list-table.php b/wp-admin/includes/class-wp-terms-list-table.php
index bb660b7071..482a7afb25 100644
--- a/wp-admin/includes/class-wp-terms-list-table.php
+++ b/wp-admin/includes/class-wp-terms-list-table.php
@@ -185,7 +185,7 @@ class WP_Terms_List_Table extends WP_List_Table {
 	}
 
 	/**
-	 * @return array
+	 * @return string[] Array of column titles keyed by their column name.
 	 */
 	public function get_columns() {
 		$columns = array(
diff --git a/wp-admin/includes/class-wp-themes-list-table.php b/wp-admin/includes/class-wp-themes-list-table.php
index 7fb72e6bb7..8d385f9a78 100644
--- a/wp-admin/includes/class-wp-themes-list-table.php
+++ b/wp-admin/includes/class-wp-themes-list-table.php
@@ -170,7 +170,7 @@ class WP_Themes_List_Table extends WP_List_Table {
 	}
 
 	/**
-	 * @return array
+	 * @return string[] Array of column titles keyed by their column name.
 	 */
 	public function get_columns() {
 		return array();
diff --git a/wp-includes/block-template-utils.php b/wp-includes/block-template-utils.php
index cdf4b7e1b6..d6c2589c86 100644
--- a/wp-includes/block-template-utils.php
+++ b/wp-includes/block-template-utils.php
@@ -1345,7 +1345,6 @@ function wp_generate_block_templates_export_file() {
 /**
  * Gets the template hierarchy for the given template slug to be created.
  *
- *
  * Note: Always add `index` as the last fallback template.
  *
  * @since 6.1.0
diff --git a/wp-includes/class-wp-application-passwords.php b/wp-includes/class-wp-application-passwords.php
index c4e34350fc..49c4e58b6b 100644
--- a/wp-includes/class-wp-application-passwords.php
+++ b/wp-includes/class-wp-application-passwords.php
@@ -68,8 +68,22 @@ class WP_Application_Passwords {
 	 *     @type string $name   The name of the application password.
 	 *     @type string $app_id A UUID provided by the application to uniquely identify it.
 	 * }
-	 * @return array|WP_Error The first key in the array is the new password, the second is its detailed information.
-	 *                        A WP_Error instance is returned on error.
+	 * @return array|WP_Error {
+	 *     Application password details, or a WP_Error instance if an error occurs.
+	 *
+	 *     @type string $0 The unhashed generated application password.
+	 *     @type array  $1 {
+	 *         The details about the created password.
+	 *
+	 *         @type string $uuid      The unique identifier for the application password.
+	 *         @type string $app_id    A UUID provided by the application to uniquely identify it.
+	 *         @type string $name      The name of the application password.
+	 *         @type string $password  A one-way hash of the password.
+	 *         @type int    $created   Unix timestamp of when the password was created.
+	 *         @type null   $last_used Null.
+	 *         @type null   $last_ip   Null.
+	 *     }
+	 * }
 	 */
 	public static function create_new_application_password( $user_id, $args = array() ) {
 		if ( ! empty( $args['name'] ) ) {
diff --git a/wp-includes/class-wp-block-supports.php b/wp-includes/class-wp-block-supports.php
index f319dbe0b9..ee2791dd17 100644
--- a/wp-includes/class-wp-block-supports.php
+++ b/wp-includes/class-wp-block-supports.php
@@ -91,7 +91,7 @@ class WP_Block_Supports {
 	 *
 	 * @since 5.6.0
 	 *
-	 * @return string[] Array of HTML attributes.
+	 * @return string[] Array of HTML attribute values keyed by their name.
 	 */
 	public function apply_block_supports() {
 		$block_type = WP_Block_Type_Registry::get_instance()->get_registered(
diff --git a/wp-includes/class-wp-date-query.php b/wp-includes/class-wp-date-query.php
index cf3bddc9ae..eee508657d 100644
--- a/wp-includes/class-wp-date-query.php
+++ b/wp-includes/class-wp-date-query.php
@@ -685,11 +685,11 @@ class WP_Date_Query {
 	 * @since 3.7.0
 	 *
 	 * @param array $query Date query arguments.
-	 * @return string[] {
+	 * @return array {
 	 *     Array containing JOIN and WHERE SQL clauses to append to the main query.
 	 *
-	 *     @type string $join  SQL fragment to append to the main JOIN clause.
-	 *     @type string $where SQL fragment to append to the main WHERE clause.
+	 *     @type string[] $join  Array of SQL fragments to append to the main JOIN clause.
+	 *     @type string[] $where Array of SQL fragments to append to the main WHERE clause.
 	 * }
 	 */
 	protected function get_sql_for_subquery( $query ) {
@@ -705,11 +705,11 @@ class WP_Date_Query {
 	 *
 	 * @param array $query        Date query clause.
 	 * @param array $parent_query Parent query of the current date query.
-	 * @return string[] {
+	 * @return array {
 	 *     Array containing JOIN and WHERE SQL clauses to append to the main query.
 	 *
-	 *     @type string $join  SQL fragment to append to the main JOIN clause.
-	 *     @type string $where SQL fragment to append to the main WHERE clause.
+	 *     @type string[] $join  Array of SQL fragments to append to the main JOIN clause.
+	 *     @type string[] $where Array of SQL fragments to append to the main WHERE clause.
 	 * }
 	 */
 	protected function get_sql_for_clause( $query, $parent_query ) {
diff --git a/wp-includes/class-wp-meta-query.php b/wp-includes/class-wp-meta-query.php
index 4d31fd50ed..bab45d725b 100644
--- a/wp-includes/class-wp-meta-query.php
+++ b/wp-includes/class-wp-meta-query.php
@@ -523,11 +523,11 @@ class WP_Meta_Query {
 	 * @param string $clause_key   Optional. The array key used to name the clause in the original `$meta_query`
 	 *                             parameters. If not provided, a key will be generated automatically.
 	 *                             Default empty string.
-	 * @return string[] {
+	 * @return array {
 	 *     Array containing JOIN and WHERE SQL clauses to append to a first-order query.
 	 *
-	 *     @type string $join  SQL fragment to append to the main JOIN clause.
-	 *     @type string $where SQL fragment to append to the main WHERE clause.
+	 *     @type string[] $join  Array of SQL fragments to append to the main JOIN clause.
+	 *     @type string[] $where Array of SQL fragments to append to the main WHERE clause.
 	 * }
 	 */
 	public function get_sql_for_clause( &$clause, $parent_query, $clause_key = '' ) {
diff --git a/wp-includes/class-wp-tax-query.php b/wp-includes/class-wp-tax-query.php
index 881e0ce2dc..afb7dc8db9 100644
--- a/wp-includes/class-wp-tax-query.php
+++ b/wp-includes/class-wp-tax-query.php
@@ -374,11 +374,11 @@ class WP_Tax_Query {
 	 *
 	 * @param array $clause       Query clause (passed by reference).
 	 * @param array $parent_query Parent query array.
-	 * @return string[] {
+	 * @return array {
 	 *     Array containing JOIN and WHERE SQL clauses to append to a first-order query.
 	 *
-	 *     @type string $join  SQL fragment to append to the main JOIN clause.
-	 *     @type string $where SQL fragment to append to the main WHERE clause.
+	 *     @type string[] $join  Array of SQL fragments to append to the main JOIN clause.
+	 *     @type string[] $where Array of SQL fragments to append to the main WHERE clause.
 	 * }
 	 */
 	public function get_sql_for_clause( &$clause, $parent_query ) {
diff --git a/wp-includes/class-wp-user-query.php b/wp-includes/class-wp-user-query.php
index e14f92901d..99bdd7fac0 100644
--- a/wp-includes/class-wp-user-query.php
+++ b/wp-includes/class-wp-user-query.php
@@ -67,11 +67,12 @@ class WP_User_Query {
 	public $query_limit;
 
 	/**
-	 * PHP5 constructor.
+	 * Constructor.
 	 *
 	 * @since 3.1.0
 	 *
 	 * @param null|string|array $query Optional. The query variables.
+	 *                                 See WP_User_Query::prepare_query() for information on accepted arguments.
 	 */
 	public function __construct( $query = null ) {
 		if ( ! empty( $query ) ) {
@@ -85,7 +86,7 @@ class WP_User_Query {
 	 *
 	 * @since 4.4.0
 	 *
-	 * @param array $args Query vars, as passed to `WP_User_Query`.
+	 * @param string|array $args Query vars, as passed to `WP_User_Query`.
 	 * @return array Complete query variables with undefined ones filled in with defaults.
 	 */
 	public static function fill_query_vars( $args ) {
@@ -147,7 +148,7 @@ class WP_User_Query {
 	 * @global WP_Roles $wp_roles WordPress role management object.
 	 *
 	 * @param string|array $query {
-	 *     Optional. Array or string of Query parameters.
+	 *     Optional. Array or string of query parameters.
 	 *
 	 *     @type int             $blog_id             The site ID. Default is the current site.
 	 *     @type string|string[] $role                An array or a comma-separated list of role names that users must match
diff --git a/wp-includes/class-wp-user.php b/wp-includes/class-wp-user.php
index ecfa1a5920..edf84c4163 100644
--- a/wp-includes/class-wp-user.php
+++ b/wp-includes/class-wp-user.php
@@ -894,7 +894,7 @@ class WP_User {
 	 * @since 4.9.0
 	 *
 	 * @return bool[] List of capabilities keyed by the capability name,
-	 *                e.g. array( 'edit_posts' => true, 'delete_posts' => false ).
+	 *                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-wpdb.php b/wp-includes/class-wpdb.php
index 659e0d3379..d5ed464e0b 100644
--- a/wp-includes/class-wpdb.php
+++ b/wp-includes/class-wpdb.php
@@ -1437,12 +1437,12 @@ class wpdb {
 	/**
 	 * Prepares a SQL query for safe execution.
 	 *
-	 * Uses sprintf()-like syntax. The following placeholders can be used in the query string:
+	 * Uses `sprintf()`-like syntax. The following placeholders can be used in the query string:
 	 *
-	 * - %d (integer)
-	 * - %f (float)
-	 * - %s (string)
-	 * - %i (identifier, e.g. table/field names)
+	 * - `%d` (integer)
+	 * - `%f` (float)
+	 * - `%s` (string)
+	 * - `%i` (identifier, e.g. table/field names)
 	 *
 	 * All placeholders MUST be left unquoted in the query string. A corresponding argument
 	 * MUST be passed for each placeholder.
@@ -1477,12 +1477,12 @@ class wpdb {
 	 *              from `$args` to `...$args`.
 	 * @since 6.2.0 Added `%i` for identifiers, e.g. table or field names.
 	 *              Check support via `wpdb::has_cap( 'identifier_placeholders' )`.
-	 *              This preserves compatibility with sprintf(), as the C version uses
+	 *              This preserves compatibility with `sprintf()`, as the C version uses
 	 *              `%d` and `$i` as a signed integer, whereas PHP only supports `%d`.
 	 *
 	 * @link https://www.php.net/sprintf Description of syntax.
 	 *
-	 * @param string      $query   Query statement with sprintf()-like placeholders.
+	 * @param string      $query   Query statement with `sprintf()`-like placeholders.
 	 * @param array|mixed $args    The array of variables to substitute into the query's placeholders
 	 *                             if being called with an array of arguments, or the first variable
 	 *                             to substitute into the query's placeholders if being called with
@@ -3319,6 +3319,7 @@ class wpdb {
 	 *
 	 *     @type int    $length The column length.
 	 *     @type string $type   One of 'byte' or 'char'.
+	 * }
 	 */
 	public function get_col_length( $table, $column ) {
 		$tablekey  = strtolower( $table );
diff --git a/wp-includes/comment.php b/wp-includes/comment.php
index ea4340d504..45a326ced5 100644
--- a/wp-includes/comment.php
+++ b/wp-includes/comment.php
@@ -1059,7 +1059,7 @@ function get_comment_pages_count( $comments = null, $per_page = null, $threaded
  *     @type int|string $max_depth If greater than 1, comment page will be determined
  *                                 for the top-level parent `$comment_id`.
  *                                 Defaults to the value of the 'thread_comments_depth' option.
- * } *
+ * }
  * @return int|null Comment page number or null on error.
  */
 function get_page_of_comment( $comment_id, $args = array() ) {
diff --git a/wp-includes/deprecated.php b/wp-includes/deprecated.php
index 645e32f5bf..05b547bdfc 100644
--- a/wp-includes/deprecated.php
+++ b/wp-includes/deprecated.php
@@ -3935,11 +3935,11 @@ function get_shortcut_link() {
 }
 
 /**
-* Ajax handler for saving a post from Press This.
-*
-* @since 4.2.0
-* @deprecated 4.9.0
-*/
+ * Ajax handler for saving a post from Press This.
+ *
+ * @since 4.2.0
+ * @deprecated 4.9.0
+ */
 function wp_ajax_press_this_save_post() {
 	_deprecated_function( __FUNCTION__, '4.9.0' );
 	if ( is_plugin_active( 'press-this/press-this-plugin.php' ) ) {
@@ -3952,11 +3952,11 @@ function wp_ajax_press_this_save_post() {
 }
 
 /**
-* Ajax handler for creating new category from Press This.
-*
-* @since 4.2.0
-* @deprecated 4.9.0
-*/
+ * Ajax handler for creating new category from Press This.
+ *
+ * @since 4.2.0
+ * @deprecated 4.9.0
+ */
 function wp_ajax_press_this_add_category() {
 	_deprecated_function( __FUNCTION__, '4.9.0' );
 	if ( is_plugin_active( 'press-this/press-this-plugin.php' ) ) {
@@ -4446,15 +4446,15 @@ function _get_path_to_translation_from_lang_dir( $domain ) {
 }
 
 /**
-  * Allows multiple block styles.
-  *
-  * @since 5.9.0
-  * @deprecated 6.1.0
-  *
-  * @param array $metadata Metadata for registering a block type.
-  * @return array Metadata for registering a block type.
-  */
-  function _wp_multiple_block_styles( $metadata ) {
+ * Allows multiple block styles.
+ *
+ * @since 5.9.0
+ * @deprecated 6.1.0
+ *
+ * @param array $metadata Metadata for registering a block type.
+ * @return array Metadata for registering a block type.
+ */
+function _wp_multiple_block_styles( $metadata ) {
 	_deprecated_function( __FUNCTION__, '6.1.0' );
 	return $metadata;
 }
@@ -4598,7 +4598,7 @@ function get_page_by_title( $page_title, $output = OBJECT, $post_type = 'page' )
  * @access private
  * @since 6.0.0
  * @deprecated 6.2.0 Site Editor's server-side redirect for missing postType and postId
- *             		 query args is removed. Thus, this function is no longer used.
+ *                   query args is removed. Thus, this function is no longer used.
  *
  * @return array|null A template object, or null if none could be found.
  */
diff --git a/wp-includes/functions.wp-scripts.php b/wp-includes/functions.wp-scripts.php
index d6c8aaddd2..64b9368344 100644
--- a/wp-includes/functions.wp-scripts.php
+++ b/wp-includes/functions.wp-scripts.php
@@ -81,7 +81,7 @@ function _wp_scripts_maybe_doing_it_wrong( $function_name, $handle = '' ) {
  *
  * @since 2.1.0
  *
- * @param string|bool|array $handles Optional. Scripts to be printed. Default 'false'.
+ * @param string|string[]|false $handles Optional. Scripts to be printed. Default 'false'.
  * @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/wp-includes/post.php b/wp-includes/post.php
index 73add034c0..af4823424b 100644
--- a/wp-includes/post.php
+++ b/wp-includes/post.php
@@ -1225,7 +1225,7 @@ function get_page_statuses() {
  * @since 4.9.6
  * @access private
  *
- * @return array
+ * @return string[] Array of privacy request status labels keyed by their status.
  */
 function _wp_privacy_statuses() {
 	return array(
diff --git a/wp-includes/version.php b/wp-includes/version.php
index 92c3a2e115..52df7eefdf 100644
--- a/wp-includes/version.php
+++ b/wp-includes/version.php
@@ -16,7 +16,7 @@
  *
  * @global string $wp_version
  */
-$wp_version = '6.3-alpha-55727';
+$wp_version = '6.3-alpha-55732';
 
 /**
  * Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.