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
>
