Add missing/alter existing doc blocks for `wp-db.php`.

See #32444.

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


git-svn-id: http://core.svn.wordpress.org/trunk@32611 1a063a9b-81f0-0310-95a4-ce76da25c4cd

wp-includes/version.php

@@ -4,7 +4,7 @@
  *
  * @global string $wp_version
  */
-$wp_version = '4.3-alpha-32640';
+$wp_version = '4.3-alpha-32641';
 
 /**
  * Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.

wp-includes/wp-db.php

@@ -607,6 +607,8 @@ class wpdb {
 	 * @link https://core.trac.wordpress.org/ticket/3354
 	 * @since 2.0.8
 	 *
+	 * @global string $wp_version
+	 *
 	 * @param string $dbuser     MySQL database user
 	 * @param string $dbpassword MySQL database password
 	 * @param string $dbname     MySQL database name
@@ -652,7 +654,7 @@ class wpdb {
 	 *
 	 * @see wpdb::__construct()
 	 * @since 2.0.8
-	 * @return bool true
+	 * @return true
 	 */
 	public function __destruct() {
 		return true;
@@ -898,6 +900,7 @@ class wpdb {
 	 *
 	 * @since 3.0.0
 	 * @access public
+	 *
 	 * @param int $blog_id
 	 * @param int $site_id Optional.
 	 * @return int previous blog id
@@ -1026,8 +1029,7 @@ class wpdb {
 	 * @since 0.71
 	 *
 	 * @param string        $db  MySQL database name
-	 * @param resource $dbh Optional link identifier.
+	 * @param resource|null $dbh Optional link identifier.
-	 * @return null Always null.
 	 */
 	public function select( $db, $dbh = null ) {
 		if ( is_null($dbh) )
@@ -1051,7 +1053,6 @@ class wpdb {
 </ul>
 <p>If you don\'t know how to set up a database you should <strong>contact your host</strong>. If all else fails you may find help at the <a href="https://wordpress.org/support/">WordPress Support Forums</a>.</p>' ), htmlspecialchars( $db, ENT_QUOTES ), htmlspecialchars( $this->dbuser, ENT_QUOTES ) ), 'db_select_fail' );
 			}
-			return;
 		}
 	}
 
