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