Hi Peter,
Yes, NULL values are very useful to know.
I just would add a precision : I don't want the "mixed" datatype to be
compeltely eradicated ! It could be judicious when the data type is
unpredictable, like in this function :
mixed|NULL array_pop (array &$array)
Regards,
Geoffray
2011/10/5 Peter Cowburn <petercowb...@gmail.com>
> Hi Geoffray,
>
> On 5 October 2011 10:29, Geoffray Warnants <gwarna...@gmail.com> wrote:
> > Dear PHPDOC Team,
> >
> > I would like to hear what you have to say about the convention actually
> used
> > in the PHP manual to
> > describe "mixed" values, I mean parameters (or return values) that could
> > have multiple datatypes.
> >
> > I don't like them so much for some reasons :
> > - The first think I read about a PHP function in the documentation is its
> > prototype. The prototype must describe input/output parameters as
> accurately
> > as possible (data type, default value, reference, ...) without having to
> > read the full attached doc.
> > - The PHP Documentation is often integrated in latest IDE. They instantly
> > show us nice help tooltips with the complete protoype of the PHP function
> we
> > are writing. But it don't tell me what's expected if some parameters are
> > "mixed".
> >
> > As an example, I will use strpos() function :
> >
> > The documentation says strpos returns an integer or FALSE if an error
> > occured. OK, but the prototype only tells me it returns an integer :
> >
> > int strpos ( string $haystack , mixed $needle [, int $offset = 0 ] )
> >
> > To be correct and respect the current convention, we could use the
> "mixed"
> > type as the return value.
> >
> > mixed strpos ( string $haystack , mixed $needle [, int $offset = 0 ] )
> >
> > It is then strictly more accurate but less intuitive : when I read that
> > prototype without the attached doc (like it is in some IDE), I'm not able
> to
> > see clearly the return type I will get : even more confusing !
> > So why not to use the convention used in some documentation tools like
> > phpDocumentor : a value can have multiple datatypes by delimiting them
> with
> > the pipe. So it will become :
> >
> > int|bool strpos ( string $haystack , mixed $needle [, int $offset = 0 ] )
> >
> > It is great by not fully intuitive : when reading "bool" in my IDE I may
> > think the function will also return "true" in some case...
> > So, a custom convention I suggest would be :
> >
> > int|false strpos ( string $haystack , mixed $needle [, int $offset = 0 ]
> )
> >
> > Assuming many PHP functions returns the bool FALSE only if an error
> occured,
> > I think that syntax tells me everything I need to know. The same logic
> could
> > be applied to parameters.
> >
> > What do you think ?
>
> Most functions will also return NULL if you provide invalid
> parameters, for example, strpos("cake"). Should the prototype reflect
> this too? int|false|null strpos ( ...
>
>
> >
> > Regards,
> > Geoffray
> >
>
