Changeset 52373

Timestamp:

12/14/2021 04:22:47 PM (5 years ago)

Author:

johnbillion

Message:

Database: Correct and improve documentation for properties and parameters in wpdb.

See #53399

File:

• trunk/src/wp-includes/wp-db.php (modified) (10 diffs)

trunk/src/wp-includes/wp-db.php

@@ -133 +133 @@
          * @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;
@@ -280 +288 @@
          *
          * @see wpdb::tables()
-         * @var array
+         * @var string[]
          */
         public $tables = array(
@@ -303 +311 @@
          *
          * @see wpdb::tables()
-         * @var array
+         * @var string[]
          */
         public $old_tables = array( 'categories', 'post2cat', 'link2cat' );
@@ -313 +321 @@
          *
          * @see wpdb::tables()
-         * @var array
+         * @var string[]
          */
         public $global_tables = array( 'users', 'usermeta' );
@@ -323 +331 @@
          *
          * @see wpdb::tables()
-         * @var array
+         * @var string[]
          */
         public $ms_global_tables = array(
@@ -582 +590 @@
 
         /**
-         * 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;
@@ -618 +633 @@
          * @since 3.9.0
          *
-         * @var array
+         * @var string[]
          */
         protected $incompatible_modes = array(
@@ -850 +865 @@
          * @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 ) {
@@ -1142 +1157 @@
 
         /**
-         * 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.
@@ -1149 +1164 @@
          * @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 ) {