assert: update comments

Remove the numbers from the comments to make it clear that
assert does not follow the
[CJS spec](http://wiki.commonjs.org/wiki/Unit_Testing/1.0).
Additionally, clean up the existing comments for consistent
formatting/language and ease of reading.

PR-URL: #10579
Fixes: #9063
Reviewed-By: Rich Trott <rtrott@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com>
Reviewed-By: Michael Dawson <michael_dawson@ca.ibm.com>

Author: Kai Cataldo

lib/assert.js

@@ -30,16 +30,16 @@ const util = require('util');
 const Buffer = require('buffer').Buffer;
 const pToString = (obj) => Object.prototype.toString.call(obj);
 
-// 1. The assert module provides functions that throw
+// The assert module provides functions that throw
 // AssertionError's when particular conditions are not met. The
 // assert module must conform to the following interface.
 
 const assert = module.exports = ok;
 
-// 2. The AssertionError is defined in assert.
+// The AssertionError is defined in assert.
 // new assert.AssertionError({ message: message,
 //                             actual: actual,
-//                             expected: expected })
+//                             expected: expected });
 
 assert.AssertionError = function AssertionError(options) {
   this.name = 'AssertionError';
@@ -75,7 +75,7 @@ function getMessage(self) {
 // other keys to the AssertionError's constructor - they will be
 // ignored.
 
-// 3. All of the following functions must throw an AssertionError
+// All of the following functions must throw an AssertionError
 // when a corresponding condition is not met, with a message that
 // may be undefined if not provided.  All assertion methods provide
 // both the actual and expected values to the assertion error for
@@ -94,7 +94,7 @@ function fail(actual, expected, message, operator, stackStartFunction) {
 // EXTENSION! allows for well behaved errors defined elsewhere.
 assert.fail = fail;
 
-// 4. Pure assertion tests whether a value is truthy, as determined
+// Pure assertion tests whether a value is truthy, as determined
 // by !!guard.
 // assert.ok(guard, message_opt);
 // This statement is equivalent to assert.equal(true, !!guard,
@@ -106,24 +106,25 @@ function ok(value, message) {
 }
 assert.ok = ok;
 
-// 5. The equality assertion tests shallow, coercive equality with
+// The equality assertion tests shallow, coercive equality with
 // ==.
 // assert.equal(actual, expected, message_opt);
 
 assert.equal = function equal(actual, expected, message) {
   if (actual != expected) fail(actual, expected, message, '==', assert.equal);
 };
 
-// 6. The non-equality assertion tests for whether two objects are not equal
-// with != assert.notEqual(actual, expected, message_opt);
+// The non-equality assertion tests for whether two objects are not
+// equal with !=.
+// assert.notEqual(actual, expected, message_opt);
 
 assert.notEqual = function notEqual(actual, expected, message) {
   if (actual == expected) {
     fail(actual, expected, message, '!=', assert.notEqual);
   }
 };
 
-// 7. The equivalence assertion tests a deep equality relation.
+// The equivalence assertion tests a deep equality relation.
 // assert.deepEqual(actual, expected, message_opt);
 
 assert.deepEqual = function deepEqual(actual, expected, message) {
@@ -139,18 +140,22 @@ assert.deepStrictEqual = function deepStrictEqual(actual, expected, message) {
 };
 
 function _deepEqual(actual, expected, strict, memos) {
-  // 7.1. All identical values are equivalent, as determined by ===.
+  // All identical values are equivalent, as determined by ===.
   if (actual === expected) {
     return true;
+
+  // If both values are instances of buffers, equivalence is
+  // determined by comparing the values and ensuring the result
+  // === 0.
   } else if (actual instanceof Buffer && expected instanceof Buffer) {
     return compare(actual, expected) === 0;
 
-  // 7.2. If the expected value is a Date object, the actual value is
+  // If the expected value is a Date object, the actual value is
   // equivalent if it is also a Date object that refers to the same time.
   } else if (util.isDate(actual) && util.isDate(expected)) {
     return actual.getTime() === expected.getTime();
 
-  // 7.3 If the expected value is a RegExp object, the actual value is
+  // If the expected value is a RegExp object, the actual value is
   // equivalent if it is also a RegExp object with the same source and
   // properties (`global`, `multiline`, `lastIndex`, `ignoreCase`).
   } else if (util.isRegExp(actual) && util.isRegExp(expected)) {
@@ -160,18 +165,18 @@ function _deepEqual(actual, expected, strict, memos) {
            actual.lastIndex === expected.lastIndex &&
            actual.ignoreCase === expected.ignoreCase;
 
-  // 7.4. Other pairs that do not both pass typeof value == 'object',
-  // equivalence is determined by ==.
+  // If both values are primitives, equivalence is determined by
+  // == or, if checking for strict equivalence, ===.
   } else if ((actual === null || typeof actual !== 'object') &&
              (expected === null || typeof expected !== 'object')) {
     return strict ? actual === expected : actual == expected;
 
   // If both values are instances of typed arrays, wrap their underlying
-  // ArrayBuffers in a Buffer each to increase performance
+  // ArrayBuffers in a Buffer to increase performance.
   // This optimization requires the arrays to have the same type as checked by
-  // Object.prototype.toString (aka pToString). Never perform binary
-  // comparisons for Float*Arrays, though, since e.g. +0 === -0 but their
-  // bit patterns are not identical.
+  // Object.prototype.toString (pToString). Never perform binary
+  // comparisons for Float*Arrays, though, since +0 === -0 is true despite the
+  // two values' bit patterns not being identical.
   } else if (ArrayBuffer.isView(actual) && ArrayBuffer.isView(expected) &&
              pToString(actual) === pToString(expected) &&
              !(actual instanceof Float32Array ||
@@ -184,7 +189,7 @@ function _deepEqual(actual, expected, strict, memos) {
                                         expected.byteOffset +
                                         expected.byteLength)) === 0;
 
-  // 7.5 For all other Object pairs, including Array objects, equivalence is
+  // For all other Object pairs, including Array objects, equivalence is
   // determined by having the same number of owned properties (as verified
   // with Object.prototype.hasOwnProperty.call), the same set of keys
   // (although not necessarily the same order), equivalent values for every
@@ -214,7 +219,8 @@ function isArguments(object) {
 function objEquiv(a, b, strict, actualVisitedObjects) {
   if (a === null || a === undefined || b === null || b === undefined)
     return false;
-  // if one is a primitive, the other must be same
+
+  // If one is a primitive, the other must be the same.
   if (util.isPrimitive(a) || util.isPrimitive(b))
     return a === b;
   if (strict && Object.getPrototypeOf(a) !== Object.getPrototypeOf(b))
@@ -226,20 +232,23 @@ function objEquiv(a, b, strict, actualVisitedObjects) {
   const ka = Object.keys(a);
   const kb = Object.keys(b);
   var key, i;
-  // having the same number of owned properties (keys incorporates
-  // hasOwnProperty)
+
+  // The pair must have the same number of owned properties (keys
+  // incorporates hasOwnProperty).
   if (ka.length !== kb.length)
     return false;
-  //the same set of keys (although not necessarily the same order),
+
+  // The pair must have the same set of keys (although not
+  // necessarily in the same order).
   ka.sort();
   kb.sort();
-  //~~~cheap key test
+  // Cheap key test:
   for (i = ka.length - 1; i >= 0; i--) {
     if (ka[i] !== kb[i])
       return false;
   }
-  //equivalent values for every corresponding key, and
-  //~~~possibly expensive deep test
+  // The pair must have equivalent values for every corresponding key.
+  // Possibly expensive deep test:
   for (i = ka.length - 1; i >= 0; i--) {
     key = ka[i];
     if (!_deepEqual(a[key], b[key], strict, actualVisitedObjects))
@@ -248,7 +257,7 @@ function objEquiv(a, b, strict, actualVisitedObjects) {
   return true;
 }
 
-// 8. The non-equivalence assertion tests for any deep inequality.
+// The non-equivalence assertion tests for any deep inequality.
 // assert.notDeepEqual(actual, expected, message_opt);
 
 assert.notDeepEqual = function notDeepEqual(actual, expected, message) {
@@ -265,7 +274,7 @@ function notDeepStrictEqual(actual, expected, message) {
 }
 
 
-// 9. The strict equality assertion tests strict equality, as determined by ===.
+// The strict equality assertion tests strict equality, as determined by ===.
 // assert.strictEqual(actual, expected, message_opt);
 
 assert.strictEqual = function strictEqual(actual, expected, message) {
@@ -274,8 +283,9 @@ assert.strictEqual = function strictEqual(actual, expected, message) {
   }
 };
 
-// 10. The strict non-equality assertion tests for strict inequality, as
-// determined by !==.  assert.notStrictEqual(actual, expected, message_opt);
+// The strict non-equality assertion tests for strict inequality, as
+// determined by !==.
+// assert.notStrictEqual(actual, expected, message_opt);
 
 assert.notStrictEqual = function notStrictEqual(actual, expected, message) {
   if (actual === expected) {
@@ -297,7 +307,7 @@ function expectedException(actual, expected) {
       return true;
     }
   } catch (e) {
-    // Ignore.  The instanceof check doesn't work for arrow functions.
+    // Ignore. The instanceof check doesn't work for arrow functions.
   }
 
   if (Error.isPrototypeOf(expected)) {
@@ -355,7 +365,7 @@ function _throws(shouldThrow, block, expected, message) {
   }
 }
 
-// 11. Expected to throw an error:
+// Expected to throw an error.
 // assert.throws(block, Error_opt, message_opt);
 
 assert.throws = function(block, /*optional*/error, /*optional*/message) {