On Tue, 04 Jul 2006, Nuno Lopes wrote:
The answer to your questions are answered in our howto. Mainly here:
http://doc.php.net/php/dochowto/chapter-conventions.php
Quoting the important part (for now):
"Do not use mixed, if the return value is of a certain (not boolean) type,
and FALSE only on error. Provide the primary return type as the return type
of the function, and write down in the explanation, that it returns FALSE
on error. Use &return.success; if the function returns TRUE on success, and
FALSE on failure. "
Oh, okay. Seems I missed this part. So 2) '"mixed" return values on
error paths" is clearly a "no".
yep
But what about 1) '"mixed" return values in normal usage', for example
mysql_query(), which may return TRUE in normal usage? Or
mysql_fetch_array() which returns FALSE if there are no more rows --
should this be considered an error condition? At least the mysql_query()
issue confused someone on IRC today.
if the function returns different return types on normal usage you should use mixed. Don't forget to carefully document that.
(btw, while you are at it, you may consider upgrading the files you touch to the "new" doc style, which is simpler to maintain IMHO. take a look at
http://wiki.phpdoc.info/DocSkel)
(Besides this, I still consider my corrections 3) as valid.)
yes, yes. see the link above.
Thanks for your contributions,
Nuno
Kind regards,
Horst
----- Original Message -----
Hi,
I just noticed that the return types of some ext/mysql functions are not
correct, or at least misleading.
1) "mixed" return values in normal usage
----------------------------------------
In the description of mysql_query(), the interface is shown as
follows:
resource mysql_query ( string query [, resource link_identifier] )
But the "Return Values" section makes clear that the return type could
also be a boolean; shouldn't the return type be "mixed" instead of
"resource", as for example in the documentation to mysqli_query() -- or
has this been documented this way for a reason?
All ext/mysql functions which return mixed types but are not
properly documented to do so:
* mysql_query
* mysql_db_query
* mysql_fetch_array
* mysql_fetch_assoc
* mysql_fetch_field (here the docs even lack "or FALSE if there are no
more rows" in the "Return Values" section)
* mysql_fetch_object
* mysql_fetch_row
* mysql_unbuffered_query
2) "mixed" return values on error paths
---------------------------------------
Similarly this is true for mysql_connect(), although here FALSE is only
returned on failure; the "normal" return type is "resource". Is this
intentional, or should it also be corrected to "mixed"? (I'd vote for
the former.)
All ext/mysql functions which return FALSE on failure but are not
documented to do so in the "Description":
mysql_connect, mysql_db_name, mysql_fetch_lengths, mysql_field_flags,
mysql_field_len, mysql_field_name, mysql_field_table, mysql_field_type,
mysql_get_host_info, mysql_get_proto_info, mysql_get_server_info,
mysql_info, mysql_insert_id, mysql_list_dbs, mysql_list_fields,
mysql_list_processes, mysql_list_tables, mysql_num_fields,
mysql_num_rows, mysql_pconnect, mysql_real_escape_string, mysql_result,
mysql_stat (returns NULL on failure, not FALSE), mysql_tablename,
mysql_thread_id.
3) minor corrections
--------------------
Beyond this,
* mysql_field_seek needs a "Return Values" section (although it is
intuitive that it returns TRUE on success and FALSE on failure).
* mysql_field_table and mysql_field_type need "returns FALSE on failure"
to be documented.
Any comments/objections to these corrections? If nobody vetoes, I would
starting to fix 1) and 3) the next days.
Kind regards,
Horst
-- PGP-Key 0xD40E0E7A