Index: includes/database/database.inc
===================================================================
RCS file: /cvs/drupal/drupal/includes/database/database.inc,v
retrieving revision 1.98
diff -u -r1.98 database.inc
--- includes/database/database.inc	1 Mar 2010 11:30:37 -0000	1.98
+++ includes/database/database.inc	2 Mar 2010 00:22:02 -0000
@@ -63,7 +63,7 @@
  *
  * Named placeholders begin with a colon followed by a unique string. Example:
  * @code
- * SELECT nid, title FROM {node} WHERE uid=:uid
+ *   SELECT nid, title FROM {node} WHERE uid=:uid;
  * @endcode
  *
  * ":uid" is a placeholder that will be replaced with a literal value when
@@ -75,7 +75,7 @@
  *
  * Unnamed placeholders are simply a question mark. Example:
  * @code
- * SELECT nid, title FROM {node} WHERE uid=?
+ *   SELECT nid, title FROM {node} WHERE uid=?;
  * @endcode
  *
  * In this case, the array of arguments must be an indexed array of values to
@@ -86,13 +86,13 @@
  * value, not the query itself. Thus, the following is incorrect:
  *
  * @code
- * SELECT nid, title FROM {node} WHERE title LIKE :title%
+ *   SELECT nid, title FROM {node} WHERE title LIKE :title%;
  * @endcode
  *
  * It should instead read:
  *
  * @code
- * SELECT nid, title FROM {node} WHERE title LIKE :title
+ *   SELECT nid, title FROM {node} WHERE title LIKE :title;
  * @endcode
  *
  * and the value for :title should include a % as appropriate. Again, note the
@@ -105,14 +105,15 @@
  *
  * INSERT, UPDATE, and DELETE queries need special care in order to behave
  * consistently across all different databases. Therefore, they use a special
- * object-oriented API for defining a query structurally. For example, rather than
+ * object-oriented API for defining a query structurally.
+ * For example, rather than
  * @code
- * INSERT INTO node (nid, title, body) VALUES (1, 'my title', 'my body')
+ *   INSERT INTO node (nid, title, body) VALUES (1, 'my title', 'my body');
  * @endcode
  * one would instead write:
  * @code
- * $fields = array('nid' => 1, 'title' => 'my title', 'body' => 'my body');
- * db_insert('node')->fields($fields)->execute();
+ *   $fields = array('nid' => 1, 'title' => 'my title', 'body' => 'my body');
+ *   db_insert('node')->fields($fields)->execute();
  * @endcode
  * This method allows databases that need special data type handling to do so,
  * while also allowing optimizations such as multi-insert queries. UPDATE and
@@ -400,6 +401,7 @@
    *
    * @param $sql
    *   A string containing a partial or entire SQL query.
+   *
    * @return
    *   The properly-prefixed string.
    */
@@ -436,6 +438,7 @@
    * @param $query
    *   The query string as SQL, with curly-braces surrounding the
    *   table names.
+   *
    * @return DatabaseStatementInterface
    *   A PDO prepared statement ready for its execute() method.
    */
@@ -505,6 +508,7 @@
    *   The table name to use for the sequence.
    * @param $field
    *   The field name to use for the sequence.
+   *
    * @return
    *   A table prefix-parsed string for the sequence name.
    */
@@ -536,6 +540,7 @@
    * @param $options
    *   An associative array of options to control how the query is run. See
    *   the documentation for DatabaseConnection::defaultOptions() for details.
+   *
    * @return DatabaseStatementInterface
    *   This method will return one of: the executed statement, the number of
    *   rows affected by the query (not the number matched), or the generated
@@ -607,6 +612,7 @@
    *   The query string to modify.
    * @param $args
    *   The arguments for the query.
+   *
    * @return
    *   TRUE if the query was modified, FALSE otherwise.
    */
