When reading the manual, I discovered by chance a function which is currently using the multiple datatypes syntax, and found it very usefull :
bool Phar::extractTo ( string $pathto [, string|array $files [, bool $overwrite = false ]] ) (seen at http://www.php.net/manual/en/phar.extractto.php) So I'm asking : Should the $files parameter be corrected to "mixed" ? Or isn't it a good idea to let doc writers use that syntax in some usefull cases, like the above example ? We can for example vote for a writing rule to avoid more than 2 or 3 concatened type otherwise the "mixed" should be used. 2011/10/6 Hannes Magnusson <hannes.magnus...@gmail.com> > I like the idea of being more precise.. But I think it would do more > harm then good in reality. > > like Peter pointed out, most functions return atleast 2 different > types, and where we currently list 'mixed' we would have to list even > more. > > A gentle lie, like we do today, is a fair compromise imo. > Sure, there are some functions that your IDE can't help you with, but > after few vists to the manual (or its unix man page) and you'll get > the exact details, with better info and even and example and history, > that your IDE doesn't provide.. > > -Hannes > > > On Wed, Oct 5, 2011 at 12:04, Geoffray Warnants <gwarna...@gmail.com> > wrote: > > 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 > >> > > > > > >
