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 ?

Regards,
Geoffray

Reply via email to