Re: Return type declaration and &return.falseforfailure;

On 05.12.2017 at 11:15, Andrew Gromov wrote: > I see many changes from anonymous users like this: > >  - <type>int</type><methodname>preg_match</methodname> >  + <type>int|bool</type><methodname>preg_match</methodname> > > > or this: > >  - <type>int</type><methodname>preg_match_all</methodname> >  + <type>mixed</type><methodname>preg_match_all</methodname> > > > Formally them correct, but by spirit them is bad (imho). > Accept or reject them? In my opinion, we need a decision here ASAP, since we're already going round in circles. See, for instance, stristr(): r343177 changed the return type to mixed, but r343898 changed it back to string a few months later. This is bad per se, but with regard to the translations it's evil – "oh, they've changed the return type – let's postpone updating the translation until they'll change it back" … Explicitly documenting the potential null return type (due to parameter parsing type failures) does not make sense, since this issue is already generally documented, and the null return value is merely a convention, which might change in the future[1]. Personally, I don't like documenting the return type as mixed for such cases, since this doesn't appear to be helpful for our users. For instance, preg_match() either returns an int or false (I'm ignoring the potential null from here on). Note that it's false, not even a general bool. So it might make sense to document <type>int|false</type> (or maybe using the respective Docbook 5.2 enhancement <type>int</type><type>false</type>), which appears to be particularly useful for static code analyzers. The other option would be to document <type>int</type>, mentioning the possible false only in the "return values" section. I deliberately avoid to mention potential changes to the actual implementations of these functions, since even if those will happen, we'd still have to document the current behavior. Anyhow, this is just my opinion, and I'd like to hear yours! [1] <http://www.php.net/manual/en/functions.internal.php> -- Christoph M. Becker