Re: return false if error

I tend to use this type of annotation in my docblocks: @return int|bool On Wed, Mar 19, 2014 at 12:39 PM, Robert Stoll <php@tutteli.ch> wrote: > > -----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 > >