Doc #52878 [Ana]: Incorrect return type

Edit report at http://bugs.php.net/bug.php?id=52878&edit=1 ID: 52878 Updated by: philip@php.net Reported by: jon at phpsitesolutions dot com Summary: Incorrect return type Status: Analyzed Type: Documentation Problem Package: Documentation problem PHP Version: Irrelevant Assigned To: markskilbeck Block user comment: N New Comment: 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. Previous Comments: ------------------------------------------------------------------------ [2010-09-20 17:57:29] philip@php.net 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. :) ------------------------------------------------------------------------ [2010-09-20 17:43:45] jon at phpsitesolutions dot com 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 ------------------------------------------------------------------------ [2010-09-20 12:42:15] markskilbeck@php.net 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. ------------------------------------------------------------------------ [2010-09-19 17:19:28] philip@php.net 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. ------------------------------------------------------------------------ [2010-09-19 15:35:54] markskilbeck@php.net I've updated the documentation to reflect your suggestion. ------------------------------------------------------------------------ The remainder of the comments for this report are too long. To view the rest of the comments, please view the bug report online at http://bugs.php.net/bug.php?id=52878 -- Edit this bug report at http://bugs.php.net/bug.php?id=52878&edit=1