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
