I think the other thing that's missing here is that there's nearly often a conflict between the actual behavior of a function and the overly optimistic document

I think the other thing that's missing here is that there's nearly often a conflict between the actual behavior of a function and the overly optimistic documentation which is then amended by a series of caveats. I think i could forgive php more for behaving (and being named & structured) wildly inconsistently were it not that the documentation tries to make up for this by pretending this is actually not the case. So not only do you have this issue where the behavior of a function may be erratic but the documentation attempts to gloss over the issue by describing a function's most optimistic outcome rather than its actual behavior. Any behavioral caveats are left in the Notes section which in any other language documentation is reserved for "not thread safe" or "uses an easily guessable seed" or "execution blocks network access". Instead the Notes are used to explain "optional arguments not included change the behavior of this method to behave like this other one, but give no warning or otherwise visible indication of error." The whole "php is defensive programming" statement holds because you can't trust the documentation to be upfront about inconsistent behavior.