Index: includes/database.inc
===================================================================
RCS file: /cvs/drupal/drupal/includes/Attic/database.inc,v
retrieving revision 1.92.2.8
diff -u -r1.92.2.8 database.inc
--- includes/database.inc	14 Sep 2009 10:49:34 -0000	1.92.2.8
+++ includes/database.inc	28 Sep 2009 16:21:51 -0000
@@ -259,10 +259,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.
@@ -307,8 +307,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 +325,11 @@
  * @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);