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	18 Apr 2010 21:50:29 -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.
  */
@@ -259,10 +261,10 @@
 define('DB_QUERY_REGEXP', '/(%d|%s|%%|%f|%b|%n)/');
 
 /**
- * Helper function for db_rewrite_sql.
+ * Helper function for db_rewrite_sql().
  *
- * Collects JOIN and WHERE statements via hook_db_rewrite_sql()
- * Decides whether to select primary_key or DISTINCT(primary_key)
+ * Collects JOIN and WHERE statements via hook_db_rewrite_sql() and
+ * decides whether to select primary_key or DISTINCT(primary_key).
  *
  * @param $query
  *   Query to be rewritten.
@@ -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,13 @@
 }
 
 /**
- * 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 for access control. 
+ *
+ * This function asks modules via _db_rewrite_sql() for their
+ * implementations of hook_db_rewrite_sql(), and collectes the responses into
+ * a modified query, which it returns. It is meant to be used for SELECT
+ * queries, and will only work correctly if your query uses JOIN clauses
+ * to define tables, rather than FROM table1, table2 syntax.
  *
  * @param $query
  *   Query to be rewritten.
@@ -320,10 +328,12 @@
  * @param $primary_field
  *   Name of the primary field.
  * @param $args
- *   An array of arguments, passed to the implementations of hook_db_rewrite_sql.
+ *   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.
+ *   hook_db_rewrite_sql() implementations. nid is rewritten if needed.
  */
 function db_rewrite_sql($query, $primary_table = 'n', $primary_field = 'nid',  $args = array()) {
   list($join, $where, $distinct) = _db_rewrite_sql($query, $primary_table, $primary_field, $args);
@@ -398,6 +408,7 @@
  * @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.
  */
 function db_distinct_field($table, $field, $query) {
@@ -559,6 +570,7 @@
  *
  * @param $fields
  *   An array of key/index column specifiers.
+ *   
  * @return
  *   An array of field names.
  */
@@ -583,6 +595,7 @@
  *
  * @param $type
  *   The Schema API type of a field.
+ *   
  * @return
  *   The placeholder string to embed in a query for that type.
  */