Follow-up r104051: fix tests
[lhc/web/wiklou.git] / includes / db / Database.php
index 74fe86b..8dc2a9e 100644 (file)
@@ -47,7 +47,7 @@ interface DatabaseType {
         * Fields can be retrieved with $row->fieldname, with fields acting like
         * member variables.
         *
-        * @param $res SQL result object as returned from DatabaseBase::query(), etc.
+        * @param $res ResultWrapper|object as returned from DatabaseBase::query(), etc.
         * @return Row object
         * @throws DBUnexpectedError Thrown if the database returns an error
         */
@@ -224,6 +224,8 @@ abstract class DatabaseBase implements DatabaseType {
        protected $mDefaultBigSelects = null;
        protected $mSchemaVars = false;
 
+       protected $preparedArgs;
+
 # ------------------------------------------------------------------------------
 # Accessors
 # ------------------------------------------------------------------------------
@@ -242,7 +244,7 @@ abstract class DatabaseBase implements DatabaseType {
 
        /**
         * Boolean, controls output of large amounts of debug information.
-        * @param $debug:
+        * @param $debug bool|null
         *   - true to enable debugging
         *   - false to disable debugging
         *   - omitted or null to do nothing
@@ -290,6 +292,8 @@ abstract class DatabaseBase implements DatabaseType {
         * code should use lastErrno() and lastError() to handle the
         * situation as appropriate.
         *
+        * @param $ignoreErrors bool|null
+        *
         * @return The previous value of the flag.
         */
        function ignoreErrors( $ignoreErrors = null ) {
@@ -324,15 +328,17 @@ abstract class DatabaseBase implements DatabaseType {
         * @return The previous table prefix.
         */
        function tablePrefix( $prefix = null ) {
-               return wfSetVar( $this->mTablePrefix, $prefix, true );
+               return wfSetVar( $this->mTablePrefix, $prefix );
        }
 
        /**
         * Get properties passed down from the server info array of the load
         * balancer.
         *
-        * @param $name The entry of the info array to get, or null to get the
+        * @param $name string The entry of the info array to get, or null to get the
         *   whole array
+        *
+        * @return LoadBalancer|null
         */
        function getLBInfo( $name = null ) {
                if ( is_null( $name ) ) {
@@ -353,7 +359,6 @@ abstract class DatabaseBase implements DatabaseType {
         *
         * @param $name
         * @param $value
-        * @return void
         */
        function setLBInfo( $name, $value = null ) {
                if ( is_null( $value ) ) {
@@ -365,6 +370,8 @@ abstract class DatabaseBase implements DatabaseType {
 
        /**
         * Set lag time in seconds for a fake slave
+        *
+        * @param $lag int
         */
        function setFakeSlaveLag( $lag ) {
                $this->mFakeSlaveLag = $lag;
@@ -372,6 +379,8 @@ abstract class DatabaseBase implements DatabaseType {
 
        /**
         * Make this connection a fake master
+        *
+        * @param $enabled bool
         */
        function setFakeMaster( $enabled = true ) {
                $this->mFakeMaster = $enabled;
@@ -379,6 +388,8 @@ abstract class DatabaseBase implements DatabaseType {
 
        /**
         * Returns true if this database supports (and uses) cascading deletes
+        *
+        * @return bool
         */
        function cascadingDeletes() {
                return false;
@@ -386,6 +397,8 @@ abstract class DatabaseBase implements DatabaseType {
 
        /**
         * Returns true if this database supports (and uses) triggers (e.g. on the page table)
+        *
+        * @return bool
         */
        function cleanupTriggers() {
                return false;
@@ -394,6 +407,8 @@ abstract class DatabaseBase implements DatabaseType {
        /**
         * Returns true if this database is strict about what can be put into an IP field.
         * Specifically, it uses a NULL value instead of an empty string.
+        *
+        * @return bool
         */
        function strictIPs() {
                return false;
@@ -401,6 +416,8 @@ abstract class DatabaseBase implements DatabaseType {
 
        /**
         * Returns true if this database uses timestamps rather than integers
+        *
+        * @return bool
        */
        function realTimestamps() {
                return false;
@@ -408,6 +425,8 @@ abstract class DatabaseBase implements DatabaseType {
 
        /**
         * Returns true if this database does an implicit sort when doing GROUP BY
+        *
+        * @return bool
         */
        function implicitGroupby() {
                return true;
@@ -416,6 +435,8 @@ abstract class DatabaseBase implements DatabaseType {
        /**
         * Returns true if this database does an implicit order by when the column has an index
         * For example: SELECT page_title FROM page LIMIT 1
+        *
+        * @return bool
         */
        function implicitOrderby() {
                return true;
@@ -424,6 +445,8 @@ abstract class DatabaseBase implements DatabaseType {
        /**
         * Returns true if this database requires that SELECT DISTINCT queries require that all
           ORDER BY expressions occur in the SELECT list per the SQL92 standard
+        *
+        * @return bool
         */
        function standardSelectDistinct() {
                return true;
@@ -432,6 +455,8 @@ abstract class DatabaseBase implements DatabaseType {
        /**
         * Returns true if this database can do a native search on IP columns
         * e.g. this works as expected: .. WHERE rc_ip = '127.42.12.102/32';
+        *
+        * @return bool
         */
        function searchableIPs() {
                return false;
@@ -439,6 +464,8 @@ abstract class DatabaseBase implements DatabaseType {
 
        /**
         * Returns true if this database can use functional indexes
+        *
+        * @return bool
         */
        function functionalIndexes() {
                return false;
@@ -452,7 +479,6 @@ abstract class DatabaseBase implements DatabaseType {
                return $this->mLastQuery;
        }
 
-
        /**
         * Returns true if the connection may have been used for write queries.
         * Should return true if unsure.
@@ -508,6 +534,10 @@ abstract class DatabaseBase implements DatabaseType {
 
        /**
         * General read-only accessor
+        *
+        * @param $name string
+        *
+        * @return string
         */
        function getProperty( $name ) {
                return $this->$name;
@@ -578,6 +608,15 @@ abstract class DatabaseBase implements DatabaseType {
                }
        }
 
+       /**
+        * Called by serialize. Throw an exception when DB connection is serialized.
+        * This causes problems on some database engines because the connection is
+        * not restored on unserialize.
+        */
+       public function __sleep() {
+               throw new MWException( 'Database serialization may cause problems, since the connection is not restored on wakeup.' );
+       }
+
        /**
         * Same as new DatabaseMysql( ... ), kept for backward compatibility
         * @deprecated since 1.17
@@ -636,6 +675,9 @@ abstract class DatabaseBase implements DatabaseType {
                set_error_handler( array( $this, 'connectionErrorHandler' ) );
        }
 
+       /**
+        * @return bool|string
+        */
        protected function restoreErrorHandler() {
                restore_error_handler();
                if ( $this->htmlErrors !== false ) {
@@ -682,7 +724,7 @@ abstract class DatabaseBase implements DatabaseType {
         * The DBMS-dependent part of query()
         *
         * @param  $sql String: SQL query.
-        * @return Result object to feed to fetchObject, fetchRow, ...; or false on failure
+        * @return ResultWrapper Result object to feed to fetchObject, fetchRow, ...; or false on failure
         */
        protected abstract function doQuery( $sql );
 
@@ -690,6 +732,8 @@ abstract class DatabaseBase implements DatabaseType {
         * Determine whether a query writes to the DB.
         * Should return true if unsure.
         *
+        * @param $sql string
+        *
         * @return bool
         */
        function isWriteQuery( $sql ) {
@@ -763,7 +807,7 @@ abstract class DatabaseBase implements DatabaseType {
                        # that would delay transaction initializations to once connection
                        # is really used by application
                        $sqlstart = substr( $sql, 0, 10 ); // very much worth it, benchmark certified(tm)
-                       if ( strpos( $sqlstart, "SHOW " ) !== 0 and strpos( $sqlstart, "SET " ) !== 0 )
+                       if ( strpos( $sqlstart, "SHOW " ) !== 0 && strpos( $sqlstart, "SET " ) !== 0 )
                                $this->begin();
                }
 
@@ -861,6 +905,9 @@ abstract class DatabaseBase implements DatabaseType {
         * database classes. The query wrapper functions (select() etc.) should be
         * used instead.
         *
+        * @param $sql string
+        * @param $func string
+        *
         * @return array
         */
        function prepare( $sql, $func = 'DatabaseBase::prepare' ) {
@@ -946,7 +993,6 @@ abstract class DatabaseBase implements DatabaseType {
         *
         * @param $matches Array
         * @return String
-        * @private
         */
        function fillPreparedArg( $matches ) {
                switch( $matches[1] ) {
@@ -986,6 +1032,12 @@ abstract class DatabaseBase implements DatabaseType {
         * This function exists for historical reasons, DatabaseBase::update() has a more standard
         * calling convention and feature set
         *
+        * @param $table string
+        * @param $var
+        * @param $value
+        * @param $cond
+        * @param $fname string
+        *
         * @return bool
         */
        function set( $table, $var, $value, $cond, $fname = 'DatabaseBase::set' ) {
@@ -1011,7 +1063,7 @@ abstract class DatabaseBase implements DatabaseType {
         * @param $fname string The function name of the caller.
         * @param $options string|array The query options. See DatabaseBase::select() for details.
         *
-        * @return The value from the field, or false on failure.
+        * @return false|mixed The value from the field, or false on failure.
         */
        function selectField( $table, $var, $cond = '', $fname = 'DatabaseBase::selectField',
                $options = array() )
@@ -1147,7 +1199,6 @@ abstract class DatabaseBase implements DatabaseType {
         * @param $options Array Query options
         * @param $join_conds Array Join conditions
         *
-        *
         * @param $table string|array
         *
         * May be either an array of table names, or a single string holding a table
@@ -1192,9 +1243,6 @@ abstract class DatabaseBase implements DatabaseType {
         *     - If the value is an array, an IN(...) clause will be constructed,
         *       such that the field name may match any of the elements in the
         *       array. The elements of the array will be quoted.
-        *     - If the field name ends with "!", this is taken as a flag which
-        *       inverts the comparison, allowing NOT IN clauses to be constructed,
-        *       for example: array( 'user_id!' => array( 1, 2, 3 ) )
         *
         * Note that expressions are often DBMS-dependent in their syntax.
         * DBMS-independent wrappers are provided for constructing several types of
@@ -1314,7 +1362,7 @@ abstract class DatabaseBase implements DatabaseType {
                                $from = ' FROM ' . implode( ',', $this->tableNamesWithAlias( $table ) );
                        }
                } elseif ( $table != '' ) {
-                       if ( $table { 0 } == ' ' ) {
+                       if ( $table[0] == ' ' ) {
                                $from = ' FROM ' . $table;
                        } else {
                                $from = ' FROM ' . $this->tableName( $table );
@@ -1394,8 +1442,8 @@ abstract class DatabaseBase implements DatabaseType {
         * Takes the same arguments as DatabaseBase::select().
         *
         * @param $table String: table name
-        * @param $vars Array: unused
-        * @param $conds Array: filters on the table
+        * @param Array|string $vars : unused
+        * @param Array|string $conds : filters on the table
         * @param $fname String: function name for profiling
         * @param $options Array: options for select
         * @return Integer: row count
@@ -1418,7 +1466,9 @@ abstract class DatabaseBase implements DatabaseType {
         * Removes most variables from an SQL query and replaces them with X or N for numbers.
         * It's only slightly flawed. Don't use for anything important.
         *
-        * @param $sql String: A SQL Query
+        * @param $sql String A SQL Query
+        *
+        * @return string
         */
        static function generalizeSQL( $sql ) {
                # This does the same as the regexp below would do, but in such a way
@@ -1459,6 +1509,10 @@ abstract class DatabaseBase implements DatabaseType {
         * Usually throws a DBQueryError on failure
         * If errors are explicitly ignored, returns NULL on failure
         *
+        * @param $table
+        * @param $index
+        * @param $fname string
+        *
         * @return bool|null
         */
        function indexExists( $table, $index, $fname = 'DatabaseBase::indexExists' ) {
@@ -1473,20 +1527,22 @@ abstract class DatabaseBase implements DatabaseType {
        /**
         * Query whether a given table exists
         *
-        * @string table
+        * @param $table string
+        * @param $fname string
         *
         * @return bool
         */
-       function tableExists( $table ) {
+       function tableExists( $table, $fname = __METHOD__ ) {
                $table = $this->tableName( $table );
                $old = $this->ignoreErrors( true );
-               $res = $this->query( "SELECT 1 FROM $table LIMIT 1", __METHOD__ );
+               $res = $this->query( "SELECT 1 FROM $table LIMIT 1", $fname );
                $this->ignoreErrors( $old );
 
                return (bool)$res;
        }
 
        /**
+        * @todo document
         * mysql_field_type() wrapper
         */
        function fieldType( $res, $index ) {
@@ -1552,7 +1608,7 @@ abstract class DatabaseBase implements DatabaseType {
         *
         * @param $table   String Table name. This will be passed through
         *                 DatabaseBase::tableName().
-        * @param $a       Array of rows to insert
+        * @param $a       Array of rows to insert
         * @param $fname   String Calling function name (use __METHOD__) for logs/profiling
         * @param $options Array of options
         *
@@ -1627,32 +1683,36 @@ abstract class DatabaseBase implements DatabaseType {
        /**
         * UPDATE wrapper. Takes a condition array and a SET array.
         *
-        * @param $table  String name of the table to UPDATE. This will be passed through
+        * @param $table  String|array name of the table to UPDATE. This will be passed through
         *                DatabaseBase::tableName().
         *
-        * @param $values Array An array of values to SET. For each array element,
+        * @param $values Array An array of values to SET. For each array element,
         *                the key gives the field name, and the value gives the data
         *                to set that field to. The data will be quoted by
         *                DatabaseBase::addQuotes().
         *
-        * @param $conds  Array:  An array of conditions (WHERE). See
+        * @param $conds  Array  An array of conditions (WHERE). See
         *                DatabaseBase::select() for the details of the format of
         *                condition arrays. Use '*' to update all rows.
         *
-        * @param $fname  String: The function name of the caller (from __METHOD__),
+        * @param $fname  String The function name of the caller (from __METHOD__),
         *                for logging and profiling.
         *
-        * @param $options Array: An array of UPDATE options, can be:
+        * @param $options Array An array of UPDATE options, can be:
         *                   - IGNORE: Ignore unique key conflicts
         *                   - LOW_PRIORITY: MySQL-specific, see MySQL manual.
         * @return Boolean
         */
        function update( $table, $values, $conds, $fname = 'DatabaseBase::update', $options = array() ) {
-               $table = $this->tableName( $table );
+               if ( is_array( $table ) ) {
+                       $table =  implode( ',', array_map( array( $this, 'tableName' ), $table ) );
+               } else {
+                       $table = $this->tableName( $table );
+               }
                $opts = $this->makeUpdateOptions( $options );
                $sql = "UPDATE $opts $table SET " . $this->makeList( $values, LIST_SET );
 
-               if ( $conds != '*' ) {
+               if ( $conds !== array() && $conds !== '*' ) {
                        $sql .= " WHERE " . $this->makeList( $conds, LIST_AND );
                }
 
@@ -1662,7 +1722,7 @@ abstract class DatabaseBase implements DatabaseType {
        /**
         * Makes an encoded list of strings from an array
         * @param $a Array containing the data
-        * @param $mode:
+        * @param $mode int Constant
         *      - LIST_COMMA:          comma separated, no field names
         *      - LIST_AND:            ANDed WHERE clause (without the WHERE). See
         *        the documentation for $conds in DatabaseBase::select().
@@ -1670,15 +1730,6 @@ abstract class DatabaseBase implements DatabaseType {
         *      - LIST_SET:            comma separated with field names, like a SET clause
         *      - LIST_NAMES:          comma separated field names
         *
-        * In LIST_AND or LIST_OR modes, you can suffix a field with an exclamation
-        * mark to generate a 'NOT IN' structure.
-        *
-        * Example:
-        *  $db->makeList( array( 'field!' => array( 1,2,3 ) );
-        *
-        *  outputs:
-        *    'field' NOT IN ('1', '2', '3' );
-
         * @return string
         */
        function makeList( $a, $mode = LIST_COMMA ) {
@@ -1702,13 +1753,6 @@ abstract class DatabaseBase implements DatabaseType {
                                $first = false;
                        }
 
-                       // Support 'NOT IN' by suffixing fieldname with an exclamation mark
-                       $not = false;
-                       if( substr($field,-1) == '!' ) {
-                               $not = true;
-                               $field = substr($field, 0, -1 );
-                       }
-
                        if ( ( $mode == LIST_AND || $mode == LIST_OR ) && is_numeric( $field ) ) {
                                $list .= "($value)";
                        } elseif ( ( $mode == LIST_SET ) && is_numeric( $field ) ) {
@@ -1721,19 +1765,13 @@ abstract class DatabaseBase implements DatabaseType {
                                        // Don't necessarily assume the single key is 0; we don't
                                        // enforce linear numeric ordering on other arrays here.
                                        $value = array_values( $value );
-
-                                       $operator = $not ? ' != ' : ' = ';
-                                       $list .= $field . $operator . $this->addQuotes( $value[0] );
+                                       $list .= $field . " = " . $this->addQuotes( $value[0] );
                                } else {
-                                       $operator = $not ? ' NOT IN ' : ' IN ';
-                                       $list .= $field . $operator . "(" . $this->makeList( $value ) . ")";
+                                       $list .= $field . " IN (" . $this->makeList( $value ) . ") ";
                                }
                        } elseif ( $value === null ) {
                                if ( $mode == LIST_AND || $mode == LIST_OR ) {
                                        $list .= "$field IS ";
-                                       if ( $not ) {
-                                               $list .= "NOT ";
-                                       }
                                } elseif ( $mode == LIST_SET ) {
                                        $list .= "$field = ";
                                }
@@ -1812,6 +1850,9 @@ abstract class DatabaseBase implements DatabaseType {
         * Change the current database
         *
         * @todo Explain what exactly will fail if this is not overridden.
+        *
+        * @param $db
+        *
         * @return bool Success or failure
         */
        function selectDB( $db ) {
@@ -1847,11 +1888,13 @@ abstract class DatabaseBase implements DatabaseType {
         * when calling query() directly.
         *
         * @param $name String: database table name
-        * @param $quoted Boolean: Automatically pass the table name through
-        *          addIdentifierQuotes() so that it can be used in a query.
+        * @param $format String One of:
+        *   quoted - Automatically pass the table name through addIdentifierQuotes()
+        *            so that it can be used in a query.
+        *   raw - Do not add identifier quotes to the table name
         * @return String: full database name
         */
-       function tableName( $name, $quoted = true ) {
+       function tableName( $name, $format = 'quoted' ) {
                global $wgSharedDB, $wgSharedPrefix, $wgSharedTables;
                # Skip the entire process when we have a string quoted on both ends.
                # Note that we check the end so that we will still quote any use of
@@ -1877,12 +1920,18 @@ abstract class DatabaseBase implements DatabaseType {
                # the correct table.
                $dbDetails = array_reverse( explode( '.', $name, 2 ) );
                if ( isset( $dbDetails[1] ) ) {
-                       @list( $table, $database ) = $dbDetails;
+                       list( $table, $database ) = $dbDetails;
                } else {
-                       @list( $table ) = $dbDetails;
+                       list( $table ) = $dbDetails;
                }
                $prefix = $this->mTablePrefix; # Default prefix
 
+               # A database name has been specified in input. We don't want any
+               # prefixes added.
+               if ( isset( $database ) ) {
+                       $prefix = '';
+               }
+
                # Note that we use the long format because php will complain in in_array if
                # the input is not an array, and will complain in is_array if it is not set.
                if ( !isset( $database ) # Don't use shared database if pre selected.
@@ -1897,12 +1946,11 @@ abstract class DatabaseBase implements DatabaseType {
 
                # Quote the $database and $table and apply the prefix if not quoted.
                if ( isset( $database ) ) {
-                       $database = ( !$quoted || $this->isQuotedIdentifier( $database ) ? $database : $this->addIdentifierQuotes( $database ) );
-                       $prefix = '';
+                       $database = ( $format == 'quoted' || $this->isQuotedIdentifier( $database ) ? $database : $this->addIdentifierQuotes( $database ) );
                }
 
                $table = "{$prefix}{$table}";
-               if ( $quoted && !$this->isQuotedIdentifier( $table ) ) {
+               if ( $format == 'quoted' && !$this->isQuotedIdentifier( $table ) ) {
                        $table = $this->addIdentifierQuotes( "{$table}" );
                }
 
@@ -1920,6 +1968,8 @@ abstract class DatabaseBase implements DatabaseType {
         * extract($dbr->tableNames('user','watchlist'));
         * $sql = "SELECT wl_namespace,wl_title FROM $watchlist,$user
         *         WHERE wl_user=user_id AND wl_user=$nameWithQuotes";
+        *
+        * @return array
         */
        public function tableNames() {
                $inArray = func_get_args();
@@ -1940,6 +1990,8 @@ abstract class DatabaseBase implements DatabaseType {
         * list( $user, $watchlist ) = $dbr->tableNamesN('user','watchlist');
         * $sql = "SELECT wl_namespace,wl_title FROM $watchlist,$user
         *         WHERE wl_user=user_id AND wl_user=$nameWithQuotes";
+        *
+        * @return array
         */
        public function tableNamesN() {
                $inArray = func_get_args();
@@ -1957,7 +2009,7 @@ abstract class DatabaseBase implements DatabaseType {
         * e.g. tableName AS newTableName
         *
         * @param $name string Table name, see tableName()
-        * @param $alias string Alias (optional)
+        * @param $alias string|bool Alias (optional)
         * @return string SQL name for aliased table. Will not alias a table to its own name
         */
        public function tableNameWithAlias( $name, $alias = false ) {
@@ -1989,9 +2041,9 @@ abstract class DatabaseBase implements DatabaseType {
         * Get the aliased table name clause for a FROM clause
         * which might have a JOIN and/or USE INDEX clause
         *
-        * @param $tables array( [alias] => table )
-        * @param $use_index array() Same as for select()
-        * @param $join_conds array() Same as for select()
+        * @param $tables array ( [alias] => table )
+        * @param $use_index array Same as for select()
+        * @param $join_conds array Same as for select()
         * @return string
         */
        protected function tableNamesWithUseIndexOrJOIN(
@@ -2094,6 +2146,8 @@ abstract class DatabaseBase implements DatabaseType {
         * Since MySQL is the odd one out here the double quotes are our generic
         * and we implement backticks in DatabaseMysql.
         *
+        * @param $s string
+        *
         * @return string
         */
        public function addIdentifierQuotes( $s ) {
@@ -2118,6 +2172,8 @@ abstract class DatabaseBase implements DatabaseType {
         * was renamed to addIdentifierQuotes.
         * @deprecated since 1.18 use addIdentifierQuotes
         *
+        * @param $s string
+        *
         * @return string
         */
        function quote_ident( $s ) {
@@ -2130,12 +2186,20 @@ abstract class DatabaseBase implements DatabaseType {
         * WARNING: you should almost never use this function directly,
         * instead use buildLike() that escapes everything automatically
         * @deprecated since 1.17, warnings in 1.17, removed in ???
+        *
+        * @param $s string
+        *
+        * @return string
         */
        public function escapeLike( $s ) {
                wfDeprecated( __METHOD__ );
                return $this->escapeLikeInternal( $s );
        }
 
+       /**
+        * @param $s string
+        * @return string
+        */
        protected function escapeLikeInternal( $s ) {
                $s = str_replace( '\\', '\\\\', $s );
                $s = $this->strencode( $s );
@@ -2188,7 +2252,7 @@ abstract class DatabaseBase implements DatabaseType {
        /**
         * Returns a token for buildLike() that denotes a '%' to be used in a LIKE query
         *
-        * @rerturn LikeMatch
+        * @return LikeMatch
         */
        function anyString() {
                return new LikeMatch( '%' );
@@ -2198,6 +2262,10 @@ abstract class DatabaseBase implements DatabaseType {
         * Returns an appropriately quoted sequence value for inserting a new row.
         * MySQL has autoincrement fields, so this is just NULL. But the PostgreSQL
         * subclass will return an integer, and save the value for insertId()
+        *
+        * Any implementation of this function should *not* involve reusing
+        * sequence numbers created for rolled-back transactions.
+        * See http://bugs.mysql.com/bug.php?id=30767 for details.
         */
        function nextSequenceValue( $seqName ) {
                return null;
@@ -2230,14 +2298,11 @@ abstract class DatabaseBase implements DatabaseType {
         * to collide. However if you do this, you run the risk of encountering
         * errors which wouldn't have occurred in MySQL.
         *
-        * @param $rows Can be either a single row to insert, or multiple rows,
+        * @param $table String: The table to replace the row(s) in.
+        * @param $rows array Can be either a single row to insert, or multiple rows,
         *    in the same format as for DatabaseBase::insert()
-        * @param $uniqueIndexes is an array of indexes. Each element may be either
+        * @param $uniqueIndexes array is an array of indexes. Each element may be either
         *    a field name or an array of field names
-        *
-        * @param $table String: The table to replace the row(s) in.
-        * @param $uniqueIndexes Array: An associative array of indexes
-        * @param $rows Array: Array of rows to replace
         * @param $fname String: Calling function name (use __METHOD__) for logs/profiling
         */
        function replace( $table, $uniqueIndexes, $rows, $fname = 'DatabaseBase::replace' ) {
@@ -2294,6 +2359,8 @@ abstract class DatabaseBase implements DatabaseType {
         * @param $table Table name
         * @param $rows Rows to insert
         * @param $fname Caller function name
+        *
+        * @return ResultWrapper
         */
        protected function nativeReplace( $table, $rows, $fname ) {
                $table = $this->tableName( $table );
@@ -2360,6 +2427,11 @@ abstract class DatabaseBase implements DatabaseType {
 
        /**
         * Returns the size of a text field, or -1 for "unlimited"
+        *
+        * @param $table string
+        * @param $field string
+        *
+        * @return int
         */
        function textFieldSize( $table, $field ) {
                $table = $this->tableName( $table );
@@ -2419,24 +2491,24 @@ abstract class DatabaseBase implements DatabaseType {
         * INSERT SELECT wrapper. Takes data from a SELECT query and inserts it
         * into another table.
         *
-        * @param $destTable The table name to insert into
-        * @param $srcTable May be either a table name, or an array of table names
+        * @param $destTable string The table name to insert into
+        * @param $srcTable string|array May be either a table name, or an array of table names
         *    to include in a join.
         *
-        * @param $varMap must be an associative array of the form
+        * @param $varMap array must be an associative array of the form
         *    array( 'dest1' => 'source1', ...). Source items may be literals
         *    rather than field names, but strings should be quoted with
         *    DatabaseBase::addQuotes()
         *
-        * @param $conds Condition array. See $conds in DatabaseBase::select() for
+        * @param $conds array Condition array. See $conds in DatabaseBase::select() for
         *    the details of the format of condition arrays. May be "*" to copy the
         *    whole table.
         *
-        * @param $fname The function name of the caller, from __METHOD__
+        * @param $fname string The function name of the caller, from __METHOD__
         *
-        * @param $insertOptions Options for the INSERT part of the query, see
+        * @param $insertOptions array Options for the INSERT part of the query, see
         *    DatabaseBase::insert() for details.
-        * @param $selectOptions Options for the SELECT part of the query, see
+        * @param $selectOptions array Options for the SELECT part of the query, see
         *    DatabaseBase::select() for details.
         *
         * @return ResultWrapper
@@ -2468,7 +2540,10 @@ abstract class DatabaseBase implements DatabaseType {
                        " FROM $srcTable $useIndex ";
 
                if ( $conds != '*' ) {
-                       $sql .= ' WHERE ' . $this->makeList( $conds, LIST_AND );
+                       if ( is_array( $conds ) ) {
+                               $conds = $this->makeList( $conds, LIST_AND );
+                       }
+                       $sql .= " WHERE $conds";
                }
 
                $sql .= " $tailOpts";
@@ -2490,9 +2565,9 @@ abstract class DatabaseBase implements DatabaseType {
         * The version provided by default works in MySQL and SQLite.  It will very
         * likely need to be overridden for most other DBMSes.
         *
-        * @param $sql String: SQL query we will append the limit too
-        * @param $limit Integer: the SQL limit
-        * @param $offset Integer the SQL offset (default false)
+        * @param $sql String SQL query we will append the limit too
+        * @param $limit Integer the SQL limit
+        * @param $offset Integer|false the SQL offset (default false)
         *
         * @return string
         */
@@ -2506,6 +2581,11 @@ abstract class DatabaseBase implements DatabaseType {
                                . "{$limit} ";
        }
 
+       /**
+        * @param $sql
+        * @param $num
+        * @return string
+        */
        function limitResultForUpdate( $sql, $num ) {
                return $this->limitResult( $sql, $num, 0 );
        }
@@ -2605,6 +2685,8 @@ abstract class DatabaseBase implements DatabaseType {
         * Returns whatever the callback function returned on its successful,
         * iteration, or false on error, for example if the retry limit was
         * reached.
+        *
+        * @return bool
         */
        function deadlockLoop() {
                $myFname = 'DatabaseBase::deadlockLoop';
@@ -2720,6 +2802,8 @@ abstract class DatabaseBase implements DatabaseType {
 
        /**
         * Begin a transaction, committing any previously open transaction
+        *
+        * @param $fname string
         */
        function begin( $fname = 'DatabaseBase::begin' ) {
                $this->query( 'BEGIN', $fname );
@@ -2728,6 +2812,8 @@ abstract class DatabaseBase implements DatabaseType {
 
        /**
         * End a transaction
+        *
+        * @param $fname string
         */
        function commit( $fname = 'DatabaseBase::commit' ) {
                if ( $this->mTrxLevel ) {
@@ -2739,6 +2825,8 @@ abstract class DatabaseBase implements DatabaseType {
        /**
         * Rollback a transaction.
         * No-op on non-transactional databases.
+        *
+        * @param $fname string
         */
        function rollback( $fname = 'DatabaseBase::rollback' ) {
                if ( $this->mTrxLevel ) {
@@ -2785,6 +2873,8 @@ abstract class DatabaseBase implements DatabaseType {
         * The result is unquoted, and needs to be passed through addQuotes()
         * before it can be included in raw SQL.
         *
+        * @param $ts string|int
+        *
         * @return string
         */
        function timestamp( $ts = 0 ) {
@@ -2800,6 +2890,8 @@ abstract class DatabaseBase implements DatabaseType {
         * The result is unquoted, and needs to be passed through addQuotes()
         * before it can be included in raw SQL.
         *
+        * @param $ts string|int
+        *
         * @return string
         */
        function timestampOrNull( $ts = null ) {
@@ -2820,6 +2912,10 @@ abstract class DatabaseBase implements DatabaseType {
         * a wrapper. Nowadays, raw database objects are never exposed to external
         * callers, so this is unnecessary in external code. For compatibility with
         * old code, ResultWrapper objects are passed through unaltered.
+        *
+        * @param $result bool|ResultWrapper
+        *
+        * @param bool|ResultWrapper
         */
        function resultObject( $result ) {
                if ( empty( $result ) ) {
@@ -2836,6 +2932,11 @@ abstract class DatabaseBase implements DatabaseType {
 
        /**
         * Return aggregated value alias
+        *
+        * @param $valuedata
+        * @param $valuename string
+        *
+        * @return string
         */
        function aggregateValue ( $valuedata, $valuename = 'value' ) {
                return $valuename;
@@ -2852,8 +2953,12 @@ abstract class DatabaseBase implements DatabaseType {
        }
 
        /**
-        * Get slave lag.
-        * Currently supported only by MySQL
+        * Get slave lag. Currently supported only by MySQL.
+        *
+        * Note that this function will generate a fatal error on many
+        * installations. Most callers should use LoadBalancer::safeGetLag()
+        * instead.
+        *
         * @return Database replication lag in seconds
         */
        function getLag() {
@@ -2863,7 +2968,7 @@ abstract class DatabaseBase implements DatabaseType {
        /**
         * Return the maximum number of items allowed in a list, or 0 for unlimited.
         *
-        * return int
+        * @return int
         */
        function maxListLen() {
                return 0;
@@ -2996,7 +3101,7 @@ abstract class DatabaseBase implements DatabaseType {
                                continue;
                        }
 
-                       if ( '-' == $line { 0 } && '-' == $line { 1 } ) {
+                       if ( '-' == $line[0] && '-' == $line[1] ) {
                                continue;
                        }
 
@@ -3011,7 +3116,7 @@ abstract class DatabaseBase implements DatabaseType {
                                }
                        }
                        elseif ( !$dollarquote ) {
-                               if ( ';' == $line { $sl } && ( $sl < 2 || ';' != $line { $sl - 1 } ) ) {
+                               if ( ';' == $line[$sl] && ( $sl < 2 || ';' != $line[$sl - 1] ) ) {
                                        $done = true;
                                        $line = substr( $line, 0, $sl );
                                }
@@ -3099,6 +3204,8 @@ abstract class DatabaseBase implements DatabaseType {
        /**
         * Get schema variables. If none have been set via setSchemaVars(), then
         * use some defaults from the current object.
+        *
+        * @return array
         */
        protected function getSchemaVars() {
                if ( $this->mSchemaVars ) {
@@ -3210,9 +3317,10 @@ abstract class DatabaseBase implements DatabaseType {
         * @param $tableName string
         * @param $fName string
         * @return bool|ResultWrapper
+        * @since 1.18
         */
        public function dropTable( $tableName, $fName = 'DatabaseBase::dropTable' ) {
-               if( !$this->tableExists( $tableName ) ) {
+               if( !$this->tableExists( $tableName, $fName ) ) {
                        return false;
                }
                $sql = "DROP TABLE " . $this->tableName( $tableName );