Index: includes/database.inc
===================================================================
RCS file: /cvs/drupal/drupal/includes/Attic/database.inc,v
retrieving revision 1.92.2.9
diff -u -r1.92.2.9 database.inc
--- includes/database.inc	1 Feb 2010 16:32:10 -0000	1.92.2.9
+++ includes/database.inc	9 Jul 2010 17:12:41 -0000
@@ -56,6 +56,7 @@
  * @param $sql
  *   A string containing a complete SQL query.  %-substitution
  *   parameters are not supported.
+ *
  * @return
  *   An array containing the keys:
  *      success: a boolean indicating whether the query succeeded
@@ -76,6 +77,7 @@
  *
  * @param $sql
  *   A string containing a partial or entire SQL query.
+ *
  * @return
  *   The properly-prefixed string.
  */
@@ -275,6 +277,7 @@
  *   Name of the primary field.
  * @param $args
  *   Array of additional arguments.
+ *
  * @return
  *   An array: join statements, where statements, field or DISTINCT(field).
  */
@@ -307,8 +310,10 @@
 }
 
 /**
- * Rewrites node, taxonomy and comment queries. Use it for listing queries. Do not
- * use FROM table1, table2 syntax, use JOIN instead.
+ * Rewrites node, taxonomy and comment queries.
+ *
+ * To be used for for listing queries. Do not use FROM table1, table2 syntax,
+ * use JOIN instead.
  *
  * @param $query
  *   Query to be rewritten.
@@ -321,6 +326,7 @@
  *   Name of the primary field.
  * @param $args
  *   An array of arguments, passed to the implementations of hook_db_rewrite_sql.
+ *
  * @return
  *   The original query with JOIN and WHERE statements inserted from
  *   hook_db_rewrite_sql implementations. nid is rewritten if needed.
@@ -389,16 +395,20 @@
 }
 
 /**
- * Adds the DISTINCT flag to the supplied query if a DISTINCT doesn't already
- * exist in the query. Returns the altered query.
+ * Adds the DISTINCT flag to the supplied query and returns the altered query.
+ *
+ * The supplied query should not contain a DISTINCT flag. This will not, and
+ * never did guarantee that you will obtain distinct values of $table.$field.
  *
- * This will not, and never did guarantee that you will obtain distinct 
- * values of $table.$field.
+ * @param $table
+ *   Unused. Kept to retain API compatibility.
+ * @param $field
+ *   Unused. Kept to retain API compatibility.
+ * @param $query
+ *   Query to which the DISTINCT flag should be applied.
  *
- * @param $table Unused. Kept to remain API compatibility.
- * @param $field Unused. Kept to remain API compatibility.
- * @param $query Query to which the DISTINCT flag should be applied.
- * @return SQL query with the DISTINCT flag set.
+ * @return
+ *   SQL query with the DISTINCT flag set.
  */
 function db_distinct_field($table, $field, $query) {
   $matches = array();
@@ -406,6 +416,7 @@
     // Only add distinct to the outer SELECT to avoid messing up subqueries.
     $query = preg_replace('/^SELECT/i', 'SELECT DISTINCT', $query);
   }
+
   return $query;
 }
 
@@ -552,13 +563,14 @@
 }
 
 /**
- * Return an array of field names from an array of key/index column specifiers.
+ * Returns an array of field names from an array of key/index column specifiers.
  *
  * This is usually an identity function but if a key/index uses a column prefix
  * specification, this function extracts just the name.
  *
  * @param $fields
  *   An array of key/index column specifiers.
+ *
  * @return
  *   An array of field names.
  */
@@ -576,13 +588,14 @@
 }
 
 /**
- * Given a Schema API field type, return the correct %-placeholder.
+ * Given a Schema API field type, returns the correct %-placeholder.
  *
  * Embed the placeholder in a query to be passed to db_query and and pass as an
  * argument to db_query a value of the specified type.
  *
  * @param $type
  *   The Schema API type of a field.
+ *
  * @return
  *   The placeholder string to embed in a query for that type.
  */