Return value docs on db_query() are lacking important information

This is what PHP official documentation says:

• mysqli: "For successful SELECT, SHOW, DESCRIBE or EXPLAIN queries mysqli_query() will return a mysqli_result object. For other successful queries mysqli_query() will return TRUE."
• mysql: "For SELECT, SHOW, DESCRIBE, EXPLAIN and other statements returning resultset, mysql_query() returns a resource on success, or FALSE on error. For other type of SQL statements, INSERT, UPDATE, DELETE, DROP, etc, mysql_query() returns TRUE on success or FALSE on error. "
• pg_query (PostgreSQL): returns "A query result resource on success or FALSE on failure. "

Sounds like something that needs to be updated in the documentation - thanks!

Something like this?
I assume this doesn't need fixing in D8 or D7 since the database system changed a lot.

I don't think "resultset" is a word, even though the official PHP documentation apparently uses it? Also, maybe we should give examples of which queries return result sets, like the PHP docs in #2 do?

And yes, this is drupal 6 only.

Is this better?

That looks better! I am wondering if we can combine the mysql and mysqli parts?

Also, our style guidelines in the Drupal project require a , before the final or in a list:
apples, oranges, or bananas

The PHP docs area slightly different for mysql/mysqli - mysql has "and other statements returning resultset" after the list of query types. I guess it could be that they're actually the same and the PHP docs are misleading.

Should I remove the distinction between the 2 and just say "Successful SELECT, SHOW, DESCRIBE, EXPLAIN, or other queries which return a set of results will return a database query result resource" ?

That seems like a good idea to me (combining as you suggest).

Attached.

That looks good to me, thanks!

Thanks, committed, pushed.