FazBrowse GitHub Viewer | Trending |
URL:
| Home
Tools: [Download Repo ZIP]   [Original HTTPS Page]

assert: update comments · nodejs/node@7ecfe49 · GitHub

/ node Public

Commit 7ecfe49

Browse files
Kai Cataldo
authored and
MylesBorins
committed
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>
1 parent 4850b50 commit 7ecfe49

1 file changed

Lines changed: 42 additions & 32 deletions

File tree

‎lib/assert.js‎

Lines changed: 42 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -30,16 +30,16 @@ const util = require('util');
3030
const Buffer = require('buffer').Buffer;
3131
const pToString = (obj) => Object.prototype.toString.call(obj);
3232

33-
// 1. The assert module provides functions that throw
33+
// The assert module provides functions that throw
3434
// AssertionError's when particular conditions are not met. The
3535
// assert module must conform to the following interface.
3636

3737
const assert = module.exports = ok;
3838

39-
// 2. The AssertionError is defined in assert.
39+
// The AssertionError is defined in assert.
4040
// new assert.AssertionError({ message: message,
4141
// actual: actual,
42-
// expected: expected })
42+
// expected: expected });
4343

4444
assert.AssertionError = function AssertionError(options) {
4545
this.name = 'AssertionError';
@@ -75,7 +75,7 @@ function getMessage(self) {
7575
// other keys to the AssertionError's constructor - they will be
7676
// ignored.
7777

78-
// 3. All of the following functions must throw an AssertionError
78+
// All of the following functions must throw an AssertionError
7979
// when a corresponding condition is not met, with a message that
8080
// may be undefined if not provided. All assertion methods provide
8181
// both the actual and expected values to the assertion error for
@@ -94,7 +94,7 @@ function fail(actual, expected, message, operator, stackStartFunction) {
9494
// EXTENSION! allows for well behaved errors defined elsewhere.
9595
assert.fail = fail;
9696

97-
// 4. Pure assertion tests whether a value is truthy, as determined
97+
// Pure assertion tests whether a value is truthy, as determined
9898
// by !!guard.
9999
// assert.ok(guard, message_opt);
100100
// This statement is equivalent to assert.equal(true, !!guard,
@@ -106,24 +106,25 @@ function ok(value, message) {
106106
}
107107
assert.ok = ok;
108108

109-
// 5. The equality assertion tests shallow, coercive equality with
109+
// The equality assertion tests shallow, coercive equality with
110110
// ==.
111111
// assert.equal(actual, expected, message_opt);
112112

113113
assert.equal = function equal(actual, expected, message) {
114114
if (actual != expected) fail(actual, expected, message, '==', assert.equal);
115115
};
116116

117-
// 6. The non-equality assertion tests for whether two objects are not equal
118-
// with != assert.notEqual(actual, expected, message_opt);
117+
// The non-equality assertion tests for whether two objects are not
118+
// equal with !=.
119+
// assert.notEqual(actual, expected, message_opt);
119120

120121
assert.notEqual = function notEqual(actual, expected, message) {
121122
if (actual == expected) {
122123
fail(actual, expected, message, '!=', assert.notEqual);
123124
}
124125
};
125126

126-
// 7. The equivalence assertion tests a deep equality relation.
127+
// The equivalence assertion tests a deep equality relation.
127128
// assert.deepEqual(actual, expected, message_opt);
128129

129130
/* eslint-disable no-restricted-properties */
@@ -141,18 +142,22 @@ assert.deepStrictEqual = function deepStrictEqual(actual, expected, message) {
141142
};
142143

143144
function _deepEqual(actual, expected, strict, memos) {
144-
// 7.1. All identical values are equivalent, as determined by ===.
145+
// All identical values are equivalent, as determined by ===.
145146
if (actual === expected) {
146147
return true;
148+
149+
// If both values are instances of buffers, equivalence is
150+
// determined by comparing the values and ensuring the result
151+
// === 0.
147152
} else if (actual instanceof Buffer && expected instanceof Buffer) {
148153
return compare(actual, expected) === 0;
149154

150-
// 7.2. If the expected value is a Date object, the actual value is
155+
// If the expected value is a Date object, the actual value is
151156
// equivalent if it is also a Date object that refers to the same time.
152157
} else if (util.isDate(actual) && util.isDate(expected)) {
153158
return actual.getTime() === expected.getTime();
154159

155-
// 7.3 If the expected value is a RegExp object, the actual value is
160+
// If the expected value is a RegExp object, the actual value is
156161
// equivalent if it is also a RegExp object with the same source and
157162
// properties (`global`, `multiline`, `lastIndex`, `ignoreCase`).
158163
} else if (util.isRegExp(actual) && util.isRegExp(expected)) {
@@ -162,18 +167,18 @@ function _deepEqual(actual, expected, strict, memos) {
162167
actual.lastIndex === expected.lastIndex &&
163168
actual.ignoreCase === expected.ignoreCase;
164169

165-
// 7.4. Other pairs that do not both pass typeof value == 'object',
166-
// equivalence is determined by ==.
170+
// If both values are primitives, equivalence is determined by
171+
// == or, if checking for strict equivalence, ===.
167172
} else if ((actual === null || typeof actual !== 'object') &&
168173
(expected === null || typeof expected !== 'object')) {
169174
return strict ? actual === expected : actual == expected;
170175

171176
// If both values are instances of typed arrays, wrap their underlying
172-
// ArrayBuffers in a Buffer each to increase performance
177+
// ArrayBuffers in a Buffer to increase performance.
173178
// This optimization requires the arrays to have the same type as checked by
174-
// Object.prototype.toString (aka pToString). Never perform binary
175-
// comparisons for Float*Arrays, though, since e.g. +0 === -0 but their
176-
// bit patterns are not identical.
179+
// Object.prototype.toString (pToString). Never perform binary
180+
// comparisons for Float*Arrays, though, since +0 === -0 is true despite the
181+
// two values' bit patterns not being identical.
177182
} else if (ArrayBuffer.isView(actual) && ArrayBuffer.isView(expected) &&
178183
pToString(actual) === pToString(expected) &&
179184
!(actual instanceof Float32Array ||
@@ -185,7 +190,7 @@ function _deepEqual(actual, expected, strict, memos) {
185190
expected.byteOffset,
186191
expected.byteLength)) === 0;
187192

188-
// 7.5 For all other Object pairs, including Array objects, equivalence is
193+
// For all other Object pairs, including Array objects, equivalence is
189194
// determined by having the same number of owned properties (as verified
190195
// with Object.prototype.hasOwnProperty.call), the same set of keys
191196
// (although not necessarily the same order), equivalent values for every
@@ -215,7 +220,8 @@ function isArguments(object) {
215220
function objEquiv(a, b, strict, actualVisitedObjects) {
216221
if (a === null || a === undefined || b === null || b === undefined)
217222
return false;
218-
// if one is a primitive, the other must be same
223+
224+
// If one is a primitive, the other must be the same.
219225
if (util.isPrimitive(a) || util.isPrimitive(b))
220226
return a === b;
221227
if (strict && Object.getPrototypeOf(a) !== Object.getPrototypeOf(b))
@@ -227,20 +233,23 @@ function objEquiv(a, b, strict, actualVisitedObjects) {
227233
const ka = Object.keys(a);
228234
const kb = Object.keys(b);
229235
var key, i;
230-
// having the same number of owned properties (keys incorporates
231-
// hasOwnProperty)
236+
237+
// The pair must have the same number of owned properties (keys
238+
// incorporates hasOwnProperty).
232239
if (ka.length !== kb.length)
233240
return false;
234-
//the same set of keys (although not necessarily the same order),
241+
242+
// The pair must have the same set of keys (although not
243+
// necessarily in the same order).
235244
ka.sort();
236245
kb.sort();
237-
//~~~cheap key test
246+
// Cheap key test:
238247
for (i = ka.length - 1; i >= 0; i--) {
239248
if (ka[i] !== kb[i])
240249
return false;
241250
}
242-
//equivalent values for every corresponding key, and
243-
//~~~possibly expensive deep test
251+
// The pair must have equivalent values for every corresponding key.
252+
// Possibly expensive deep test:
244253
for (i = ka.length - 1; i >= 0; i--) {
245254
key = ka[i];
246255
if (!_deepEqual(a[key], b[key], strict, actualVisitedObjects))
@@ -249,7 +258,7 @@ function objEquiv(a, b, strict, actualVisitedObjects) {
249258
return true;
250259
}
251260

252-
// 8. The non-equivalence assertion tests for any deep inequality.
261+
// The non-equivalence assertion tests for any deep inequality.
253262
// assert.notDeepEqual(actual, expected, message_opt);
254263

255264
assert.notDeepEqual = function notDeepEqual(actual, expected, message) {
@@ -266,7 +275,7 @@ function notDeepStrictEqual(actual, expected, message) {
266275
}
267276

268277

269-
// 9. The strict equality assertion tests strict equality, as determined by ===.
278+
// The strict equality assertion tests strict equality, as determined by ===.
270279
// assert.strictEqual(actual, expected, message_opt);
271280

272281
assert.strictEqual = function strictEqual(actual, expected, message) {
@@ -275,8 +284,9 @@ assert.strictEqual = function strictEqual(actual, expected, message) {
275284
}
276285
};
277286

278-
// 10. The strict non-equality assertion tests for strict inequality, as
279-
// determined by !==. assert.notStrictEqual(actual, expected, message_opt);
287+
// The strict non-equality assertion tests for strict inequality, as
288+
// determined by !==.
289+
// assert.notStrictEqual(actual, expected, message_opt);
280290

281291
assert.notStrictEqual = function notStrictEqual(actual, expected, message) {
282292
if (actual === expected) {
@@ -298,7 +308,7 @@ function expectedException(actual, expected) {
298308
return true;
299309
}
300310
} catch (e) {
301-
// Ignore. The instanceof check doesn't work for arrow functions.
311+
// Ignore. The instanceof check doesn't work for arrow functions.
302312
}
303313

304314
if (Error.isPrototypeOf(expected)) {
@@ -356,7 +366,7 @@ function _throws(shouldThrow, block, expected, message) {
356366
}
357367
}
358368

359-
// 11. Expected to throw an error:
369+
// Expected to throw an error.
360370
// assert.throws(block, Error_opt, message_opt);
361371

362372
assert.throws = function(block, /*optional*/error, /*optional*/message) {

0 commit comments

Comments
 (0)
Back | FazBrowse Home | New Git URL