@@ -1163,9 +1164,10 @@ class wpdb {
 	 * Escapes content by reference for insertion into the database, for security
 	 *
 	 * @uses wpdb::_real_escape()
+	 *
 	 * @since 2.3.0
+	 *
 	 * @param string $string to escape
-	 * @return void
 	 */
 	public function escape_by_ref( &$string ) {
 		if ( ! is_float( $string ) )
@@ -1204,8 +1206,7 @@ class wpdb {
 	 *                              being called like {@link http://php.net/sprintf sprintf()}.
 	 * @param mixed       $args,... further variables to substitute into the query's placeholders if being called like
 	 *                              {@link http://php.net/sprintf sprintf()}.
-	 * @return null|false|string Sanitized query string, null if there is no query, false if there is an error and string
+	 * @return string|void Sanitized query string, if there is a query to prepare.
-	 * 	if there was something to prepare
 	 */
 	public function prepare( $query, $args ) {
 		if ( is_null( $query ) )
@@ -1262,7 +1263,7 @@ class wpdb {
 	 * @global array $EZSQL_ERROR Stores error information of query and error string
 	 *
 	 * @param string $str The error to display
-	 * @return false|null False if the showing of errors is disabled.
+	 * @return false|void False if the showing of errors is disabled.
 	 */
 	public function print_error( $str = '' ) {
 		global $EZSQL_ERROR;
@@ -1367,7 +1368,6 @@ class wpdb {
 	 * Kill cached query results.
 	 *
 	 * @since 0.71
-	 * @return void
 	 */
 	public function flush() {
 		$this->last_result = array();
@@ -1404,10 +1404,9 @@ class wpdb {
 	 * @since 3.9.0 $allow_bail parameter added.
 	 *
 	 * @param bool $allow_bail Optional. Allows the function to bail. Default true.
-	 * @return null|bool True with a successful connection, false on failure.
+	 * @return bool True with a successful connection, false on failure.
 	 */
 	public function db_connect( $allow_bail = true ) {
-
 		$this->is_mysql = true;
 
 		/*
@@ -1529,7 +1528,7 @@ class wpdb {
 	 * @since 3.9.0
 	 *
 	 * @param bool $allow_bail Optional. Allows the function to bail. Default true.
-	 * @return bool|null True if the connection is up.
+	 * @return bool|void True if the connection is up.
 	 */
 	public function check_connection( $allow_bail = true ) {
 		if ( $this->use_mysqli ) {
@@ -1759,10 +1758,13 @@ class wpdb {
 	 * @see wpdb::$field_types
 	 * @see wp_set_wpdb_vars()
 	 *
-	 * @param string $table table name
+	 * @param string       $table  Table name
-	 * @param array $data Data to insert (in column => value pairs). Both $data columns and $data values should be "raw" (neither should be SQL escaped).
+	 * @param array        $data   Data to insert (in column => value pairs).
-	 * @param array|string $format Optional. An array of formats to be mapped to each of the value in $data. If string, that format will be used for all of the values in $data.
+	 *                             Both $data columns and $data values should be "raw" (neither should be SQL escaped).
-	 * 	A format is one of '%d', '%f', '%s' (integer, float, string). If omitted, all values in $data will be treated as strings unless otherwise specified in wpdb::$field_types.
+	 * @param array|string $format Optional. An array of formats to be mapped to each of the value in $data.
+	 *                             If string, that format will be used for all of the values in $data.
+	 *                             A format is one of '%d', '%f', '%s' (integer, float, string).
+	 *                             If omitted, all values in $data will be treated as strings unless otherwise specified in wpdb::$field_types.
 	 * @return int|false The number of rows inserted, or false on error.
 	 */
 	public function insert( $table, $data, $format = null ) {
@@ -1780,10 +1782,13 @@ class wpdb {
 	 * @see wpdb::$field_types
 	 * @see wp_set_wpdb_vars()
 	 *
-	 * @param string $table table name
+	 * @param string       $table  Table name
-	 * @param array $data Data to insert (in column => value pairs). Both $data columns and $data values should be "raw" (neither should be SQL escaped).
+	 * @param array        $data   Data to insert (in column => value pairs).
-	 * @param array|string $format Optional. An array of formats to be mapped to each of the value in $data. If string, that format will be used for all of the values in $data.
+	 *                             Both $data columns and $data values should be "raw" (neither should be SQL escaped).
-	 * 	A format is one of '%d', '%f', '%s' (integer, float, string). If omitted, all values in $data will be treated as strings unless otherwise specified in wpdb::$field_types.
+	 * @param array|string $format Optional. An array of formats to be mapped to each of the value in $data.
+	 *                             If string, that format will be used for all of the values in $data.
+	 *                             A format is one of '%d', '%f', '%s' (integer, float, string).
+	 *                             If omitted, all values in $data will be treated as strings unless otherwise specified in wpdb::$field_types.
 	 * @return int|false The number of rows affected, or false on error.
 	 */
 	public function replace( $table, $data, $format = null ) {
@@ -1801,10 +1806,13 @@ class wpdb {
 	 * @see wpdb::$field_types
 	 * @see wp_set_wpdb_vars()
 	 *
-	 * @param string $table table name
+	 * @param string       $table  Table name
-	 * @param array $data Data to insert (in column => value pairs). Both $data columns and $data values should be "raw" (neither should be SQL escaped).
+	 * @param array        $data   Data to insert (in column => value pairs).
-	 * @param array|string $format Optional. An array of formats to be mapped to each of the value in $data. If string, that format will be used for all of the values in $data.
+	 *                             Both $data columns and $data values should be "raw" (neither should be SQL escaped).
-	 * 	A format is one of '%d', '%f', '%s' (integer, float, string). If omitted, all values in $data will be treated as strings unless otherwise specified in wpdb::$field_types.
+	 * @param array|string $format Optional. An array of formats to be mapped to each of the value in $data.
+	 *                             If string, that format will be used for all of the values in $data.
+	 *                             A format is one of '%d', '%f', '%s' (integer, float, string).
+	 *                             If omitted, all values in $data will be treated as strings unless otherwise specified in wpdb::$field_types.
 	 * @param string $type         Optional. What type of operation is this? INSERT or REPLACE. Defaults to INSERT.
 	 * @return int|false The number of rows affected, or false on error.
 	 */
@@ -1846,12 +1854,20 @@ class wpdb {
 	 * @see wpdb::$field_types
 	 * @see wp_set_wpdb_vars()
 	 *
-	 * @param string $table table name
+	 * @param string       $table        Table name
-	 * @param array $data Data to update (in column => value pairs). Both $data columns and $data values should be "raw" (neither should be SQL escaped).
+	 * @param array        $data         Data to update (in column => value pairs).
-	 * @param array $where A named array of WHERE clauses (in column => value pairs). Multiple clauses will be joined with ANDs. Both $where columns and $where values should be "raw".
+	 *                                   Both $data columns and $data values should be "raw" (neither should be SQL escaped).
-	 * @param array|string $format Optional. An array of formats to be mapped to each of the values in $data. If string, that format will be used for all of the values in $data.
+	 * @param array        $where        A named array of WHERE clauses (in column => value pairs).
-	 * 	A format is one of '%d', '%f', '%s' (integer, float, string). If omitted, all values in $data will be treated as strings unless otherwise specified in wpdb::$field_types.
+	 *                                   Multiple clauses will be joined with ANDs.
-	 * @param array|string $where_format Optional. An array of formats to be mapped to each of the values in $where. If string, that format will be used for all of the items in $where. A format is one of '%d', '%f', '%s' (integer, float, string). If omitted, all values in $where will be treated as strings.
+	 *                                   Both $where columns and $where values should be "raw".
+	 * @param array|string $format       Optional. An array of formats to be mapped to each of the values in $data.
+	 *                                   If string, that format will be used for all of the values in $data.
+	 *                                   A format is one of '%d', '%f', '%s' (integer, float, string).
+	 *                                   If omitted, all values in $data will be treated as strings unless otherwise specified in wpdb::$field_types.
+	 * @param array|string $where_format Optional. An array of formats to be mapped to each of the values in $where.
+	 *                                   If string, that format will be used for all of the items in $where.
+	 *                                   A format is one of '%d', '%f', '%s' (integer, float, string).
+	 *                                   If omitted, all values in $where will be treated as strings.
 	 * @return int|false The number of rows updated, or false on error.
 	 */
 	public function update( $table, $data, $where, $format = null, $where_format = null ) {
@@ -1898,9 +1914,14 @@ class wpdb {
 	 * @see wpdb::$field_types
 	 * @see wp_set_wpdb_vars()
 	 *
-	 * @param string $table table name
+	 * @param string       $table        Table name
-	 * @param array $where A named array of WHERE clauses (in column => value pairs). Multiple clauses will be joined with ANDs. Both $where columns and $where values should be "raw".
+	 * @param array        $where        A named array of WHERE clauses (in column => value pairs).
-	 * @param array|string $where_format Optional. An array of formats to be mapped to each of the values in $where. If string, that format will be used for all of the items in $where. A format is one of '%d', '%f', '%s' (integer, float, string). If omitted, all values in $where will be treated as strings unless otherwise specified in wpdb::$field_types.
+	 *                                   Multiple clauses will be joined with ANDs.
+	 *                                   Both $where columns and $where values should be "raw".
+	 * @param array|string $where_format Optional. An array of formats to be mapped to each of the values in $where.
+	 *                                   If string, that format will be used for all of the items in $where.
+	 *                                   A format is one of '%d', '%f', '%s' (integer, float, string).
+	 *                                   If omitted, all values in $where will be treated as strings unless otherwise specified in wpdb::$field_types.
 	 * @return int|false The number of rows updated, or false on error.
 	 */
 	public function delete( $table, $where, $where_format = null ) {
@@ -1942,7 +1963,7 @@ class wpdb {
 	 * @param string $table  Table name.
 	 * @param array  $data   Field/value pair.
 	 * @param mixed  $format Format for each field.
-	 * @return array|bool Returns an array of fields that contain paired values
+	 * @return array|false Returns an array of fields that contain paired values
 	 *                    and formats. Returns false for invalid values.
 	 */
 	protected function process_fields( $table, $data, $format ) {
@@ -2014,7 +2035,7 @@ class wpdb {
 	 *
 	 * @param array  $data  As it comes from the wpdb::process_field_formats() method.
 	 * @param string $table Table name.
-	 * @return The same array as $data with additional 'charset' keys.
+	 * @return array|false The same array as $data with additional 'charset' keys.
 	 */
 	protected function process_field_charsets( $data, $table ) {
 		foreach ( $data as $field => $value ) {
@@ -2043,7 +2064,7 @@ class wpdb {
 	 *
 	 * @param array  $data  As it comes from the wpdb::process_field_charsets() method.
 	 * @param string $table Table name.
-	 * @return array|False The same array as $data with additional 'length' keys, or false if
+	 * @return array|false The same array as $data with additional 'length' keys, or false if
 	 *                     any of the values were too long for their corresponding field.
 	 */
 	protected function process_field_lengths( $data, $table ) {
@@ -2107,10 +2128,12 @@ class wpdb {
 	 * @since 0.71
 	 *
 	 * @param string|null $query  SQL query.
-	 * @param string $output Optional. one of ARRAY_A | ARRAY_N | OBJECT constants. Return an associative array (column => value, ...),
+	 * @param string      $output Optional. one of ARRAY_A | ARRAY_N | OBJECT constants.
-	 * 	a numerically indexed array (0 => value, ...) or an object ( ->column = value ), respectively.
+	 *                            Return an associative array (column => value, ...),
+	 *                            a numerically indexed array (0 => value, ...) or
+	 *                            an object ( ->column = value ), respectively.
 	 * @param int         $y      Optional. Row to return. Indexed from 0.
-	 * @return mixed Database query result in format specified by $output or null on failure
+	 * @return array|object|null|void Database query result in format specified by $output or null on failure
 	 */
 	public function get_row( $query = null, $output = OBJECT, $y = 0 ) {
 		$this->func_call = "\$db->get_row(\"$query\",$output,$y)";
@@ -2180,10 +2203,12 @@ class wpdb {
 	 * @since 0.71
 	 *
 	 * @param string $query  SQL query.
-	 * @param string $output Optional. Any of ARRAY_A | ARRAY_N | OBJECT | OBJECT_K constants. With one of the first three, return an array of rows indexed from 0 by SQL result row number.
+	 * @param string $output Optional. Any of ARRAY_A | ARRAY_N | OBJECT | OBJECT_K constants.
+	 *                       With one of the first three, return an array of rows indexed from 0 by SQL result row number.
 	 *                       Each row is an associative array (column => value, ...), a numerically indexed array (0 => value, ...), or an object. ( ->column = value ), respectively.
-	 * 	With OBJECT_K, return an associative array of row objects keyed by the value of each row's first column's value. Duplicate keys are discarded.
+	 *                       With OBJECT_K, return an associative array of row objects keyed by the value of each row's first column's value.
-	 * @return mixed Database query results
+	 *                       Duplicate keys are discarded.
+	 * @return array|object|null Database query results
 	 */
 	public function get_results( $query = null, $output = OBJECT ) {
 		$this->func_call = "\$db->get_results(\"$query\", $output)";
@@ -2342,7 +2367,7 @@ class wpdb {
 	 *
 	 * @param string $table  Table name.
 	 * @param string $column Column name.
-	 * @return mixed Column character set as a string. False if the column has no
+	 * @return string|false|WP_Error Column character set as a string. False if the column has no
 	 *                               character set. WP_Error object if there was an error.
 	 */
 	public function get_col_charset( $table, $column ) {
@@ -2407,7 +2432,7 @@ class wpdb {
 	 *
 	 * @param string $table  Table name.
 	 * @param string $column Column name.
-	 * @return mixed array( 'length' => (int), 'type' => 'byte' | 'char' )
+	 * @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.
 	 */
@@ -2937,7 +2962,7 @@ class wpdb {
 	 *
 	 * @since 1.5.0
 	 *
-	 * @return bool
+	 * @return true
 	 */
 	public function timer_start() {
 		$this->time_start = microtime( true );
@@ -2981,10 +3006,11 @@ class wpdb {
 	 * Whether MySQL database is at least the required minimum version.
 	 *
 	 * @since 2.5.0
-	 * @uses $wp_version
-	 * @uses $required_mysql_version
 	 *
-	 * @return WP_Error
+	 * @global string $wp_version
+	 * @global string $required_mysql_version
+	 *
+	 * @return WP_Error|void
 	 */
 	public function check_database_version() {
 		global $wp_version, $required_mysql_version;
@@ -3038,7 +3064,7 @@ class wpdb {
 	 * @param string $db_cap The feature to check for. Accepts 'collation',
 	 *                       'group_concat', 'subqueries', 'set_charset',
 	 *                       or 'utf8mb4'.
-	 * @return bool Whether the database feature is supported, false otherwise.
+	 * @return int|false Whether the database feature is supported, false otherwise.
 	 */
 	public function has_cap( $db_cap ) {
 		$version = $this->db_version();
@@ -3083,7 +3109,7 @@ class wpdb {
 	 *
 	 * @since 2.5.0
 	 *
-	 * @return string The name of the calling function
+	 * @return string|array The name of the calling function
 	 */
 	public function get_caller() {
 		return wp_debug_backtrace_summary( __CLASS__ );