Merge pull request #2848 from jgonggrijp/comparison-operator-doc

Closes #2846.

index.html

@@ -382,6 +382,12 @@
       </a>
     </div>
 
+    <div class="searchable_section">
+      <a class="toc_title" href="#notes">
+        Notes
+      </a>
+    </div>
+
     <div class="searchable_section">
       <a class="toc_title" href="#changelog">
         Change Log
@@ -734,6 +740,8 @@ <h2 id="collections">Collection Functions (Arrays or Objects)</h2>
         criterion by which the value is ranked. <i>-Infinity</i> is returned
         if <b>list</b> is empty, so an <a href="#isEmpty">isEmpty</a> guard
         may be required. Non-numerical values in <b>list</b> will be ignored.
+        This function uses operator <tt>&lt;</tt>
+        (<a href="#relational-operator-note">note</a>).
       </p>
       <pre>
 var stooges = [{name: 'moe', age: 40}, {name: 'larry', age: 50}, {name: 'curly', age: 60}];
@@ -749,6 +757,8 @@ <h2 id="collections">Collection Functions (Arrays or Objects)</h2>
         criterion by which the value is ranked. <i>Infinity</i> is returned
         if <b>list</b> is empty, so an <a href="#isEmpty">isEmpty</a> guard
         may be required. Non-numerical values in <b>list</b> will be ignored.
+        This function uses operator <tt>&lt;</tt>
+        (<a href="#relational-operator-note">note</a>).
       </p>
       <pre>
 var numbers = [10, 5, 100, 2, 1000];
@@ -762,7 +772,8 @@ <h2 id="collections">Collection Functions (Arrays or Objects)</h2>
         Returns a (stably) sorted copy of <b>list</b>, ranked in ascending
         order by the results of running each value through <a href="#iteratee"><b>iteratee</b></a>.
         iteratee may also be the string name of the property to sort by (eg.
-        <tt>length</tt>).
+        <tt>length</tt>). This function uses operator <tt>&lt;</tt>
+        (<a href="#relational-operator-note">note</a>).
       </p>
       <pre>
 _.sortBy([1, 2, 3, 4, 5, 6], function(num){ return Math.sin(num); });
@@ -1091,7 +1102,9 @@ <h2 id="arrays">Array Functions</h2>
         large array, and you know that the array is already sorted, pass <tt>true</tt>
         for <b>isSorted</b> to use a faster binary search ... or, pass a number as
         the third argument in order to look for the first matching value in the
-        array after the given index.
+        array after the given index. If <tt>isSorted</tt> is <tt>true</tt>,
+        this function uses operator <tt>&lt;</tt>
+        (<a href="#relational-operator-note">note</a>).
       </p>
       <pre>
 _.indexOf([1, 2, 3], 2);
@@ -1117,7 +1130,9 @@ <h2 id="arrays">Array Functions</h2>
         <i>should</i> be inserted into the <b>array</b> in order to maintain the <b>array</b>'s
         sorted order. If an <a href="#iteratee"><b>iteratee</b></a> function is provided,
         it will be used to compute the sort ranking of each value, including the <b>value</b> you pass.
-        The iteratee may also be the string name of the property to sort by (eg. <tt>length</tt>).
+        The iteratee may also be the string name of the property to sort by
+        (eg. <tt>length</tt>). This function uses operator <tt>&lt;</tt>
+        (<a href="#relational-operator-note">note</a>).
       </p>
       <pre>
 _.sortedIndex([10, 20, 30, 40, 50], 35);
@@ -2417,6 +2432,50 @@ <h2 id="links">Links &amp; Suggested Reading</h2>
         collection of functional helpers for Python, partially inspired by Underscore.
       </p>
 
+      <h2 id="notes">Notes</h2>
+
+      <p id="relational-operator-note">
+        <b class="header">On the use of <tt>&lt;</tt> in Underscore</b>
+        <br>
+        Underscore functions that depend on ordering, such as
+        <a href="#sortBy"><tt>_.sortBy</tt></a> and
+        <a href="#sortedIndex"><tt>_.sortedIndex</tt></a>, use
+        JavaScript&rsquo;s built-in
+        <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Comparison_Operators#Relational_operators">relational operators</a>,
+        specifically the &ldquo;less than&rdquo; operator <tt>&lt;</tt>. It is
+        important to understand that these operators are only meaningful for
+        numbers and strings. You can throw any value to them, but JavaScript
+        will convert the operands to string or number first before performing
+        the actual comparison. If you pass an operand that
+        cannot be meaningfully converted to string or number, it ends up being
+        <tt>NaN</tt> by default. This value is unsortable.
+      </p>
+      <p>
+        Ideally, the values that you are sorting should either be all
+        (meaningfully convertible to) strings or all (meaningfully convertible
+        to) numbers. If this is not the case, you have two options:
+        <ul>
+          <li>
+            <a href="#filter"><tt>_.filter</tt></a> out all unsortable values
+            first.
+          </li>
+          <li>
+            Pick a target type, i.e., either string or number, and pass an
+            <a href="#iteratee"><tt>iteratee</tt></a> to your Underscore
+            function that will convert its argument to a sensible instance of
+            the target type. For example, if you have an array of numbers that
+            you want to sort and that may occasionally contain <tt>null</tt> or
+            <tt>undefined</tt>, you can control whether you want to sort these
+            before or after all numbers by passing an <tt>iteratee</tt> to
+            <tt>_.sortBy</tt> that returns <tt>-Infinity</tt> or
+            <tt>+Infinity</tt> for such values, respectively. Or maybe you want
+            to treat them as zeros; it is up to you. The same <tt>iteratee</tt>
+            can also be passed to other Underscore functions to ensure that the
+            behavior is consistent.
+          </li>
+        </ul>
+      </p>
+
       <h2 id="changelog">Change Log</h2>
 
       <p id="1.10.2">