Re: Doc #64909 [Opn->Nab]: array_merge - Return value documentation incorrect/misleading

(Cross-posted from the bugspam list.) On 25 May 2013 12:10, <salathe@php.net> wrote: > This behaviour is common across almost all functions, and we have a > note to that effect on the "Internal (built-in) functions" page > (http://php.net/manual/en/functions.internal.php): > > Note: 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 of the function is undefined. In this case > it will likely return NULL but this is just a convention, and > cannot be relied upon. > > The documentation team have discussed this in the past and > determined that it would be impractical and confusing for readers > if such a note were to be added to every-single-function in the manual. I know I've previously signed up for this line of thought too, but I've been thinking about that a bit, and I wonder if we are actually right here. As things stand, the return values section for almost all functions is actually incomplete — I think it's a reasonable expectation that reference pages should be reasonably self-contained, and right now they're not: our description of inputs and outputs usually doesn't cover the rather common case where an input variable is the wrong type for whatever reason. I think we should define an entity that could be the final paragraph of most return value sections that reads something like: "Returns NULL if parameters of the wrong type are provided." Actually adding that to function pages could probably be done in a semi-automated manner — it's not particularly hard to test if an internal function does actually exhibit the NULL on incorrect type behaviour. Does anyone have any thoughts for or against? I don't mind doing the work next time I have some free time on a Sunday, but I need to know if I'm not the only one who thinks it's a worthwhile change before doing so. :) Adam PS: Sorry for picking on your comment, Peter. This has been percolating in my head for a while, so it's nothing personal!