RE: [PHP-DOC] return false if error

> -----Original Message----- > From: Hannes Magnusson [mailto:hannes.magnusson@gmail.com] > Sent: Wednesday, March 19, 2014 1:52 AM > To: Robert Stoll > Cc: PHP Documentation ML > Subject: Re: [PHP-DOC] return false if error > > On Tue, Mar 18, 2014 at 2:06 PM, Robert Stoll <php@tutteli.ch> wrote: > > Heya, > > > > We were discussing the scenario where a function returns false in an error case in a > > thread on the general mailing list. > > I always thought the documentation would use mixed as return type in such a situation > > (like in strpos) but others > > disagreed. > > > > For instance, Mike Ford told me: > >> It has always been policy in the documentation to specify only the substantive return > >> type(s) of a function > >> in the signature, and only mention return of "false" as an error indicator > >> in the description. There are > >> many, many examples of this in the manual, and I think it's unlikely the policy > >> will change any time soon. > > > > So my question is, what is your opinion on that topic? > > > > I already committed two patches to change the return type to mixed, since the functions > > also return false. > > I could revert them (or discard the commit, I do not know if this is possible - was made > > through edit.php.net). > > > > IMO the most important thing is that the documentation is consistent. Either change all > > such functions to mixed or > > change strpos to int (and probably further functions as well). > > Or we go a new path and add a construct which indicates that a function returns false as > > well. > > > > For instance: > > > > int! strpos ( string $haystack , mixed $needle [, int $offset = 0 ] ) > > > > where int! stands for int or false if an error occurs. > > > > Interesting. > > I don't know why or when strpos docs got changed to 'mixed', that > definitely is not how it was originally: > http://www.php.net/manual/en/about.prototypes.php > > The docs consistently white-lie with "on failure" return value, for > example; if you pass 10 arguments to strpos() it will not return > false, it will actually return null. > > This is true for ~98% of the documented functions. > > And we don't have the return type 'mixed' everywhere. I believe we > always document the return value of a successful execution of the > function, then mention "but on failure it can be blabla". > A successful case can also be a "failure value" (such as > not-found-but-that-doesn't-really-matter) - so the strpos() case is > very 50/50 if it should be int or mixed. > > > Your int! idea seems interesting. But its not always that a function > returns false on "successful execution of the function, but didn't > find what you wanted".. What happens in that case? > > -Hannes My idea would be, that the ! appendix would be used for functions which have written something like "Returns FALSE on error" such as strpos, strstr, fopen etc. Following the return type for those functions: strpos: int! strstr: string! fopen: resource! This way it would be clear at a glance that false is a valid return value and I should check for it