Docs and code convention cleanups. see #11644 props hakre

git-svn-id: http://svn.automattic.com/wordpress/trunk@13314 1a063a9b-81f0-0310-95a4-ce76da25c4cd

wp-includes/wp-db.php

@@ -12,27 +12,27 @@
 /**
  * @since 0.71
  */
-define('EZSQL_VERSION', 'WP1.25');
+define( 'EZSQL_VERSION', 'WP1.25' );
 
 /**
  * @since 0.71
  */
-define('OBJECT', 'OBJECT', true);
+define( 'OBJECT', 'OBJECT', true );
 
 /**
  * @since {@internal Version Unknown}}
  */
-define('OBJECT_K', 'OBJECT_K', false);
+define( 'OBJECT_K', 'OBJECT_K', false );
 
 /**
  * @since 0.71
  */
-define('ARRAY_A', 'ARRAY_A', false);
+define( 'ARRAY_A', 'ARRAY_A', false );
 
 /**
  * @since 0.71
  */
-define('ARRAY_N', 'ARRAY_N', false);
+define( 'ARRAY_N', 'ARRAY_N', false );
 
 /**
  * WordPress Database Access Abstraction Object
@@ -65,7 +65,7 @@ class wpdb {
 	 * Whether to suppress errors during the DB bootstrapping.
 	 *
 	 * @access private
-	 * @since {@internal Version Unknown}}
+	 * @since 2.5
 	 * @var bool
 	 */
 	var $suppress_errors = false;
