I've updated the documentation to reflect your suggestion.

Technically it should be 'array' and not 'mixed' as otherwise every 
method/function in the manual would be 'mixed'. The prototype includes what may 
happen on success.

That is, unless false is returned when no items are found (as opposed to some 
error or fail). I assume an empty array is returned in that case but if not then 
mixed is perfect. Either way, it could be clarified.

Hi, Phillip.

I wasn't aware that only the success value should be documented. Anyway, most of the documentation I've seen shows functions that return FALSE on failure and any other value on success as a mixed return. This makes sense to me. However, getMultiByKey does return FALSE only on error, it seems.

Whichever is the correct approach, I leave up to better minds @php.net (such as 
yourselves) to decide.
The main issue is to ensure that the "void" return type is corrected to at least 
array or mixed, as either would be more accurate than "void".


Just a suggestion regarding the array vs mixed debate, there does seem to be a 
definite inconsistency across PHP docs, so it would be nice to see a decision 
and then likely a process would need to be put in place to review the return 
types going forward, to make consistent?

Or maybe I'm just overthinking things :-)

Cheers

The official stance is to designate the return type as the 'on success' values. If 
this were not the case, then every return value would be either 'mixed' or 'bool' 
with that assuming we ignore NULL. The 'return role' then may say something like  
'returns false on failure'

In the case of this function, it should be array.

As far as being consistent, that's always a goal. :)

And to be clear, success means the function executed without bailing out. So fail 
could mean, for example, passing in the wrong type as a parameter, or using the 
function incorrectly.

This bug has been fixed in the documentation's XML sources. Since the
online and downloadable versions of the documentation need some time
to get updated, we would like to ask you to be a bit patient.

Thank you for the report, and for helping us make our documentation better.