@@ -651,7 +657,6 @@
   /**
    * Prepare and return a SELECT query object with the specified ID.
    *
-   * @see SelectQuery
    * @param $table
    *   The base table for this query, that is, the first table in the FROM
    *   clause. This table will also be used as the "base" table for query_alter
@@ -660,8 +665,11 @@
    *   The alias of the base table of this query.
    * @param $options
    *   An array of options on the query.
+   *
    * @return SelectQueryInterface
    *   A new SelectQuery object.
+   *
+   * @see SelectQuery
    */
   public function select($table, $alias = NULL, array $options = array()) {
     if (empty($this->selectClass)) {
@@ -681,11 +689,13 @@
   /**
    * Prepare and return an INSERT query object with the specified ID.
    *
-   * @see InsertQuery
    * @param $options
    *   An array of options on the query.
+   *
    * @return InsertQuery
    *   A new InsertQuery object.
+   *
+   * @see InsertQuery
    */
   public function insert($table, array $options = array()) {
     if (empty($this->insertClass)) {
@@ -701,11 +711,13 @@
   /**
    * Prepare and return a MERGE query object with the specified ID.
    *
-   * @see MergeQuery
    * @param $options
    *   An array of options on the query.
+   *
    * @return MergeQuery
    *   A new MergeQuery object.
+   *
+   * @see MergeQuery
    */
   public function merge($table, array $options = array()) {
     if (empty($this->mergeClass)) {
@@ -722,11 +734,13 @@
   /**
    * Prepare and return an UPDATE query object with the specified ID.
    *
-   * @see UpdateQuery
    * @param $options
    *   An array of options on the query.
+   *
    * @return UpdateQuery
    *   A new UpdateQuery object.
+   *
+   * @see UpdateQuery
    */
   public function update($table, array $options = array()) {
     if (empty($this->updateClass)) {
@@ -742,11 +756,13 @@
   /**
    * Prepare and return a DELETE query object with the specified ID.
    *
-   * @see DeleteQuery
    * @param $options
    *   An array of options on the query.
+   *
    * @return DeleteQuery
    *   A new DeleteQuery object.
+   *
+   * @see DeleteQuery
    */
   public function delete($table, array $options = array()) {
     if (empty($this->deleteClass)) {
@@ -762,11 +778,13 @@
   /**
    * Prepare and return a TRUNCATE query object.
    *
-   * @see TruncateQuery
    * @param $options
    *   An array of options on the query.
+   *
    * @return TruncateQuery
    *   A new DeleteQuery object.
+   *
+   * @see TruncateQuery
    */
   public function truncate($table, array $options = array()) {
     if (empty($this->truncateClass)) {
@@ -820,10 +838,10 @@
    * For example, the following does a case-insensitive query for all rows whose
    * name starts with $prefix:
    * @code
-   * $result = db_query(
-   *   'SELECT * FROM person WHERE name LIKE :pattern',
-   *   array(':pattern' => db_like($prefix) . '%')
-   * );
+   *   $result = db_query(
+   *     'SELECT * FROM person WHERE name LIKE :pattern',
+   *     array(':pattern' => db_like($prefix) . '%')
+   *   );
    * @endcode
    *
    * Backslash is defined as escape character for LIKE patterns in
@@ -831,6 +849,7 @@
    *
    * @param $string
    *   The string to escape.
+   *
    * @return
    *   The escaped string.
    */
@@ -1030,6 +1049,7 @@
    *   The maximum number of result rows to return.
    * @param $options
    *   An array of options on the query.
+   *
    * @return DatabaseStatementInterface
    *   A database query result resource, or NULL if the query was not executed
    *   correctly.
@@ -1065,6 +1085,7 @@
    * @param $options
    *   An associative array of options to control how the query is run. See
    *   the documentation for DatabaseConnection::defaultOptions() for details.
+   *
    * @return
    *   The name of the temporary table.
    */
@@ -1117,11 +1138,13 @@
    * overridable lookup function. Database connections should define only
    * those operators they wish to be handled differently than the default.
    *
-   * @see DatabaseCondition::compile()
    * @param $operator
    *   The condition operator, such as "IN", "BETWEEN", etc. Case-sensitive.
+   *
    * @return
    *   The extra handling directives for the specified operator, or NULL.
+   *
+   * @see DatabaseCondition::compile()
    */
   abstract public function mapConditionOperator($operator);
 
@@ -1151,6 +1174,7 @@
    *   After a database import, it might be that the sequences table is behind,
    *   so by passing in the maximum existing id, it can be assured that we
    *   never issue the same id.
+   *
    * @return
    *   An integer number larger than any number returned by earlier calls and
    *   also larger than the $existing_id if one was passed in.
@@ -1164,7 +1188,6 @@
  * This class is uninstantiatable and un-extendable. It acts to encapsulate
  * all control and shepherding of database connections into a single location
  * without the use of globals.
- *
  */
 abstract class Database {
 
@@ -1248,15 +1271,17 @@
   /**
    * Start logging a given logging key on the specified connection.
    *
-   * @see DatabaseLog
    * @param $logging_key
    *   The logging key to log.
    * @param $key
    *   The database connection key for which we want to log.
+   *
    * @return DatabaseLog
    *   The query log object. Note that the log object does support richer
    *   methods than the few exposed through the Database class, so in some
    *   cases it may be desirable to access it directly.
+   *
+   * @see DatabaseLog
    */
   final public static function startLog($logging_key, $key = 'default') {
     if (empty(self::$logs[$key])) {
@@ -1278,13 +1303,14 @@
   /**
    * Set a logging callback for notices and errors.
    *
-   * @see watchdog()
    * @param $logging_callback
    *   The function to use as the logging callback.
    * @param $logging_default_severity
    *   The default severity level to use for logged messages.
    * @param $logging_error_severity
    *   The severity level to use for logging error messages.
+   *
+   * @see watchdog()
    */
   final public static function setLoggingCallback($callback, $default_severity, $error_severity) {
     self::$logging_callback = array(
@@ -1314,13 +1340,15 @@
    * it again (which does nothing to an open log key) and call methods on it as
    * desired.
    *
-   * @see DatabaseLog
    * @param $logging_key
    *   The logging key to log.
    * @param $key
    *   The database connection key for which we want to log.
-   * @return array
+   *
+   * @return Array
    *   The query log for the specified logging key and connection.
+   *
+   * @see DatabaseLog
    */
   final public static function getLog($logging_key, $key = 'default') {
     if (empty(self::$logs[$key])) {
@@ -1338,6 +1366,7 @@
    *   The database target name.
    * @param $key
    *   The database connection key. Defaults to NULL which means the active key.
+   *
    * @return DatabaseConnection
    *   The corresponding connection object.
    */
@@ -1572,7 +1601,8 @@
 }
 
 /**
- * Exception to throw when popTransaction() is called when no transaction is active.
+ * Exception to throw when popTransaction() is called when no transaction is
+ * active.
  */
 class NoActiveTransactionException extends Exception { }
 
@@ -1620,8 +1650,9 @@
  * commands, allowing user-space code to proceed normally. The only difference
  * is that rollbacks won't actually do anything.
  *
- * In the vast majority of cases, you should not instantiate this class directly.
- * Instead, call ->startTransaction(), from the appropriate connection object.
+ * In the vast majority of cases, you should not instantiate this class
+ * directly. Instead, call ->startTransaction(), from the appropriate connection
+ * object.
  */
 class DatabaseTransaction {
 
@@ -1696,14 +1727,14 @@
  *
  * Child implementations should either extend PDOStatement:
  * @code
- * class DatabaseStatement_oracle extends PDOStatement implements DatabaseStatementInterface {}
+ *   class DatabaseStatement_oracle extends PDOStatement implements DatabaseStatementInterface {}
  * @endcode
  *
  * …or implement their own class, but in that case they will also have to
  * implement the Iterator or IteratorArray interfaces before
  * DatabaseStatementInterface:
  * @code
- * class DatabaseStatement_oracle implements Iterator, DatabaseStatementInterface {}
+ *   class DatabaseStatement_oracle implements Iterator, DatabaseStatementInterface {}
  * @endcode
  */
 interface DatabaseStatementInterface extends Traversable {
@@ -1716,6 +1747,7 @@
    *   the SQL statement being executed.
    * @param $options
    *   An array of options for this query.
+   *
    * @return
    *   TRUE on success, or FALSE on failure.
    */
@@ -1770,6 +1802,7 @@
    *   Not implemented in all database drivers, don't use.
    * @param $cursor_offset
    *   Not implemented in all database drivers, don't use.
+   *
    * @return
    *   A result, formatted according to $mode.
    */
@@ -1780,6 +1813,7 @@
    *
    * @param $index
    *   The numeric index of the field to return. Defaults to the first field.
+   *
    * @return
    *   A single field from the next record.
    */
@@ -1814,6 +1848,7 @@
    *   If $mode is PDO::FETCH_COLUMN, the index of the column to fetch.
    * @param $constructor_arguments
    *   If $mode is PDO::FETCH_CLASS, the arguments to pass to the constructor.
+   *
    * @return
    *   An array of results.
    */
@@ -1826,6 +1861,7 @@
    *
    * @param $index
    *   The index of the column number to fetch.
+   *
    * @return
    *   An indexed array.
    */
@@ -1845,6 +1881,7 @@
    *   The numeric index of the field to use as the array key.
    * @param $value_index
    *   The numeric index of the field to use as the array value.
+   *
    * @return
    *   An associative array.
    */
@@ -1865,6 +1902,7 @@
    *   The fetchmode to use. If set to PDO::FETCH_ASSOC, PDO::FETCH_NUM, or
    *   PDO::FETCH_BOTH the returned value with be an array of arrays. For any
    *   other value it will be an array of objects.
+   *
    * @return
    *   An associative array.
    */
@@ -2057,6 +2095,7 @@
 
 /**
  * The following utility functions are simply convenience wrappers.
+ *
  * They should never, ever have any database-specific code in them.
  */
 
@@ -2067,7 +2106,6 @@
  * be handled via the appropriate query builder factory. Use this function for
  * SELECT queries that do not require a query builder.
  *
- * @see DatabaseConnection::defaultOptions()
  * @param $query
  *   The prepared statement query to run. Although it will accept both named and
  *   unnamed placeholders, named placeholders are strongly preferred as they are
@@ -2079,8 +2117,11 @@
  *   the order of placeholders in the query string.
  * @param $options
  *   An array of options to control how the query operates.
+ *
  * @return DatabaseStatementInterface
  *   A prepared statement object, already executed.
+ *
+ * @see DatabaseConnection::defaultOptions()
  */
 function db_query($query, array $args = array(), array $options = array()) {
   if (empty($options['target'])) {
@@ -2091,10 +2132,10 @@
 }
 
 /**
- * Execute an arbitrary query string against the active database, restricted to
- * a specified range.
+ * Execute an arbitrary query string against the active database.
+ * 
+ * The query string has to be restricted to a specified range.
  *
- * @see DatabaseConnection::defaultOptions()
  * @param $query
  *   The prepared statement query to run. Although it will accept both named and
  *   unnamed placeholders, named placeholders are strongly preferred as they are
@@ -2110,8 +2151,11 @@
  *   the order of placeholders in the query string.
  * @param $options
  *   An array of options to control how the query operates.
+ *
  * @return DatabaseStatementInterface
  *   A prepared statement object, already executed.
+ *
+ * @see DatabaseConnection::defaultOptions()
  */
 function db_query_range($query, $from, $count, array $args = array(), array $options = array()) {
   if (empty($options['target'])) {
@@ -2122,10 +2166,10 @@
 }
 
 /**
- * Execute a query string against the active database and save the result set
- * to a temp table.
+ * Execute a query string and save the result set to a temp table.
+ *
+ * The execution of the query string happens against the active database.
  *
- * @see DatabaseConnection::defaultOptions()
  * @param $query
  *   The prepared statement query to run. Although it will accept both named and
  *   unnamed placeholders, named placeholders are strongly preferred as they are
@@ -2137,8 +2181,11 @@
  *   the order of placeholders in the query string.
  * @param $options
  *   An array of options to control how the query operates.
+ *
  * @return
  *   The name of the temporary table.
+ *
+ * @see DatabaseConnection::defaultOptions()
  */
 function db_query_temporary($query, array $args = array(), array $options = array()) {
   if (empty($options['target'])) {
@@ -2155,6 +2202,7 @@
  *   The table into which to insert.
  * @param $options
  *   An array of options to control how the query operates.
+ *
  * @return InsertQuery
  *   A new InsertQuery object for this connection.
  */
@@ -2172,6 +2220,7 @@
  *   The table into which to merge.
  * @param $options
  *   An array of options to control how the query operates.
+ *
  * @return MergeQuery
  *   A new MergeQuery object for this connection.
  */
@@ -2189,6 +2238,7 @@
  *   The table to update.
  * @param $options
  *   An array of options to control how the query operates.
+ *
  * @return UpdateQuery
  *   A new UpdateQuery object for this connection.
  */
@@ -2206,6 +2256,7 @@
  *   The table from which to delete.
  * @param $options
  *   An array of options to control how the query operates.
+ *
  * @return DeleteQuery
  *   A new DeleteQuery object for this connection.
  */
@@ -2223,6 +2274,7 @@
  *   The table from which to delete.
  * @param $options
  *   An array of options to control how the query operates.
+ *
  * @return TruncateQuery
  *   A new TruncateQuery object for this connection.
  */
@@ -2243,6 +2295,7 @@
  *   The alias for the base table of this query.
  * @param $options
  *   An array of options to control how the query operates.
+ *
  * @return SelectQuery
  *   A new SelectQuery object for this connection.
  */
@@ -2263,6 +2316,7 @@
  * @param $options
  *   An array of options to control how the transaction operates.  Only the
  *   target key has any meaning in this case.
+ *
  * @return DatabaseTransaction
  *   A new DatabaseTransaction object for this connection.
  */
@@ -2278,6 +2332,7 @@
  *
  * @param $key
  *   The key in the $databases array to set as the default database.
+ *
  * @return
  *   The key of the formerly active database.
  */
@@ -2306,6 +2361,7 @@
  *
  * @param $table
  *   The table name to escape.
+ *
  * @return
  *   The escaped table name as a string.
  */
@@ -2334,6 +2390,7 @@
  *
  * @param $string
  *   The string to escape.
+ *
  * @return
  *   The escaped string.
  */
@@ -2342,10 +2399,12 @@
 }
 
 /**
- * Retrieve the name of the currently active database driver, such as "mysql" or
- * "pgsql".
+ * Retrieve the name of the currently active database driver.
+ *
+ * For example: "mysql" or "pgsql".
  *
- * @return The name of the currently active database driver.
+ * @return
+ *   The name of the currently active database driver.
  */
 function db_driver() {
   return Database::getConnection()->driver();
@@ -2375,6 +2434,7 @@
  *   After a database import, it might be that the sequences table is behind, so
  *   by passing in a minimum ID, it can be assured that we never issue the same
  *   ID.
+ *
  * @return
  *   An integer number larger than any number returned before for this sequence.
  */
@@ -2415,6 +2475,7 @@
  *
  * @param $fields
  *   An array of key/index column specifiers.
+ *
  * @return
  *   An array of field names.
  */
@@ -2429,6 +2490,7 @@
  *   The name of the table in drupal (no prefixing).
  * @param $name
  *   The name of the index in drupal (no prefixing).
+ *
  * @return
  *   TRUE if the given index exists, otherwise FALSE.
  */
@@ -2441,6 +2503,7 @@
  *
  * @param $table
  *   The name of the table in drupal (no prefixing).
+ *
  * @return
  *   TRUE if the given table exists, otherwise FALSE.
  */
@@ -2455,6 +2518,7 @@
  *   The name of the table in drupal (no prefixing).
  * @param $name
  *   The name of the column.
+ *
  * @return
  *   TRUE if the given column exists, otherwise FALSE.
  */
@@ -2468,6 +2532,7 @@
  * @param $table_expression
  *   An SQL expression, for example "simpletest%" (without the quotes).
  *   BEWARE: this is not prefixed, the caller should take care of that.
+ *
  * @return
  *   Array, both the keys and the values are the matching tables.
  */
@@ -2480,8 +2545,10 @@
 }
 
 /**
- * This maps a generic data type in combination with its data size
- * to the engine-specific data type.
+ * This maps a generic data type.
+ * 
+ * The mapping happens in combination with its data size to the engine-specific
+ * data type.
  */
 function db_type_map() {
   return Database::getConnection()->schema()->getFieldTypeMap();
@@ -2527,6 +2594,7 @@
  *   without the 'fields' element. If you are adding a type 'serial' field, you
  *   MUST specify at least one key or index including it in this array. See
  *   db_change_field() for more explanation why.
+ *
  * @see db_change_field()
  */
 function db_add_field($table, $field, $spec, $keys_new = array()) {
@@ -2714,16 +2782,17 @@
  */
 
 /**
- * Prints a themed maintenance page with the 'Site offline' text, adding the
- * provided error message in the case of 'display_errors' set to on. Ends the
- * page request; no return.
+ * Prints a themed maintenance page with the 'Site offline' text.
+ *
+ * Adds the provided error message in the case of 'display_errors' set to on.
+ * Ends the page request; no return.
  */
 function _db_error_page($error = '') {
   global $db_type;
   drupal_language_initialize();
   drupal_maintenance_theme();
   drupal_add_http_header($_SERVER['SERVER_PROTOCOL'] . ' 503 Service Unavailable');
-  drupal_set_title('Site offline');
+  drupal_set_title(t('Site offline'));
 }
 
  /**