Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:70098
Mailing-List: contact internals-help@lists.php.net; run by ezmlm
Received-SPF: pass (pb1.pair.com: domain gmail.com designates 74.125.82.171 as permitted sender)
Message-ID: <52812873.70406@gmail.com>
Date: Mon, 11 Nov 2013 18:56:51 +0000
User-Agent: Mozilla/5.0 (Windows NT 6.1; WOW64; rv:24.0) Gecko/20100101 Thunderbird/24.1.0
MIME-Version: 1.0
To: internals@lists.php.net
References: <CAGa2bXY4mS27qAfD6U03pxFyRNyK1AAowY3D0MxeqcjNQSKqRw@mail.gmail.com> <527DF228.1080108@sugarcrm.com> <CAGa2bXbqR7Cg_pmq0VnZhMHzXfTrR7ve1yYKoeiEf88Oght2tg@mail.gmail.com> <416659913.20131110035553@cypressintegrated.com> <CAGa2bXYf-CxH+WjOktvYRRNnb_3spNPg9=+SrHNC_bGUe=PHFQ@mail.gmail.com> <127298508.20131110042057@cypressintegrated.com> <CAGa2bXZtTqsCARTEG5-GArjn9Qdt2sHAFjhVYMLGeVVn5Nbq_Q@mail.gmail.com> <97776909.20131110045342@cypressintegrated.com> <CAGa2bXYm+2SfF932EF0bht6h1eU6HOhM-7c43q4H0NMP6znQDg@mail.gmail.com> <527FDE61.70102@gmail.com> <346085145.20131110145938@cypressintegrated.com>
In-Reply-To: <346085145.20131110145938@cypressintegrated.com>
Content-Type: text/plain; charset=ISO-8859-1; format=flowed
Content-Transfer-Encoding: 7bit
Subject: Re: [PHP-DEV] [RFC] Comparison and conversion inconsistency - need
 more info
From: rowan.collins@gmail.com (Rowan Collins)

Sanford Whiteman wrote (on 10/11/2013):
>> I didn't immediately spot it, but the word "comparable" next to each
>> argument in the Parameters section is linked to the comparison operators
>> page. It mgiht be an idea to add it to the See Also section as well, to
>> make it more visible.
> Don't see how this has any more of a visibility problem than `mixed`
> type params for other functions.

Well, "mixed" is a pseudo-type used consistently throughout the manual 
and linked to an explanation of the term here: 
http://php.net/manual/en/language.pseudo-types.php

The fact that a particular value has to be "comparable", on the other 
hand, doesn't really tell you how the different parameters interact, so 
the link has poor "information scent" - I'd probably click there if my 
values were being rejected, but not if certain *combinations* were 
behaving "oddly". The reason I suggested a "See also" is that it's 
unobtrusive, but can include clear text as to why you might want to look 
at it.

Actually, now I look, most of the other text specifically talks only 
about numeric (e.g. the "Return Values" section: "min() returns the 
numerically lowest of the parameter values" which is just plain wrong) 
or alphanumeric (in the "Note:" within the "Description" section) 
values. This could easily reinforce the kind of mistake made here of 
thinking that everything is cast to int (or possibly string) before 
comparison.

> IMO, it's a nice convenience that the hyperlink is there, but not even
> necessary. min(<list>) should be assumed to be sort(<array>) and
> unshift(<array>). Sort --> comparison --> comparison rules apply.

That's certainly an intuitive explanation, but it's by no means the only 
way of implementing or imagining the underlying algorithm. It would be 
one way of making clear what happens though: "This function is 
equivalent to sorting the items based on the [link]standard type 
comparisons[/link] and returning the first item."

You don't have to think the current documentation is awful to find ways 
of improving it.

Regards,
-- 
Rowan Collins
[IMSoP]