Index: includes/database/query.inc
===================================================================
RCS file: /cvs/drupal/drupal/includes/database/query.inc,v
retrieving revision 1.57
diff -u -r1.57 query.inc
--- includes/database/query.inc	18 Oct 2010 00:50:36 -0000	1.57
+++ includes/database/query.inc	22 Oct 2010 20:09:58 -0000
@@ -17,56 +17,60 @@
 interface QueryConditionInterface {
 
   /**
-   * Helper function to build most common conditional clauses.
+   * Helper function: builds the most common conditional clauses.
    *
    * This method can take a variable number of parameters. If called with two
-   * parameters, they are taken as $field and $value with $operator having a value
-   * of IN if $value is an array and = otherwise.
+   * parameters, they are taken as $field and $value with $operator having a
+   * value of IN if $value is an array and = otherwise.
    *
    * @param $field
    *   The name of the field to check. If you would like to add a more complex
    *   condition involving operators or functions, use where().
    * @param $value
-   *   The value to test the field against. In most cases, this is a scalar. For more
-   *   complex options, it is an array. The meaning of each element in the array is
-   *   dependent on the $operator.
+   *   The value to test the field against. In most cases, this is a scalar.
+   *   For more complex options, it is an array. The meaning of each element in
+   *   the array is dependent on the $operator.
    * @param $operator
-   *   The comparison operator, such as =, <, or >=. It also accepts more complex
-   *   options such as IN, LIKE, or BETWEEN. Defaults to IN if $value is an array
-   *   = otherwise.
+   *   The comparison operator, such as =, <, or >=. It also accepts more
+   *   complex options such as IN, LIKE, or BETWEEN. Defaults to IN if $value is
+   *   an array, and = otherwise.
+   *
    * @return QueryConditionInterface
    *   The called object.
    */
   public function condition($field, $value = NULL, $operator = NULL);
 
   /**
-   * Add an arbitrary WHERE clause to the query.
+   * Adds an arbitrary WHERE clause to the query.
    *
    * @param $snippet
-   *   A portion of a WHERE clause as a prepared statement. It must use named placeholders,
-   *   not ? placeholders.
+   *   A portion of a WHERE clause as a prepared statement. It must use named
+   *   placeholders, not ? placeholders.
    * @param $args
    *   An associative array of arguments.
+   *
    * @return QueryConditionInterface
    *   The called object.
    */
   public function where($snippet, $args = array());
 
   /**
-   * Set a condition that the specified field be NULL.
+   * Sets a condition that the specified field be NULL.
    *
    * @param $field
    *   The name of the field to check.
+   *
    * @return QueryConditionInterface
    *   The called object.
    */
   public function isNull($field);
 
   /**
-   * Set a condition that the specified field be NOT NULL.
+   * Sets a condition that the specified field be NOT NULL.
    *
    * @param $field
    *   The name of the field to check.
+   *
    * @return QueryConditionInterface
    *   The called object.
    */
@@ -80,12 +84,13 @@
    *
    * The data structure that is returned is an indexed array of entries, where
    * each entry looks like the following:
-   *
+   * @code
    * array(
    *   'field' => $field,
    *   'value' => $value,
    *   'operator' => $operator,
    * );
+   * @endcode
    *
    * In the special case that $operator is NULL, the $field is taken as a raw
    * SQL snippet (possibly containing a function) and $value is an associative
@@ -112,7 +117,7 @@
    *
    * @param $connection
    *   The database connection for which to compile the conditionals.
-   * @param $query
+   * @param $queryPlaceholder
    *   The query this condition belongs to. If not given, the current query is
    *   used.
    */
@@ -130,12 +135,13 @@
    *
    * Tags are strings that identify a query. A query may have any number of
    * tags. Tags are used to mark a query so that alter hooks may decide if they
-   * wish to take action. Tags should be all lower-case and contain only letters,
-   * numbers, and underscore, and start with a letter. That is, they should
-   * follow the same rules as PHP identifiers in general.
+   * wish to take action. Tags should be all lower-case and contain only
+   * letters, numbers, and underscore, and start with a letter. That is, they
+   * should follow the same rules as PHP identifiers in general.
    *
    * @param $tag
    *   The tag to add.
+   *
    * @return QueryAlterableInterface
    *   The called object.
    */
@@ -146,6 +152,7 @@
    *
    * @param $tag
    *   The tag to check.
+   *
    * @return
    *   TRUE if this query has been marked with this tag, FALSE otherwise.
    */
@@ -156,8 +163,10 @@
    *
    * @param $tags
    *   A variable number of arguments, one for each tag to check.
+   *
    * @return
-   *   TRUE if this query has been marked with all specified tags, FALSE otherwise.
+   *   TRUE if this query has been marked with all specified tags, FALSE
+   *   otherwise.
    */
   public function hasAllTags();
 
@@ -166,6 +175,7 @@
    *
    * @param $tags
    *   A variable number of arguments, one for each tag to check.
+   *
    * @return
    *   TRUE if this query has been marked with at least one of the specified
    *   tags, FALSE otherwise.
@@ -184,6 +194,7 @@
    *   follows the same rules as any other PHP identifier.
    * @param $object
    *   The additional data to add to the query. May be any valid PHP variable.
+   *
    * @return QueryAlterableInterface
    *   The called object.
    */
@@ -194,6 +205,7 @@
    *
    * @param $key
    *   The unique identifier for the piece of metadata to retrieve.
+   *
    * @return
    *   The previously attached metadata object, or NULL if one doesn't exist.
    */
@@ -215,9 +227,10 @@
 }
 
 /**
- * Base class for the query builders.
+ * Base class for query builders.
  *
- * All query builders inherit from a common base class.
+ * Note that query builders use PHP's magic __toString() method to compile the
+ * query object into a prepared statement.
  */
 abstract class Query implements QueryPlaceholderInterface {
 
@@ -247,26 +260,41 @@
    */
   protected $comments = array();
 
+  /**
+   * Constructs a Query object.
+   *
+   * @param DatabaseConnection $connection
+   *   Database connection object.
+   * @param array $options
+   *   Array of query options.
+   */
   public function __construct(DatabaseConnection $connection, $options) {
     $this->connection = $connection;
     $this->queryOptions = $options;
   }
 
   /**
-   * Run the query against the database.
+   * Runs the query against the database.
    */
   abstract protected function execute();
 
   /**
-   * __toString() magic method.
+   * Implements PHP magic __toString method to convert the query to a string.
    *
-   * The toString operation is how we compile a query object to a prepared statement.
+   * The toString operation is how we compile a query object to a prepared
+   * statement.
    *
    * @return
    *   A prepared statement query string for this object.
    */
   abstract public function __toString();
 
+  /**
+   * Gets the next placeholder value for this query object.
+   *
+   * @return int
+   *   Next placeholder value.
+   */
   public function nextPlaceholder() {
     return $this->nextPlaceholder++;
   }
@@ -275,12 +303,13 @@
    * Adds a comment to the query.
    *
    * By adding a comment to a query, you can more easily find it in your
-   * query log or the list of active queries on an sql server. This allows
+   * query log or the list of active queries on an SQL server. This allows
    * for easier debugging and allows you to more easily find where a query
    * with a performance problem is being generated.
    *
    * @param $comment
    *   The comment string to be inserted into the query.
+   *
    * @return Query
    *   The called object.
    */
@@ -297,7 +326,6 @@
    * use of comment() is preferred.
    *
    * Note that this method must be called by reference as well:
-   *
    * @code
    * $comments =& $query->getComments();
    * @endcode
@@ -311,7 +339,7 @@
 }
 
 /**
- * General class for an abstracted INSERT operation.
+ * General class for an abstracted INSERT query.
  */
 class InsertQuery extends Query {
 
@@ -330,7 +358,7 @@
   protected $insertFields = array();
 
   /**
-   * An array of fields which should be set to their database-defined defaults.
+   * An array of fields that should be set to their database-defined defaults.
    *
    * @var array
    */
@@ -339,13 +367,17 @@
   /**
    * A nested array of values to insert.
    *
-   * $insertValues itself is an array of arrays. Each sub-array is an array of
-   * field names to values to insert. Whether multiple insert sets
-   * will be run in a single query or multiple queries is left to individual drivers
-   * to implement in whatever manner is most efficient. The order of values in each
-   * sub-array must match the order of fields in $insertFields.
+   * $insertValues is an array of arrays. Each sub-array is either an
+   * associative array whose keys are field names and whose values are field
+   * values to insert, or a non-associative array of values in the same order
+   * as $insertFields.
+   *
+   * Whether multiple insert sets will be run in a single query or multiple
+   * queries is left to individual drivers to implement in whatever manner is
+   * most appropriate. The order of values in each sub-array must match the
+   * order of fields in $insertFields.
    *
-   * @var string
+   * @var array
    */
   protected $insertValues = array();
 
@@ -356,6 +388,16 @@
    */
   protected $fromQuery;
 
+  /**
+   * Constructs an InsertQuery object.
+   *
+   * @param DatabaseConnection $connection
+   *   A DatabaseConnection object.
+   * @param string $table
+   *   Name of the table to associate with this query.
+   * @param array $options
+   *   Array of database options.
+   */
   public function __construct($connection, $table, array $options = array()) {
     if (!isset($options['return'])) {
       $options['return'] = Database::RETURN_INSERT_ID;
@@ -365,7 +407,7 @@
   }
 
   /**
-   * Add a set of field->value pairs to be inserted.
+   * Adds a set of field->value pairs to be inserted.
    *
    * This method may only be called once. Calling it a second time will be
    * ignored. To queue up multiple sets of values to be inserted at once,
@@ -380,6 +422,7 @@
    * @param $values
    *   An array of fields to insert into the database. The values must be
    *   specified in the same order as the $fields array.
+   *
    * @return InsertQuery
    *   The called object.
    */
@@ -401,15 +444,16 @@
   }
 
   /**
-   * Add another set of values to the query to be inserted.
+   * Adds another set of values to the query to be inserted.
    *
-   * If $values is a numeric array, it will be assumed to be in the same
+   * If $values is a numeric-keyed array, it will be assumed to be in the same
    * order as the original fields() call. If it is associative, it may be
    * in any order as long as the keys of the array match the names of the
    * fields.
    *
    * @param $values
    *   An array of values to add to the query.
+   *
    * @return InsertQuery
    *   The called object.
    */
@@ -429,7 +473,7 @@
   }
 
   /**
-   * Specify fields for which the database-defaults should be used.
+   * Specifies fields for which the database defaults should be used.
    *
    * If you want to force a given field to use the database-defined default,
    * not NULL or undefined, use this method to instruct the database to use
@@ -443,6 +487,7 @@
    * @param $fields
    *   An array of values for which to use the default values
    *   specified in the table definition.
+   *
    * @return InsertQuery
    *   The called object.
    */