@@ -73,7 +73,9 @@ class wpdb {
 	/**
 	 * The last error during query.
 	 *
-	 * @since {@internal Version Unknown}}
+	 * @see get_last_error()
+	 * @since 2.5
+	 * @access private
 	 * @var string
 	 */
 	var $last_error = '';
@@ -87,6 +89,22 @@ class wpdb {
 	 */
 	var $num_queries = 0;
 
+	/**
+	 * Count of rows returned by previous query
+	 *
+	 * @since 1.2
+	 * @var int
+	 */
+	var $num_rows = 0; 
+
+	/**
+	 * Count of affected rows by previous query
+	 *
+	 * @since 0.71
+	 * @var int
+	 */
+	var $rows_affected = 0;
+
 	/**
 	 * Saved result of the last query made
 	 *
@@ -96,6 +114,14 @@ class wpdb {
 	 */
 	var $last_query;
 
+	/**
+	 * Results of the last query made
+	 *
+	 * @since {@internal Version Unknown}}
+	 * @var mixed
+	 */
+	var $last_result;
+
 	/**
 	 * Saved info on the table column
 	 *
@@ -135,7 +161,21 @@ class wpdb {
 	 * @var bool
 	 */
 	var $ready = false;
+
+	/**
+	 * {@internal Missing Description}}
+	 *
+	 * @since 3.0.0
+	 * @var int
+	 */
 	var $blogid = 0;
+
+	/**
+	 * {@internal Missing Description}}
+	 *
+	 * @since 3.0.0
+	 * @var int
+	 */
 	var $siteid = 0;
 
 	/**
@@ -251,6 +291,7 @@ class wpdb {
 	/**
 	 * List of deprecated WordPress tables
 	 *
+	 * @deprecated
 	 * @since 2.9.0
 	 * @access private
 	 * @see wpdb::tables()
@@ -343,9 +384,9 @@ class wpdb {
 	var $global_tables = array( 'users', 'usermeta' );
 
 	/**
-	 * Format specifiers for DB columns. Columns not listed here default to %s. Initialized in wp-settings.php.
+	 * Format specifiers for DB columns. Columns not listed here default to %s. Initialized during WP load.
 	 * 
-	 * Keys are colmn names, values are format types: 'ID' => '%d'
+	 * Keys are column names, values are format types: 'ID' => '%d'
 	 *
 	 * @since 2.8.0
 	 * @see wpdb:prepare()
@@ -406,10 +447,10 @@ class wpdb {
 	 * @param string $dbname MySQL database name
 	 * @param string $dbhost MySQL database host
 	 */
-	function wpdb($dbuser, $dbpassword, $dbname, $dbhost) {
+	function wpdb( $dbuser, $dbpassword, $dbname, $dbhost ) {
 		if( defined( 'WP_USE_MULTIPLE_DB' ) && WP_USE_MULTIPLE_DB )
 			$this->db_connect();
-		return $this->__construct($dbuser, $dbpassword, $dbname, $dbhost);
+		return $this->__construct( $dbuser, $dbpassword, $dbname, $dbhost );
 	}
 
 	/**
@@ -426,8 +467,8 @@ class wpdb {
 	 * @param string $dbname MySQL database name
 	 * @param string $dbhost MySQL database host
 	 */
-	function __construct($dbuser, $dbpassword, $dbname, $dbhost) {
+	function __construct( $dbuser, $dbpassword, $dbname, $dbhost ) {
-		register_shutdown_function(array(&$this, "__destruct"));
+		register_shutdown_function( array( &$this, '__destruct' ) );
 
 		if ( WP_DEBUG )
 			$this->show_errors();
@@ -442,14 +483,14 @@ class wpdb {
 			$this->collate = DB_COLLATE;
 		}
 
-		if ( defined('DB_CHARSET') )
+		if ( defined( 'DB_CHARSET' ) )
 			$this->charset = DB_CHARSET;
 
 		$this->dbuser = $dbuser;
 
-		$this->dbh = @mysql_connect($dbhost, $dbuser, $dbpassword, true);
+		$this->dbh = @mysql_connect( $dbhost, $dbuser, $dbpassword, true );
-		if (!$this->dbh) {
+		if ( !$this->dbh ) {
-			$this->bail(sprintf(/*WP_I18N_DB_CONN_ERROR*/"
+			$this->bail( sprintf( /*WP_I18N_DB_CONN_ERROR*/"
 <h1>Error establishing a database connection</h1>
 <p>This either means that the username and password information in your <code>wp-config.php</code> file is incorrect or we can't contact the database server at <code>%s</code>. This could mean your host's database server is down.</p>
 <ul>
@@ -458,33 +499,32 @@ class wpdb {
 	<li>Are you sure that the database server is running?</li>
 </ul>
 <p>If you're unsure what these terms mean you should probably contact your host. If you still need help you can always visit the <a href='http://wordpress.org/support/'>WordPress Support Forums</a>.</p>
-"/*/WP_I18N_DB_CONN_ERROR*/, $dbhost), 'db_connect_fail');
+"/*/WP_I18N_DB_CONN_ERROR*/, $dbhost ), 'db_connect_fail' );
 			return;
 		}
 
 		$this->ready = true;
 
-		if ( $this->has_cap( 'collation' ) && !empty($this->charset) ) {
+		if ( $this->has_cap( 'collation' ) && !empty( $this->charset ) ) {
-			if ( function_exists('mysql_set_charset') ) {
+			if ( function_exists( 'mysql_set_charset' ) ) {
-				mysql_set_charset($this->charset, $this->dbh);
+				mysql_set_charset( $this->charset, $this->dbh );
 				$this->real_escape = true;
 			} else {
-				$collation_query = "SET NAMES '{$this->charset}'";
+				$query = $this->prepare( 'SET NAMES %s', $this->charset );
-				if ( !empty($this->collate) )
+				if ( ! empty( $this->collate ) )
-					$collation_query .= " COLLATE '{$this->collate}'";
+					$query .= $this->prepare( ' COLLATE %s', $this->collate );
-				$this->query($collation_query);
+				$this->query( $query );
 			}
 		}
 
-		$this->select($dbname, $this->dbh);
+		$this->select( $dbname, $this->dbh );
 	}
 
 	/**
 	 * PHP5 style destructor and will run when database object is destroyed.
 	 *
 	 * @since 2.0.8
-	 *
+	 * @return bool true
-	 * @return bool Always true
 	 */
 	function __destruct() {
 		return true;
@@ -503,13 +543,10 @@ class wpdb {
 	 */
 	function set_prefix( $prefix ) {
 
-		if ( preg_match('|[^a-z0-9_]|i', $prefix) )
+		if ( preg_match( '|[^a-z0-9_]|i', $prefix ) )
 			return new WP_Error('invalid_db_prefix', /*WP_I18N_DB_BAD_PREFIX*/'Invalid database prefix'/*/WP_I18N_DB_BAD_PREFIX*/);
 
-		if ( is_multisite() )
+		$old_prefix = is_multisite() ? '' : $prefix;
-			$old_prefix = '';
-		else
-			$old_prefix = $prefix;
 
 		if ( isset( $this->base_prefix ) )
 			$old_prefix = $this->base_prefix;
@@ -517,7 +554,7 @@ class wpdb {
 		foreach ( $this->tables( 'global' ) as $table )
 			$this->$table = $prefix . $table;
 
-		if ( defined('VHOST') && empty( $this->blogid ) )
+		if ( defined( 'VHOST' ) && empty( $this->blogid ) )
 			return $old_prefix;
 
 		$this->prefix = $this->get_blog_prefix( $this->blogid );
@@ -528,17 +565,26 @@ class wpdb {
 		foreach ( (array) $this->tables( 'old' ) as $table )
 			$this->$table = $this->prefix . $table;
 
-		if ( defined('CUSTOM_USER_TABLE') )
+		if ( defined( 'CUSTOM_USER_TABLE' ) )
 			$this->users = CUSTOM_USER_TABLE;
 
-		if ( defined('CUSTOM_USER_META_TABLE') )
+		if ( defined( 'CUSTOM_USER_META_TABLE' ) )
 			$this->usermeta = CUSTOM_USER_META_TABLE;
 
 		return $old_prefix;
 	}
 
-	function set_blog_id($blog_id, $site_id = '') {
+	/**
-		if ( !empty($site_id) )
+	 * Sets blog id.
+	 *
+	 * @since 3.0.0
+	 * @access public
+	 * @param string $blog_id
+	 * @param string $site_id. Optional.
+	 * @return string previous blog id
+	 */	
+	function set_blog_id( $blog_id, $site_id = '' ) {
+		if ( ! empty( $site_id ) )
 			$this->siteid = $site_id;
 
 		$old_blog_id  = $this->blogid;
@@ -555,7 +601,15 @@ class wpdb {
 		return $old_blog_id;
 	}
 
-	function get_blog_prefix( $blog_id = '' ) {
+	/**
+	 * Gets blog prefix.
+	 *
+	 * @uses is_multisite()
+	 * @since 3.0.0
+	 * @param int $blog_id. Optional.
+	 * @return string Blog prefix.
+	 */
+	function get_blog_prefix( $blog_id = 0 ) {
 		if ( is_multisite() && $blog_id ) {
 			if ( defined('MULTISITE') && ( $blog_id == 0 || $blog_id == 1 ) )
 				return $this->base_prefix;
@@ -620,10 +674,10 @@ class wpdb {
 	 * @param string $db MySQL database name
 	 * @return null Always null.
 	 */
-	function select($db, &$dbh) {
+	function select( $db, &$dbh ) {
-		if (!@mysql_select_db($db, $dbh)) {
+		if ( !@mysql_select_db( $db, $dbh ) ) {
 			$this->ready = false;
-			$this->bail(sprintf(/*WP_I18N_DB_SELECT_DB*/'
+			$this->bail( sprintf( /*WP_I18N_DB_SELECT_DB*/'
 <h1>Can&#8217;t select database</h1>
 <p>We were able to connect to the database server (which means your username and password is okay) but not able to select the <code>%1$s</code> database.</p>
 <ul>
@@ -631,24 +685,55 @@ class wpdb {
 <li>Does the user <code>%2$s</code> have permission to use the <code>%1$s</code> database?</li>
 <li>On some systems the name of your database is prefixed with your username, so it would be like <code>username_%1$s</code>. Could that be the problem?</li>
 </ul>
-<p>If you don\'t know how to setup a database you should <strong>contact your host</strong>. If all else fails you may find help at the <a href="http://wordpress.org/support/">WordPress Support Forums</a>.</p>'/*/WP_I18N_DB_SELECT_DB*/, $db, $this->dbuser), 'db_select_fail');
+<p>If you don\'t know how to setup a database you should <strong>contact your host</strong>. If all else fails you may find help at the <a href="http://wordpress.org/support/">WordPress Support Forums</a>.</p>'/*/WP_I18N_DB_SELECT_DB*/, $db, $this->dbuser ), 'db_select_fail' );
 			return;
 		}
 	}
 
-	function _weak_escape($string) {
+	/**
-		return addslashes($string);
+	 * Weak escape
+	 *
+	 * @see addslashes()
+	 * @since  unknown
+	 * @access private
+	 *
+	 * @param  string $string
+	 * @return string
+	 */
+	function _weak_escape( $string ) {
+		return addslashes( $string );
 	}
 
-	function _real_escape($string) {
+	/**
+	 * Real escape
+	 *
+	 * @see mysql_real_escape_string()
+	 * @see addslashes()
+	 * @since 2.8
+	 * @access private
+	 *
+	 * @param  string $string to escape
+	 * @return string escaped
+	 */
+	function _real_escape( $string ) {
 		if ( $this->dbh && $this->real_escape )
 			return mysql_real_escape_string( $string, $this->dbh );
 		else
 			return addslashes( $string );
 	}
 
-	function _escape($data) {
+	/**
-		if ( is_array($data) ) {
+	 * Escape data.
+	 *
+	 * @see esc_sql()
+	 * @since  2.8
+	 * @access private
+	 *
+	 * @param  string|array $data
+	 * @return string|array escaped
+	 */
+	function _escape( $data ) {
+		if ( is_array( $data ) ) {
 			foreach ( (array) $data as $k => $v ) {
 				if ( is_array($v) )
 					$data[$k] = $this->_escape( $v );
@@ -667,13 +752,13 @@ class wpdb {
 	 *
 	 * @since 0.71
 	 *
-	 * @param string|array $data
+	 * @param  string|array $data to escape
-	 * @return string query safe string
+	 * @return string|array escaped as query safe string
 	 */
-	function escape($data) {
+	function escape( $data ) {
-		if ( is_array($data) ) {
+		if ( is_array( $data ) ) {
 			foreach ( (array) $data as $k => $v ) {
-				if ( is_array($v) )
+				if ( is_array( $v ) )
 					$data[$k] = $this->escape( $v );
 				else
 					$data[$k] = $this->_weak_escape( $v );
@@ -690,15 +775,25 @@ class wpdb {
 	 *
 	 * @since 2.3.0
 	 *
-	 * @param string $s
+	 * @param  string $string to escape
+	 * @return void
 	 */
-	function escape_by_ref(&$string) {
+	function escape_by_ref( &$string ) {
 		$string = $this->_real_escape( $string );
 	}
 
 	/**
 	 * Prepares a SQL query for safe execution.  Uses sprintf()-like syntax.
 	 *
+	 * The following directives can be used in the query format string: 
+	 *   %d (decimal number)  
+	 *   %s (string)
+	 *   %% (literal percentage sign - no argument needed) 
+	 *
+	 * Both %d and %s are to be left unquoted in the query string and   
+	 * they need an argument passed for them. Literals (%) as parts of
+	 * the query must be properly written as %%.
+	 *
 	 * This function only supports a small subset of the sprintf syntax; it only supports %d (decimal number), %s (string).
 	 * Does not support sign, padding, alignment, width or precision specifiers.
 	 * Does not support argument numbering/swapping.
@@ -715,23 +810,27 @@ class wpdb {
 	 * @since 2.3.0
 	 *
 	 * @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 like {@link http://php.net/vsprintf vsprintf()}, or the first variable to substitute into the query's placeholders if being called like {@link http://php.net/sprintf sprintf()}.
+	 * @param array|mixed $args The array of variables to substitute into the query's placeholders if being called like
-	 * @param mixed $args,... further variables to substitute into the query's placeholders if being called like {@link http://php.net/sprintf sprintf()}.
+	 * 	{@link http://php.net/vsprintf vsprintf()}, or the first variable to substitute into the query's placeholders if
-	 * @return null|string Sanitized query string
+	 * 	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
+	 * 	if there was something to prepare
 	 */
-	function prepare($query = null) { // ( $query, *$args )
+	function prepare( $query = null ) { // ( $query, *$args )
 		if ( is_null( $query ) )
 			return;
 		$args = func_get_args();
-		array_shift($args);
+		array_shift( $args );
 		// If args were passed as an array (as in vsprintf), move them up
-		if ( isset($args[0]) && is_array($args[0]) )
+		if ( isset( $args[0] ) && is_array($args[0]) )
 			$args = $args[0];
-		$query = str_replace("'%s'", '%s', $query); // in case someone mistakenly already singlequoted it
+		$query = str_replace( "'%s'", '%s', $query ); // in case someone mistakenly already singlequoted it
-		$query = str_replace('"%s"', '%s', $query); // doublequote unquoting
+		$query = str_replace( '"%s"', '%s', $query ); // doublequote unquoting
-		$query = str_replace('%s', "'%s'", $query); // quote the strings
+		$query = str_replace( '%s', "'%s'", $query ); // quote the strings
-		array_walk($args, array(&$this, 'escape_by_ref'));
+		array_walk( $args, array( &$this, 'escape_by_ref' ) );
-		return @vsprintf($query, $args);
+		return @vsprintf( $query, $args );
 	}
 
 	/**
@@ -743,11 +842,12 @@ class wpdb {
 	 * @param string $str The error to display
 	 * @return bool False if the showing of errors is disabled.
 	 */
-	function print_error($str = '') {
+	function print_error( $str = '' ) {
 		global $EZSQL_ERROR;
 
-		if (!$str) $str = mysql_error($this->dbh);
+		if ( !$str )
-		$EZSQL_ERROR[] = array ('query' => $this->last_query, 'error_str' => $str);
+			$str = mysql_error( $this->dbh );
+		$EZSQL_ERROR[] = array( 'query' => $this->last_query, 'error_str' => $str );
 
 		if ( $this->suppress_errors )
 			return false;
@@ -780,8 +880,8 @@ class wpdb {
 			if ( defined( 'DIEONDBERROR' ) )
 				die( $msg );
 		} else {
-			$str = htmlspecialchars($str, ENT_QUOTES);
+			$str   = htmlspecialchars( $str, ENT_QUOTES );
-			$query = htmlspecialchars($this->last_query, ENT_QUOTES);
+			$query = htmlspecialchars( $this->last_query, ENT_QUOTES );
 
 			print "<div id='error'>
 			<p class='wpdberror'><strong>WordPress database error:</strong> [$str]<br />
@@ -799,6 +899,7 @@ class wpdb {
 	 * errors.
 	 *
 	 * @since 0.71
+	 * @see wpdb::hide_errors()
 	 *
 	 * @param bool $show Whether to show or hide errors
 	 * @return bool Old value for showing errors.
@@ -812,7 +913,10 @@ class wpdb {
 	/**
 	 * Disables showing of database errors.
 	 *
+	 * By default database errors are not shown.
+	 *
 	 * @since 0.71
+	 * @see wpdb::show_errors()
 	 *
 	 * @return bool Whether showing of errors was active or not
 	 */
@@ -825,12 +929,17 @@ class wpdb {
 	/**
 	 * Whether to suppress database errors.
 	 *
-	 * @param unknown_type $suppress
+	 * By default database errors are suppressed, with a simple
-	 * @return unknown
+	 * call to this function they can be enabled.
+	 *
+	 * @since 2.5
+	 * @see wpdb::hide_errors()
+	 * @param bool $suppress Optional. New value. Defaults to true.
+	 * @return bool Old value
 	 */
 	function suppress_errors( $suppress = true ) {
 		$errors = $this->suppress_errors;
-		$this->suppress_errors = $suppress;
+		$this->suppress_errors = (bool) $suppress;
 		return $errors;
 	}
 
@@ -838,6 +947,7 @@ class wpdb {
 	 * Kill cached query results.
 	 *
 	 * @since 0.71
+	 * @return void
 	 */
 	function flush() {
 		$this->last_result = array();
@@ -847,7 +957,7 @@ class wpdb {
 
 	function db_connect( $query = "SELECT" ) {
 		global $db_list, $global_db_list;
-		if ( is_array( $db_list ) == false )
+		if ( ! is_array( $db_list ) )
 			return true;
 
 		if ( $this->blogs != '' && preg_match("/(" . $this->blogs . "|" . $this->users . "|" . $this->usermeta . "|" . $this->site . "|" . $this->sitemeta . "|" . $this->sitecategories . ")/i",$query) ) {
@@ -867,7 +977,7 @@ class wpdb {
 		$dbhname = "dbh" . $action;
 		$this->$dbhname = @mysql_connect( $details[ 'db_host' ], $details[ 'db_user' ], $details[ 'db_password' ] );
 		if (!$this->$dbhname ) {
-			$this->bail("
+			$this->bail(/*WP_I18N_DB_CONNECT_DB*/"
 <h1>Error establishing a database connection</h1>
 <p>This either means that the username and password information in your <code>wp-config.php</code> file is incorrect or we can't contact the database server at <code>{$details['db_host']}</code>. This could mean your host's database server is down.</p>
 <ul>
@@ -876,7 +986,7 @@ class wpdb {
 	<li>Are you sure that the database server is running?</li>
 </ul>
 <p>If you're unsure what these terms mean you should probably contact your host. If you still need help you can always visit the <a href='http://wordpress.org/support/'>WordPress Support Forums</a>.</p>
-");
+"/*/WP_I18N_DB_CONNECT_DB*/);
 		}
 		$this->select( $details[ 'db_name' ], $this->$dbhname );
 	}
@@ -888,19 +998,19 @@ class wpdb {
 	 *
 	 * @since 0.71
 	 *
-	 * @param string $query
+	 * @param string $query Database query
 	 * @return int|false Number of rows affected/selected or false on error
 	 */
-	function query($query) {
+	function query( $query ) {
 		if ( ! $this->ready )
 			return false;
 
 		// filter the query, if filters are available
 		// NOTE: some queries are made before the plugins have been loaded, and thus cannot be filtered with this method
-		if ( function_exists('apply_filters') )
+		if ( function_exists( 'apply_filters' ) )
-			$query = apply_filters('query', $query);
+			$query = apply_filters( 'query', $query );
 
-		// initialise return
+		// initialize return
 		$return_val = 0;
 		$this->flush();
 
@@ -910,8 +1020,7 @@ class wpdb {
 		// Keep track of the last query for debug..
 		$this->last_query = $query;
 
-		// Perform the query via std mysql_query function..
+		if ( defined( 'SAVEQUERIES' ) && SAVEQUERIES )
-		if ( defined('SAVEQUERIES') && SAVEQUERIES )
 			$this->timer_start();
 
 		// use $this->dbh for read ops, and $this->dbhwrite for write ops
@@ -939,45 +1048,44 @@ class wpdb {
 			$this->last_db_used = "other/read";
 		}
 
-		$this->result = @mysql_query($query, $dbh);
+		$this->result = @mysql_query( $query, $dbh );
 		++$this->num_queries;
 
 		if ( defined('SAVEQUERIES') && SAVEQUERIES )
 			$this->queries[] = array( $query, $this->timer_stop(), $this->get_caller() );
 
 		// If there is an error then take note of it..
-		if ( $this->last_error = mysql_error($dbh) ) {
+		if ( $this->last_error = mysql_error( $dbh ) ) {
 			$this->print_error();
 			return false;
 		}
 
-		if ( preg_match("/^\\s*(insert|delete|update|replace|alter) /i",$query) ) {
+		if ( preg_match( "/^\\s*(insert|delete|update|replace|alter) /i", $query ) ) {
-			$this->rows_affected = mysql_affected_rows($dbh);
+			$this->rows_affected = mysql_affected_rows( $dbh );
 			// Take note of the insert_id
-			if ( preg_match("/^\\s*(insert|replace) /i",$query) ) {
+			if ( preg_match( "/^\\s*(insert|replace) /i", $query ) ) {
 				$this->insert_id = mysql_insert_id($dbh);
 			}
 			// Return number of rows affected
 			$return_val = $this->rows_affected;
 		} else {
 			$i = 0;
-			while ($i < @mysql_num_fields($this->result)) {
+			while ( $i < @mysql_num_fields( $this->result ) ) {
-				$this->col_info[$i] = @mysql_fetch_field($this->result);
+				$this->col_info[$i] = @mysql_fetch_field( $this->result );
 				$i++;
 			}
 			$num_rows = 0;
-			while ( $row = @mysql_fetch_object($this->result) ) {
+			while ( $row = @mysql_fetch_object( $this->result ) ) {
 				$this->last_result[$num_rows] = $row;
 				$num_rows++;
 			}
 
-			@mysql_free_result($this->result);
+			@mysql_free_result( $this->result );
 
 			// Log number of rows the query returned
+			// and return number of rows selected
 			$this->num_rows = $num_rows;
-
+			$return_val     = $num_rows;
-			// Return number of rows selected
-			$return_val = $this->num_rows;
 		}
 
 		return $return_val;
@@ -998,21 +1106,21 @@ class wpdb {
 	 * @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', '%s' (decimal number, string).  If omitted, all values in $data will be treated as strings.
 	 * @return int|false The number of rows inserted, or false on error.
 	 */
-	function insert($table, $data, $format = null) {
+	function insert( $table, $data, $format = null ) {
 		$formats = $format = (array) $format;
-		$fields = array_keys($data);
+		$fields = array_keys( $data );
 		$formatted_fields = array();
 		foreach ( $fields as $field ) {
-			if ( !empty($format) )
+			if ( !empty( $format ) )
-				$form = ( $form = array_shift($formats) ) ? $form : $format[0];
+				$form = ( $form = array_shift( $formats ) ) ? $form : $format[0];
-			elseif ( isset($this->field_types[$field]) )
+			elseif ( isset( $this->field_types[$field] ) )
 				$form = $this->field_types[$field];
 			else
 				$form = '%s';
 			$formatted_fields[] = $form;
 		}
 		$sql = "INSERT INTO `$table` (`" . implode( '`,`', $fields ) . "`) VALUES ('" . implode( "','", $formatted_fields ) . "')";
-		return $this->query( $this->prepare( $sql, $data) );
+		return $this->query( $this->prepare( $sql, $data ) );
 	}
 
 
@@ -1033,15 +1141,15 @@ class wpdb {
 	 * @param array|string $format_where (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', '%s' (decimal number, string).  If omitted, all values in $where will be treated as strings.
 	 * @return int|false The number of rows updated, or false on error.
 	 */
-	function update($table, $data, $where, $format = null, $where_format = null) {
+	function update( $table, $data, $where, $format = null, $where_format = null ) {
-		if ( !is_array( $where ) )
+		if ( ! is_array( $where ) )
 			return false;
 
 		$formats = $format = (array) $format;
 		$bits = $wheres = array();
-		foreach ( (array) array_keys($data) as $field ) {
+		foreach ( (array) array_keys( $data ) as $field ) {
-			if ( !empty($format) )
+			if ( !empty( $format ) )
-				$form = ( $form = array_shift($formats) ) ? $form : $format[0];
+				$form = ( $form = array_shift( $formats ) ) ? $form : $format[0];
 			elseif ( isset($this->field_types[$field]) )
 				$form = $this->field_types[$field];
 			else
@@ -1050,10 +1158,10 @@ class wpdb {
 		}
 
 		$where_formats = $where_format = (array) $where_format;
-		foreach ( (array) array_keys($where) as $field ) {
+		foreach ( (array) array_keys( $where ) as $field ) {
-			if ( !empty($where_format) )
+			if ( !empty( $where_format ) )
-				$form = ( $form = array_shift($where_formats) ) ? $form : $where_format[0];
+				$form = ( $form = array_shift( $where_formats ) ) ? $form : $where_format[0];
-			elseif ( isset($this->field_types[$field]) )
+			elseif ( isset( $this->field_types[$field] ) )
 				$form = $this->field_types[$field];
 			else
 				$form = '%s';
@@ -1061,7 +1169,7 @@ class wpdb {
 		}
 
 		$sql = "UPDATE `$table` SET " . implode( ', ', $bits ) . ' WHERE ' . implode( ' AND ', $wheres );
-		return $this->query( $this->prepare( $sql, array_merge(array_values($data), array_values($where))) );
+		return $this->query( $this->prepare( $sql, array_merge( array_values( $data ), array_values( $where ) ) ) );
 	}
 
 	/**
@@ -1073,23 +1181,23 @@ class wpdb {
 	 *
 	 * @since 0.71
 	 *
-	 * @param string|null $query SQL query.  If null, use the result from the previous query.
+	 * @param string|null $query Optional. SQL query. If null (default), uses the result from the previous query.
 	 * @param int $x (optional) Column of value to return.  Indexed from 0.
 	 * @param int $y (optional) Row of value to return.  Indexed from 0.
-	 * @return string Database query result
+	 * @return string|null Database query result, or null on failure
 	 */
-	function get_var($query=null, $x = 0, $y = 0) {
+	function get_var( $query = null, $x = 0, $y = 0 ) {
-		$this->func_call = "\$db->get_var(\"$query\",$x,$y)";
+		$this->func_call = "\$db->get_var(\"$query\", $x, $y)";
 		if ( $query )
-			$this->query($query);
+			$this->query( $query );
 
 		// Extract var out of cached results based x,y vals
 		if ( !empty( $this->last_result[$y] ) ) {
-			$values = array_values(get_object_vars($this->last_result[$y]));
+			$values = array_values( get_object_vars( $this->last_result[$y] ) );
 		}
 
 		// If there is a value return it else return null
-		return (isset($values[$x]) && $values[$x]!=='') ? $values[$x] : null;
+		return ( isset( $values[$x] ) && $values[$x] !== '' ) ? $values[$x] : null;
 	}
 
 	/**
@@ -1102,24 +1210,24 @@ class wpdb {
 	 * @param string|null $query SQL query.
 	 * @param string $output (optional) one of ARRAY_A | ARRAY_N | OBJECT constants.  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 specifed by $output
+	 * @return mixed Database query result in format specifed by $output or null on failure
 	 */
-	function get_row($query = null, $output = OBJECT, $y = 0) {
+	function get_row( $query = null, $output = OBJECT, $y = 0 ) {
 		$this->func_call = "\$db->get_row(\"$query\",$output,$y)";
 		if ( $query )
-			$this->query($query);
+			$this->query( $query );
 		else
 			return null;
 
-		if ( !isset($this->last_result[$y]) )
+		if ( !isset( $this->last_result[$y] ) )
 			return null;
 
 		if ( $output == OBJECT ) {
 			return $this->last_result[$y] ? $this->last_result[$y] : null;
 		} elseif ( $output == ARRAY_A ) {
-			return $this->last_result[$y] ? get_object_vars($this->last_result[$y]) : null;
+			return $this->last_result[$y] ? get_object_vars( $this->last_result[$y] ) : null;
 		} elseif ( $output == ARRAY_N ) {
-			return $this->last_result[$y] ? array_values(get_object_vars($this->last_result[$y])) : null;
+			return $this->last_result[$y] ? array_values( get_object_vars( $this->last_result[$y] ) ) : null;
 		} else {
 			$this->print_error(/*WP_I18N_DB_GETROW_ERROR*/" \$db->get_row(string query, output type, int offset) -- Output type must be one of: OBJECT, ARRAY_A, ARRAY_N"/*/WP_I18N_DB_GETROW_ERROR*/);
 		}
@@ -1134,18 +1242,18 @@ class wpdb {
 	 *
 	 * @since 0.71
 	 *
-	 * @param string|null $query SQL query.  If null, use the result from the previous query.
+	 * @param string|null $query Optional. SQL query. If null (default), use the result from the previous query.
-	 * @param int $x Column to return.  Indexed from 0.
+	 * @param int $x Optional. Column to return. Indexed from 0.
 	 * @return array Database query result. Array indexed from 0 by SQL result row number.
 	 */
-	function get_col($query = null , $x = 0) {
+	function get_col( $query = null , $x = 0 ) {
 		if ( $query )
-			$this->query($query);
+			$this->query( $query );
 
 		$new_array = array();
 		// Extract the column values
-		for ( $i=0; $i < count($this->last_result); $i++ ) {
+		for ( $i=0; $i < count( $this->last_result ); $i++ ) {
-			$new_array[$i] = $this->get_var(null, $x, $i);
+			$new_array[$i] = $this->get_var( null, $x, $i );
 		}
 		return $new_array;
 	}
@@ -1161,11 +1269,11 @@ class wpdb {
 	 * @param string $output (optional) ane 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.
 	 * @return mixed Database query results
 	 */
-	function get_results($query = null, $output = OBJECT) {
+	function get_results( $query = null, $output = OBJECT ) {
 		$this->func_call = "\$db->get_results(\"$query\", $output)";
 
 		if ( $query )
-			$this->query($query);
+			$this->query( $query );
 		else
 			return null;
 
@@ -1206,11 +1314,11 @@ class wpdb {
 	 *
 	 * @since 0.71
 	 *
-	 * @param string $info_type one of name, table, def, max_length, not_null, primary_key, multiple_key, unique_key, numeric, blob, type, unsigned, zerofill
+	 * @param string $info_type Optional. Type one of name, table, def, max_length, not_null, primary_key, multiple_key, unique_key, numeric, blob, type, unsigned, zerofill
-	 * @param int $col_offset 0: col name. 1: which table the col's in. 2: col's max length. 3: if the col is numeric. 4: col's type
+	 * @param int $col_offset Optional. 0: col name. 1: which table the col's in. 2: col's max length. 3: if the col is numeric. 4: col's type
 	 * @return mixed Column Results
 	 */
-	function get_col_info($info_type = 'name', $col_offset = -1) {
+	function get_col_info( $info_type = 'name', $col_offset = -1 ) {
 		if ( $this->col_info ) {
 			if ( $col_offset == -1 ) {
 				$i         = 0;
@@ -1234,8 +1342,7 @@ class wpdb {
 	 * @return true
 	 */
 	function timer_start() {
-		$mtime = microtime();
+		$mtime            = explode( ' ', microtime() );
-		$mtime = explode(' ', $mtime);
 		$this->time_start = $mtime[1] + $mtime[0];
 		return true;
 	}
@@ -1248,8 +1355,7 @@ class wpdb {
 	 * @return int Total time spent on the query, in milliseconds
 	 */
 	function timer_stop() {
-		$mtime = microtime();
+		$mtime      = explode( ' ', microtime() );
-		$mtime = explode(' ', $mtime);
 		$time_end   = $mtime[1] + $mtime[0];
 		$time_total = $time_end - $this->time_start;
 		return $time_total;
@@ -1266,9 +1372,9 @@ class wpdb {
 	 * @param string $error_code (optional) A Computer readable string to identify the error.
 	 * @return false|void
 	 */
-	function bail($message, $error_code = '500') {
+	function bail( $message, $error_code = '500' ) {
 		if ( !$this->show_errors ) {
-			if ( class_exists('WP_Error') )
+			if ( class_exists( 'WP_Error' ) )
 				$this->error = new WP_Error($error_code, $message);
 			else
 				$this->error = $message;
@@ -1282,6 +1388,7 @@ class wpdb {
 	 *
 	 * @since 2.5.0
 	 * @uses $wp_version
+	 * @uses $required_mysql_version
 	 *
 	 * @return WP_Error
 	 */
@@ -1289,7 +1396,7 @@ class wpdb {
 		global $wp_version, $required_mysql_version;
 		// Make sure the server has the required MySQL version
 		if ( version_compare($this->db_version(), $required_mysql_version, '<') )
-			return new WP_Error('database_version',sprintf(__('<strong>ERROR</strong>: WordPress %1$s requires MySQL %2$s or higher'), $wp_version, $required_mysql_version));
+			return new WP_Error('database_version', sprintf( __( '<strong>ERROR</strong>: WordPress %1$s requires MySQL %2$s or higher' ), $wp_version, $required_mysql_version ));
 	}
 
 	/**
@@ -1306,21 +1413,25 @@ class wpdb {
 	}
 
 	/**
-	 * Generic function to determine if a database supports a particular feature
+	 * Determine if a database supports a particular feature
+	 *
+	 * @since 2.7
+	 * @see   wpdb::db_version()
+	 *
 	 * @param string $db_cap the feature
-	 * @param false|string|resource $dbh_or_table (not implemented) Which database to test.  False = the currently selected database, string = the database containing the specified table, resource = the database corresponding to the specified mysql resource.
+	 * @param false|string|resource $dbh_or_table. Not implemented.
+	 * 	Which database to test. False = the currently selected database, string = the database containing the specified table, resource = the database corresponding to the specified mysql resource.
 	 * @return bool
 	 */
 	function has_cap( $db_cap ) {
 		$version = $this->db_version();
 
-		switch ( strtolower( $db_cap ) ) :
+		switch ( strtolower( $db_cap ) ) {
 			case 'collation' :    // @since 2.5.0
 			case 'group_concat' : // @since 2.7
 			case 'subqueries' :   // @since 2.7
-			return version_compare($version, '4.1', '>=');
+				return version_compare( $version, '4.1', '>=' );
-			break;
+		};
-		endswitch;
 
 		return false;
 	}
@@ -1355,11 +1466,12 @@ class wpdb {
 
 	/**
 	 * The database version number
-	 * @param false|string|resource $dbh_or_table (not implemented) Which database to test.  False = the currently selected database, string = the database containing the specified table, resource = the database corresponding to the specified mysql resource.
+	 * @param false|string|resource $dbh_or_table. Not implemented.
+	 * 	Which database to test. False = the currently selected database, string = the database containing the specified table, resource = the database corresponding to the specified mysql resource.
 	 * @return false|string false on failure, version number on success
 	 */
 	function db_version() {
-		return preg_replace('/[^0-9.].*/', '', mysql_get_server_info( $this->dbh ));
+		return preg_replace( '/[^0-9.].*/', '', mysql_get_server_info( $this->dbh ) );
 	}
 }