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
> >> >
> >
> >
>

Reply via email to