@@ -451,6 +496,15 @@
     return $this;
   }
 
+  /**
+   * Sets the fromQuery on this InsertQuery object.
+   *
+   * @param SelectQueryInterface $query
+   *   The query to fetch the rows that should be inserted.
+   *
+   * @return InsertQuery
+   *   The called object.
+   */
   public function from(SelectQueryInterface $query) {
     $this->fromQuery = $query;
     return $this;
@@ -466,8 +520,8 @@
    *   return NULL. That makes it safe to use in multi-insert loops.
    */
   public function execute() {
-    // If validation fails, simply return NULL.
-    // Note that validation routines in preExecute() may throw exceptions instead.
+    // If validation fails, simply return NULL. Note that validation routines
+    // in preExecute() may throw exceptions instead.
     if (!$this->preExecute()) {
       return NULL;
     }
@@ -508,6 +562,12 @@
     return $last_insert_id;
   }
 
+  /**
+   * Implements PHP magic __toString method to convert the query to a string.
+   *
+   * @return string
+   *   The prepared statement.
+   */
   public function __toString() {
 
     // Create a comments string to prepend to the query.
@@ -531,7 +591,7 @@
   }
 
   /**
-   * Generic preparation and validation for an INSERT query.
+   * Preprocesses and validates the query.
    *
    * @return
    *   TRUE if the validation was successful, FALSE if not.
@@ -583,13 +643,24 @@
   protected $table;
 
   /**
-   * The condition object for this query. Condition handling is handled via
-   * composition.
+   * The condition object for this query.
+   *
+   * Condition handling is handled via composition.
    *
    * @var DatabaseCondition
    */
   protected $condition;
 
+  /**
+   * Constructs a DeleteQuery object.
+   *
+   * @param DatabaseConnection $connection
+   *   A DatabaseConnection object.
+   * @param string $table
+   *   Name of the table to associate with this query.
+   * @param array $options
+   *   Array of database options.
+   */
   public function __construct(DatabaseConnection $connection, $table, array $options = array()) {
     $options['return'] = Database::RETURN_AFFECTED;
     parent::__construct($connection, $options);
@@ -598,38 +669,65 @@
     $this->condition = new DatabaseCondition('AND');
   }
 
+  /**
+   * Implements QueryConditionInterface::condition().
+   */
   public function condition($field, $value = NULL, $operator = NULL) {
     $this->condition->condition($field, $value, $operator);
     return $this;
   }
 
+  /**
+   * Implements QueryConditionInterface::isNull().
+   */
   public function isNull($field) {
     $this->condition->isNull($field);
     return $this;
   }
 
+  /**
+   * Implements QueryConditionInterface::isNotNull().
+   */
   public function isNotNull($field) {
     $this->condition->isNotNull($field);
     return $this;
   }
 
+  /**
+   * Implements QueryConditionInterface::conditions().
+   */
   public function &conditions() {
     return $this->condition->conditions();
   }
 
+  /**
+   * Implements QueryConditionInterface::arguments().
+   */
   public function arguments() {
     return $this->condition->arguments();
   }
 
+  /**
+   * Implements QueryConditionInterface::where().
+   */
   public function where($snippet, $args = array()) {
     $this->condition->where($snippet, $args);
     return $this;
   }
 
+  /**
+   * Implements QueryConditionInterface::compile().
+   */
   public function compile(DatabaseConnection $connection, QueryPlaceholderInterface $queryPlaceholder = NULL) {
     return $this->condition->compile($connection, isset($queryPlaceholder) ? $queryPlaceholder : $this);
   }
 
+  /**
+   * Executes the DELETE query.
+   *
+   * @return
+   *   The return value is dependant on the database connection.
+   */
   public function execute() {
     $values = array();
     if (count($this->condition)) {
@@ -640,6 +738,12 @@
     return $this->connection->query((string) $this, $values, $this->queryOptions);
   }
 
+  /**
+   * Implements PHP magic __toString method to convert the query to a string.
+   *
+   * @return string
+   *   The prepared statement.
+   */
   public function __toString() {
 
     // Create a comments string to prepend to the query.
@@ -664,26 +768,51 @@
 class TruncateQuery extends Query {
 
   /**
-   * The table from which to delete.
+   * The table to truncate.
    *
    * @var string
    */
   protected $table;
 
+  /**
+   * Constructs a TruncateQuery object.
+   *
+   * @param DatabaseConnection $connection
+   *   A DatabaseConnection object.
+   * @param string $table
+   *   Name of the table to associate with this query.
+   * @param array $options
+   *   Array of database options.
+   */
   public function __construct(DatabaseConnection $connection, $table, array $options = array()) {
     $options['return'] = Database::RETURN_AFFECTED;
     parent::__construct($connection, $options);
     $this->table = $table;
   }
 
+  /**
+   * Implements QueryConditionInterface::compile().
+   */
   public function compile(DatabaseConnection $connection, QueryPlaceholderInterface $queryPlaceholder = NULL) {
     return $this->condition->compile($connection, isset($queryPlaceholder) ? $queryPlaceholder : $this);
   }
 
+  /**
+   * Executes the TRUNCATE query.
+   *
+   * @return
+   *   Return value is dependent on the database type.
+   */
   public function execute() {
     return $this->connection->query((string) $this, array(), $this->queryOptions);
   }
 
+  /**
+   * Implements PHP magic __toString method to convert the query to a string.
+   *
+   * @return string
+   *   The prepared statement.
+   */
   public function __toString() {
     // Create a comments string to prepend to the query.
     $comments = (!empty($this->comments)) ? '/* ' . implode('; ', $this->comments) . ' */ ' : '';
@@ -719,26 +848,39 @@
   protected $arguments = array();
 
   /**
-   * The condition object for this query. Condition handling is handled via
-   * composition.
+   * The condition object for this query.
+   *
+   * Condition handling is handled via composition.
    *
    * @var DatabaseCondition
    */
   protected $condition;
 
   /**
-   * An array of fields to update to an expression in case of a duplicate record.
+   * Array of fields to update to an expression in case of a duplicate record.
    *
    * This variable is a nested array in the following format:
+   * @code
    * <some field> => array(
-   *  'condition' => <condition to execute, as a string>
-   *  'arguments' => <array of arguments for condition, or NULL for none>
+   *  'condition' => <condition to execute, as a string>,
+   *  'arguments' => <array of arguments for condition, or NULL for none>,
    * );
+   * @endcode
    *
    * @var array
    */
   protected $expressionFields = array();
 
+  /**
+   * Constructs an UpdateQuery object.
+   *
+   * @param DatabaseConnection $connection
+   *   A DatabaseConnection object.
+   * @param string $table
+   *   Name of the table to associate with this query.
+   * @param array $options
+   *   Array of database options.
+   */
   public function __construct(DatabaseConnection $connection, $table, array $options = array()) {
     $options['return'] = Database::RETURN_AFFECTED;
     parent::__construct($connection, $options);
@@ -747,44 +889,66 @@
     $this->condition = new DatabaseCondition('AND');
   }
 
+  /**
+   * Implements QueryConditionInterface::condition().
+   */
   public function condition($field, $value = NULL, $operator = NULL) {
     $this->condition->condition($field, $value, $operator);
     return $this;
   }
 
+  /**
+   * Implements QueryConditionInterface::isNull().
+   */
   public function isNull($field) {
     $this->condition->isNull($field);
     return $this;
   }
 
+  /**
+   * Implements QueryConditionInterface::isNotNull().
+   */
   public function isNotNull($field) {
     $this->condition->isNotNull($field);
     return $this;
   }
 
+  /**
+   * Implements QueryConditionInterface::conditions().
+   */
   public function &conditions() {
     return $this->condition->conditions();
   }
 
+  /**
+   * Implements QueryConditionInterface::arguments().
+   */
   public function arguments() {
     return $this->condition->arguments();
   }
 
+  /**
+   * Implements QueryConditionInterface::where().
+   */
   public function where($snippet, $args = array()) {
     $this->condition->where($snippet, $args);
     return $this;
   }
 
+  /**
+   * Implements QueryConditionInterface::compile().
+   */
   public function compile(DatabaseConnection $connection, QueryPlaceholderInterface $queryPlaceholder = NULL) {
     return $this->condition->compile($connection, isset($queryPlaceholder) ? $queryPlaceholder : $this);
   }
 
   /**
-   * Add a set of field->value pairs to be updated.
+   * Adds a set of field->value pairs to be updated.
    *
    * @param $fields
    *   An associative array of fields to write into the database. The array keys
-   *   are the field names while the values are the values to which to set them.
+   *   are the field names and the values are the values to which to set them.
+   *
    * @return UpdateQuery
    *   The called object.
    */
@@ -794,7 +958,7 @@
   }
 
   /**
-   * Specify fields to be updated as an expression.
+   * Specifies fields to be updated as an expression.
    *
    * Expression fields are cases such as counter=counter+1. This method takes
    * precedence over fields().
@@ -807,6 +971,7 @@
    * @param $arguments
    *   If specified, this is an array of key/value pairs for named placeholders
    *   corresponding to the expression.
+   *
    * @return UpdateQuery
    *   The called object.
    */
@@ -819,6 +984,12 @@
     return $this;
   }
 
+  /**
+   * Executes the UPDATE query.
+   *
+   * @return
+   *   The number of rows affected by the update.
+   */
   public function execute() {
 
     // Expressions take priority over literal fields, so we process those first
@@ -847,6 +1018,12 @@
     return $this->connection->query((string) $this, $update_values, $this->queryOptions);
   }
 
+  /**
+   * Implements PHP magic __toString method to convert the query to a string.
+   *
+   * @return string
+   *   The prepared statement.
+   */
   public function __toString() {
 
     // Create a comments string to prepend to the query.
@@ -880,7 +1057,7 @@
 }
 
 /**
- * General class for an abstracted MERGE operation.
+ * General class for an abstracted MERGE query operation.
  *
  * An ANSI SQL:2003 compatible database would run the following query:
  *
@@ -970,25 +1147,37 @@
   protected $updateFields = array();
 
   /**
-   * An array of fields to update to an expression in case of a duplicate record.
+   * Array of fields to update to an expression in case of a duplicate record.
    *
    * This variable is a nested array in the following format:
+   * @code
    * <some field> => array(
-   *  'condition' => <condition to execute, as a string>
-   *  'arguments' => <array of arguments for condition, or NULL for none>
+   *  'condition' => <condition to execute, as a string>,
+   *  'arguments' => <array of arguments for condition, or NULL for none>,
    * );
+   * @endcode
    *
    * @var array
    */
   protected $expressionFields = array();
 
   /**
-   * Flag indicated whether an UPDATE is necessary.
+   * Flag indicating whether an UPDATE is necessary.
    *
    * @var boolean
    */
   protected $needsUpdate = FALSE;
 
+  /**
+  * Constructs a MergeQuery object.
+  *
+  * @param DatabaseConnection $connection
+  *   A DatabaseConnection object.
+  * @param string $table
+  *   Name of the table to associate with this query.
+  * @param array $options
+  *   Array of database options.
+  */
   public function __construct(DatabaseConnection $connection, $table, array $options = array()) {
     $options['return'] = Database::RETURN_AFFECTED;
     parent::__construct($connection, $options);
@@ -998,7 +1187,7 @@
   }
 
   /**
-   * Set the table or subquery to be used for the condition.
+   * Sets the table or subquery to be used for the condition.
    *
    * @param $table
    *   The table name or the subquery to be used. Use a SelectQuery object to
@@ -1017,7 +1206,7 @@
    *
    * @param $fields
    *   An associative array of fields to write into the database. The array keys
-   *   are the field names while the values are the values to which to set them.
+   *   are the field names and the values are the values to which to set them.
    *
    * @return MergeQuery
    *   The called object.
@@ -1029,7 +1218,7 @@
   }
 
   /**
-   * Specify fields to be updated as an expression.
+   * Specifies fields to be updated as an expression.
    *
    * Expression fields are cases such as counter = counter + 1. This method
    * takes precedence over MergeQuery::updateFields() and it's wrappers,
@@ -1043,6 +1232,7 @@
    * @param $arguments
    *   If specified, this is an array of key/value pairs for named placeholders
    *   corresponding to the expression.
+   *
    * @return MergeQuery
    *   The called object.
    */
@@ -1104,7 +1294,7 @@
   }
 
   /**
-   * Set common field-value pairs in the INSERT and UPDATE query parts.
+   * Sets common field-value pairs in the INSERT and UPDATE query parts.
    *
    * This method should only be called once. It may be called either
    * with a single associative array or two indexed arrays. If called
@@ -1114,11 +1304,11 @@
    * and the second array is taken as the corresponding values.
    *
    * @param $fields
-   *   An associative array of fields on which to insert. The keys of the
-   *   array are taken to be the fields and the values are taken to be
-   *   corresponding values to insert.
+   *   An array of fields to insert, or an associative array of fields and
+   *   values. The keys of the array are taken to be the fields and the values
+   *   are taken to be corresponding values to insert.
    * @param $values
-   *   An array of fields to set into the database. The values must be
+   *   An array of values to set into the database. The values must be
    *   specified in the same order as the $fields array.
    *
    * @return MergeQuery
@@ -1137,7 +1327,7 @@
   }
 
   /**
-   * Set the key field(s) to be used as conditions for this query.
+   * Sets the key field(s) to be used as conditions for this query.
    *
    * This method should only be called once. It may be called either
    * with a single associative array or two indexed arrays. If called
@@ -1150,10 +1340,11 @@
    * If no other method is called, the UPDATE will become a no-op.
    *
    * @param $fields
-   *   An array of fields to set.
+   *   An array of fields to set, or an associative array of fields and values.
    * @param $values
-   *   An array of fields to set into the database. The values must be
+   *   An array of values to set into the database. The values must be
    *   specified in the same order as the $fields array.
+   *
    * @return MergeQuery
    *   The called object.
    */
@@ -1168,38 +1359,68 @@
     return $this;
   }
 
+  /**
+   * Implements QueryConditionInterface::condition().
+   */
   public function condition($field, $value = NULL, $operator = NULL) {
     $this->condition->condition($field, $value, $operator);
     return $this;
   }
 
+  /**
+   * Implements QueryConditionInterface::isNull().
+   */
   public function isNull($field) {
     $this->condition->isNull($field);
     return $this;
   }
 
+  /**
+   * Implements QueryConditionInterface::isNotNull().
+   */
   public function isNotNull($field) {
     $this->condition->isNotNull($field);
     return $this;
   }
 
+  /**
+   * Implements QueryConditionInterface::conditions().
+   */
   public function &conditions() {
     return $this->condition->conditions();
   }
 
+  /**
+   * Implements QueryConditionInterface::arguments().
+   */
   public function arguments() {
     return $this->condition->arguments();
   }
 
+  /**
+   * Implements QueryConditionInterface::where().
+   */
   public function where($snippet, $args = array()) {
     $this->condition->where($snippet, $args);
     return $this;
   }
 
+  /**
+   * Implements QueryConditionInterface::compile().
+   */
   public function compile(DatabaseConnection $connection, QueryPlaceholderInterface $queryPlaceholder = NULL) {
     return $this->condition->compile($connection, isset($queryPlaceholder) ? $queryPlaceholder : $this);
   }
 
+  /**
+   * Implements PHP magic __toString method to convert the query to a string.
+   *
+   * In the degenerate case, there is no string-able query as this operation
+   * is potentially two queries.
+   *
+   * @return string
+   *   The prepared query statement.
+   */
   public function __toString() {
   }
 
@@ -1261,25 +1482,54 @@
  */
 class DatabaseCondition implements QueryConditionInterface, Countable {
 
+  /**
+   * Array of conditions.
+   *
+   * @var array
+   */
   protected $conditions = array();
+
+  /**
+   * Array of arguments.
+   *
+   * @var array
+   */
   protected $arguments = array();
 
+  /**
+   * Whether the conditions have been changed.
+   *
+   * TRUE if the condition has been changed since the last compile.
+   * FALSE if the condition has been compiled and not changed.
+   *
+   * @var bool
+   */
   protected $changed = TRUE;
 
+  /**
+   * Constructs a DataBaseCondition object.
+   *
+   * @param string $conjunction
+   *   The operator to use to combine conditions: 'AND' or 'OR'.
+   */
   public function __construct($conjunction) {
     $this->conditions['#conjunction'] = $conjunction;
   }
 
   /**
-   * Return the size of this conditional. This is part of the Countable interface.
+   * Implements Countable::count().
    *
-   * The size of the conditional is the size of its conditional array minus
-   * one, because one element is the the conjunction.
+   * Returns the size of this conditional. The size of the conditional is the
+   * size of its conditional array minus one, because one element is the the
+   * conjunction.
    */
   public function count() {
     return count($this->conditions) - 1;
   }
 
+  /**
+   * Implements QueryConditionInterface::condition().
+   */
   public function condition($field, $value = NULL, $operator = NULL) {
     if (!isset($operator)) {
       if (is_array($value)) {
@@ -1303,6 +1553,9 @@
     return $this;
   }
 
+  /**
+   * Implements QueryConditionInterface::where().
+   */
   public function where($snippet, $args = array()) {
     $this->conditions[] = array(
       'field' => $snippet,
@@ -1314,18 +1567,30 @@
     return $this;
   }
 
+  /**
+   * Implements QueryConditionInterface::isNull().
+   */
   public function isNull($field) {
     return $this->condition($field);
   }
 
+  /**
+   * Implements QueryConditionInterface::isNotNull().
+   */
   public function isNotNull($field) {
     return $this->condition($field, NULL, 'IS NOT NULL');
   }
 
+  /**
+   * Implements QueryConditionInterface::conditions().
+   */
   public function &conditions() {
     return $this->conditions;
   }
 
+  /**
+   * Implements QueryConditionInterface::arguments().
+   */
   public function arguments() {
     // If the caller forgot to call compile() first, refuse to run.
     if ($this->changed) {
@@ -1334,6 +1599,9 @@
     return $this->arguments;
   }
 
+  /**
+   * Implements QueryConditionInterface::compile().
+   */
   public function compile(DatabaseConnection $connection, QueryPlaceholderInterface $queryPlaceholder = NULL) {
     if ($this->changed) {
       $condition_fragments = array();
@@ -1407,6 +1675,12 @@
     }
   }
 
+  /**
+   * Implements PHP magic __toString method to convert the conditions to string.
+   *
+   * @return string
+   *   A string version of the conditions.
+   */
   public function __toString() {
     // If the caller forgot to call compile() first, refuse to run.
     if ($this->changed) {
@@ -1415,6 +1689,12 @@
     return $this->stringVersion;
   }
 
+  /**
+   * PHP magic __clone() method.
+   *
+   * Only copies fields that implement QueryConditionInterface. Also sets
+   * $this->changed to TRUE.
+   */
   function __clone() {
     $this->changed = TRUE;
     foreach ($this->conditions as $key => $condition) {
@@ -1433,6 +1713,7 @@
    *
    * @param $operator
    *   The condition operator, such as "IN", "BETWEEN", etc. Case-sensitive.
+   *
    * @return
    *   The extra handling directives for the specified operator, or NULL.
    */