Fix/object is polyfill (#2793)

files/en-us/web/javascript/reference/global_objects/object/is/index.html

@@ -68,32 +68,39 @@ <h2 id="Description">Description</h2>
 
 <p>This is also <em>not</em> the same as being equal according to the
   {{jsxref("Operators/Comparison_Operators", "===", "#Identity")}} operator. The
-  <code>===</code> operator (and the <code>==</code> operator as well) treats the number
-  values <code>-0</code> and <code>+0</code> as equal and treats {{jsxref("Number.NaN")}}
-  as not equal to {{jsxref("NaN")}}.</p>
+  only difference between <code>Object.is()</code> and <code>===</code> is in
+  their treatment of signed zeroes and NaNs. For example, the <code>===</code>
+  operator (and the <code>==</code> operator) treats the number values <code>-0</code>
+  and <code>+0</code> as equal. Also, the <code>===</code> operator treats
+  {{jsxref("Number.NaN")}} and {{jsxref("NaN")}} as not equal.</p>
 
 <h2 id="Examples">Examples</h2>
 
 <h3 id="Using_Object.is">Using Object.is</h3>
 
-<pre class="brush: js">Object.is('foo', 'foo');     // true
-Object.is(window, window);   // true
-
-Object.is('foo', 'bar');     // false
-Object.is([], []);           // false
-
+<pre class="brush: js">// Case 1: Evaluation result is the same as using ===
+Object.is(25, 25);                // true
+Object.is('foo', 'foo');          // true
+Object.is('foo', 'bar');          // false
+Object.is(null, null);            // true
+Object.is(undefined, undefined);  // true
+Object.is(window, window);        // true
+Object.is([], []);                // false
 var foo = { a: 1 };
 var bar = { a: 1 };
-Object.is(foo, foo);         // true
-Object.is(foo, bar);         // false
-
-Object.is(null, null);       // true
-
-// Special Cases
-Object.is(0, -0);            // false
-Object.is(0n, -0n);          // true
-Object.is(-0, -0);           // true
-Object.is(NaN, 0/0);         // true
+Object.is(foo, foo);              // true
+Object.is(foo, bar);              // false
+
+// Case 2: Signed zero
+Object.is(0, -0);                 // false
+Object.is(+0, -0);                // false
+Object.is(-0, -0);                // true
+const n = 15;
+Object.is(0n, -0n);               // true
+
+// Case 3: NaN
+Object.is(NaN, 0/0);              // true
+Object.is(NaN, Number.NaN)        // true
 </pre>
 
 <h2 id="Polyfill">Polyfill</h2>
@@ -102,11 +109,16 @@ <h2 id="Polyfill">Polyfill</h2>
   Object.defineProperty(Object, "is", {
     value: function (x, y) {
       // SameValue algorithm
-      if (x === y) { // Steps 1-5, 7-10
-        // Steps 6.b-6.e: +0 != -0
+      if (x === y) {
+        // return true if x and y are not 0, OR
+        // if x and y are both 0 of the same sign.
+        // This checks for cases 1 and 2 above.
         return x !== 0 || 1 / x === 1 / y;
       } else {
-        // Step 6.a: NaN == NaN
+        // return true if both x AND y evaluate to NaN.
+        // The only possibility for a variable to not be strictly equal to itself
+        // is when that variable evaluates to NaN (example: Number.NaN, 0/0, NaN).
+        // This checks for case 3.
         return x !== x &amp;&amp; y !== y;
       }
     }