From 0124d01d1db2f588062cbd1a45d0404ac5b406c1 Mon Sep 17 00:00:00 2001
From: John Blackbourn <johnbillion@git.wordpress.org>
Date: Tue, 14 Dec 2021 16:24:02 +0000
Subject: [PATCH] Database: Correct and improve documentation for properties
 and parameters in `wpdb`.

See #53399

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


git-svn-id: http://core.svn.wordpress.org/trunk@51965 1a063a9b-81f0-0310-95a4-ce76da25c4cd
---
 wp-includes/version.php |  2 +-
 wp-includes/wp-db.php   | 47 +++++++++++++++++++++++++++--------------
 2 files changed, 32 insertions(+), 17 deletions(-)

diff --git a/wp-includes/version.php b/wp-includes/version.php
index c859e32a78..e386bd0c11 100644
--- a/wp-includes/version.php
+++ b/wp-includes/version.php
@@ -16,7 +16,7 @@
  *
  * @global string $wp_version
  */
-$wp_version = '5.9-beta2-52372';
+$wp_version = '5.9-beta2-52373';
 
 /**
  * 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 fa071c426d..68c4988a96 100644
--- a/wp-includes/wp-db.php
+++ b/wp-includes/wp-db.php
@@ -132,16 +132,24 @@ class wpdb {
 	 *
 	 * @since 0.71
 	 *
-	 * @var array|null
+	 * @var stdClass[]|null
 	 */
 	public $last_result;
 
 	/**
-	 * MySQL result, which is either a resource or boolean.
+	 * MySQL query result.
+	 *
+	 * Possible values:
+	 *
+	 * - `null` if a query is yet to be made or if the result has since been flushed
+	 * - `mysqli_result` instance when the MySQLi driver is in use, or `resource` when the older
+	 *   MySQL driver is in use, for successful SELECT, SHOW, DESCRIBE, or EXPLAIN queries
+	 * - `true` for other query types that were successful
+	 * - `false` if the query returned an error
 	 *
 	 * @since 0.71
 	 *
-	 * @var mixed
+	 * @var mysqli_result|resource|bool|null
 	 */
 	protected $result;
 
@@ -279,7 +287,7 @@ class wpdb {
 	 * @since 2.5.0
 	 *
 	 * @see wpdb::tables()
-	 * @var array
+	 * @var string[]
 	 */
 	public $tables = array(
 		'posts',
@@ -302,7 +310,7 @@ class wpdb {
 	 * @since 2.9.0
 	 *
 	 * @see wpdb::tables()
-	 * @var array
+	 * @var string[]
 	 */
 	public $old_tables = array( 'categories', 'post2cat', 'link2cat' );
 
@@ -312,7 +320,7 @@ class wpdb {
 	 * @since 3.0.0
 	 *
 	 * @see wpdb::tables()
-	 * @var array
+	 * @var string[]
 	 */
 	public $global_tables = array( 'users', 'usermeta' );
 
@@ -322,7 +330,7 @@ class wpdb {
 	 * @since 3.0.0
 	 *
 	 * @see wpdb::tables()
-	 * @var array
+	 * @var string[]
 	 */
 	public $ms_global_tables = array(
 		'blogs',
@@ -581,11 +589,18 @@ class wpdb {
 	protected $dbhost;
 
 	/**
-	 * Database Handle.
+	 * Database handle.
+	 *
+	 * Possible values:
+	 *
+	 * - `null` if the connection is yet to be made or has been closed
+	 * - `mysqli` instance when the MySQLi driver is in use
+	 * - `resource` when the older MySQL driver is in use
+	 * - `false` if the connection has failed
 	 *
 	 * @since 0.71
 	 *
-	 * @var string
+	 * @var mysqli|resource|false|null
 	 */
 	protected $dbh;
 
@@ -617,7 +632,7 @@ class wpdb {
 	 *
 	 * @since 3.9.0
 	 *
-	 * @var array
+	 * @var string[]
 	 */
 	protected $incompatible_modes = array(
 		'NO_ZERO_DATE',
@@ -849,9 +864,9 @@ class wpdb {
 	 *
 	 * @since 3.1.0
 	 *
-	 * @param resource $dbh     The resource given by mysql_connect.
-	 * @param string   $charset Optional. The character set. Default null.
-	 * @param string   $collate Optional. The collation. Default null.
+	 * @param mysqli|resource $dbh     The connection returned by `mysqli_connect()` or `mysql_connect()`.
+	 * @param string          $charset Optional. The character set. Default null.
+	 * @param string          $collate Optional. The collation. Default null.
 	 */
 	public function set_charset( $dbh, $charset = null, $collate = null ) {
 		if ( ! isset( $charset ) ) {
@@ -1141,15 +1156,15 @@ class wpdb {
 	}
 
 	/**
-	 * Selects a database using the current database connection.
+	 * Selects a database using the current or provided database connection.
 	 *
 	 * The database name will be changed based on the current database connection.
 	 * On failure, the execution will bail and display a DB error.
 	 *
 	 * @since 0.71
 	 *
-	 * @param string        $db  MySQL database name.
-	 * @param resource|null $dbh Optional link identifier.
+	 * @param string          $db  MySQL database name.
+	 * @param mysqli|resource $dbh Optional database connection.
 	 */
 	public function select( $db, $dbh = null ) {
 		if ( is_null( $dbh ) ) {