Doc #52878 [Ana->Csd]: Incorrect return type

Edit report at http://bugs.php.net/bug.php?id=52878&edit=1 ID: 52878 Updated by: markskilbeck@php.net Reported by: jon at phpsitesolutions dot com Summary: Incorrect return type -Status: Analyzed +Status: Closed Type: Documentation Problem Package: Documentation problem PHP Version: Irrelevant Assigned To: markskilbeck Block user comment: N New Comment: 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. Previous Comments: ------------------------------------------------------------------------ [2010-10-24 18:57:29] markskilbeck@php.net Automatic comment from SVN on behalf of markskilbeck Revision: http://svn.php.net/viewvc/?view=revision&revision=304707 Log: #52878 - Fix return type; now 'array' instead of 'mixed' ------------------------------------------------------------------------ [2010-09-20 18:15:15] philip@php.net 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. ------------------------------------------------------------------------ [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. ------------------------------------------------------------------------ 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