"most functions" : Returning NULL is not a general rule, thus it shoulnd't IMO be documented globally such as in the docs for NULL.

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.

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 ;-) 

Thanks for your thoughtful reply!

I think it's too much to add to every page.  No other language that I'm aware of documents the return values when given nonsense arguments.  They just say "The result is undefined."

It can be mystifying though, to have a ($ret === false) test fail when a function says it returns false on failure.  For this reason, I think it's worth saying somewhere that you can't expect anything if you give unexpected parameters.

I just discovered that the common functions fopen() and fclose() return false when given strange parameters.  And exec() returns "" when given an array or an integer.  exec(5000) doesn't even generate a warning.  Maybe NULL is not the most common return value?

My next try:

"Note that if the parameters given to a function are not what it expects, such as passing an array where a string is expected, the return value is undefined."

Saying "not the correct type" may not be good enough, since functions like fopen() need specific values of a specific type.

Sorry, exec() behaves more normally in php 5.1.4.  Ignore that part :)

PHP6 will introduce array type hinting to internal 
functions which will cause E_RECOVERABLE_ERROR on failure 
rather than E_WARNING...

This has now been documented and will show up when the manual is next built, thank you for the bug report :)

Diff is as follows:
http://cvs.php.net/viewvc.cgi/phpdoc/en/language/functions.xml?r1=1.62&r2=1.63