db_rewrite_sql is a mystery: explain what it does

db_rewrite_sql will be removed from D7. Instead, you can use hook_query_alter, see http://drupal.org/node/310077.

A link for D6:
http://drupal.org/node/93737

Basicallly, db_rewrite_sql allows other modules to change the query, mostly for access permissions, for example a node list.

This function doc header should have more information, for the Drupal 6 version. It is pointless to fix it in Drupal 7, since (as noted above) the function itself is going away.

It may also be pointless to propose a patch for Drupal 6, since it doesn't seem that such patches are ever being committed to the code base. Sigh.

Here's a patch to clean up this documentation.

Forgot status...

Looks good; just added a blank line between all the @param and @return.

I am cleaning up old 6.x documentation issues. At this point, we are not spending effort fixing them. Sorry.