#38130 [Opn->Asn]: Unwritten rule on functions returning null

ID: 38130 Updated by: philip@php.net Reported By: btherl at yahoo dot com dot au -Status: Open +Status: Assigned Bug Type: Documentation problem Operating System: Linux PHP Version: Irrelevant -Assigned To: +Assigned To: philip New Comment: For most users it's not an issue so that's likely where the "waste of time" comment in bug #38127 came from. The thought of this information overload and worrying about having it mentioned in every function man page... A little scary but something to consider. I personally don't have a strong feeling either way. Your suggestion of having it in a location, like under "Internal (built-in) functions" sounds reasonable and thank you for the write-up it looks good. The about.prototypes section is another possible location but perhaps not as appropriate. I agree with colder, it should not be listed under language.types.null. There are some function docs that mention NULL as a possible return value but this is rare. Regarding #38127 those docs should be reworded as it's misleading. Lastly, this bug report was left open so no need to think it'll be ignored ;-) Previous Comments: ------------------------------------------------------------------------ [2006-07-19 01:23:13] btherl at yahoo dot com dot au The origin of this report was when I suggested that a function document that it returns NULL when arguments are incorrectly typed. The response I got was "Most functions return NULL on bogus parameters. No need to waste time with this." Which leads to the obvious question: If there is no need to document that function X returns NULL on bogus parameters, then where is it documented? How about this: "The return value of built-in functions is undefined when the parameters are not of the correct type. Most functions will return NULL, but this is just a convention, and cannot be relied on." Anyone who wishes to reply with "This is a waste of time", save your time and don't hit submit :) I'm not writing this for you. ------------------------------------------------------------------------ [2006-07-18 10:59:36] colder@php.net "most functions" : Returning NULL is not a general rule, thus it shoulnd't IMO be documented globally such as in the docs for NULL. ------------------------------------------------------------------------ [2006-07-18 10:12:05] btherl at yahoo dot com dot au Description: ------------ Most functions return NULL if their arguments are invalid. This should be documented somewhere, perhaps in "Internal (built-in) functions". It may be useful to document it in the documentation for NULL itself. ------------------------------------------------------------------------ -- Edit this bug report at http://bugs.php.net/?id=38130&edit=1