db_query() doc - list of % specs is incomplete

Good catch, thanks for reporting!

This refers to http://api.drupal.org/api/function/db_query/6

The doc currently says:
"Valid %-modifiers are: %s, %d, %f, %b (binary data, do not enclose in '') and %%."

If you look at http://api.drupal.org/api/constant/DB_QUERY_REGEXP/6 and http://api.drupal.org/api/function/_db_query_callback/6, you see that %d is for integers, %s is for strings, %n is for numbers, %% is for a % sign, %f is for float, and %b is for binary. So the reporter is correct.

Note that Drupal 7 uses a completely different mechanism for query variable expansion, so this issue only applies to Drupal 6.

Here is a patch for the db_query() doc. Also fixes #489676: Incorrect return specification for db_query.

This seem to only affect the docs for the pgsql version of this function. I guess we intend to have identical documentation on the MySQL functions as well. I guess you include both database information in @return, since api.drupal.org will not consider these two different functions given their equal name.

For some reason, the pgsql version of the doc only is what is displayed on api.drupal.org (I guess they had to choose one?). But you are right, probably the function header in the MySQL version should also be updated.

From a later bug report: (#774620: Documentation problem with db_query)

Please add comment http://api.drupal.org/api/function/db_query/6#comment-236 to the doc:
Placeholder | Meaning
%s | String
%d | Integer
%b | Binary
%% | Inserts a literal % sign
%f | Float

Gabor: Right now only the PGSQL versions of these functions is being displayed, but when we get the new version of the API module out there, we'll be displaying both. So probably both of the functions' doc needs to be fixed up.

Here is a patch that enumerates each supported sprintf format. Applied for both Postgres and MySQL.

Good work... One small thing to fix:

 * @return
- *   A database query result resource, or FALSE if the query was not
- *   executed correctly.
+ *   FALSE if unsuccessful; TRUE for
+ *   a successful UPDATE, INSERT, DELETE or similar query; a database query
+ *   result resource for a successful SELECT, SHOW, EXPLAIN, etc. query.

We try to have everything wrap at as close to 80-character lines as possible. So these three added lines should be reformatted for that. Thanks!

Thanks, Jennifer. Here's the updated patch with better formatting.

Looks good to me...
Thanks!

Uhm, %n still not documented?

Doh! That needs to be added to the patch above. %n is a number.

Someone want to re-roll?

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