typings: add JSDoc typings for assert

PR-URL: https://github.com/nodejs/node/pull/38188
Reviewed-By: Bradley Farias <bradley.meck@gmail.com>
Reviewed-By: Michaël Zasso <targos@protonmail.com>

1 files changed, 123 insertions, 8 deletions

diff --git a/lib/assert.js b/lib/assert.js
index af6b1fc59a9..48daa56a29c 100644
--- a/lib/assert.js
+++ b/lib/assert.js
@@ -105,6 +105,14 @@ function innerFail(obj) {
   throw new AssertionError(obj);
 }
 
+/**
+ * @param {any} actual
+ * @param {any} expected
+ * @param {string | Error} [message]
+ * @param {string} [operator]
+ * @param {Function} [stackStartFn]
+ * @returns {never}
+ */
 function fail(actual, expected, message, operator, stackStartFn) {
   const argsLen = arguments.length;
 
@@ -384,14 +392,24 @@ function innerOk(fn, argLen, value, message) {
   }
 }
 
-// Pure assertion tests whether a value is truthy, as determined
-// by !!value.
+/**
+ * Pure assertion tests whether a value is truthy, as determined
+ * by !!value.
+ * @param {...any} args
+ * @returns {void}
+ */
 function ok(...args) {
   innerOk(ok, args.length, ...args);
 }
 assert.ok = ok;
 
-// The equality assertion tests shallow, coercive equality with ==.
+/**
+ * The equality assertion tests shallow, coercive equality with ==.
+ * @param {any} actual
+ * @param {any} expected
+ * @param {string | Error} [message]
+ * @returns {void}
+ */
 /* eslint-disable no-restricted-properties */
 assert.equal = function equal(actual, expected, message) {
   if (arguments.length < 2) {
@@ -409,8 +427,14 @@ assert.equal = function equal(actual, expected, message) {
   }
 };
 
-// The non-equality assertion tests for whether two objects are not
-// equal with !=.
+/**
+ * The non-equality assertion tests for whether two objects are not
+ * equal with !=.
+ * @param {any} actual
+ * @param {any} expected
+ * @param {string | Error} [message]
+ * @returns {void}
+ */
 assert.notEqual = function notEqual(actual, expected, message) {
   if (arguments.length < 2) {
     throw new ERR_MISSING_ARGS('actual', 'expected');
@@ -427,7 +451,13 @@ assert.notEqual = function notEqual(actual, expected, message) {
   }
 };
 
-// The equivalence assertion tests a deep equality relation.
+/**
+ * The deep equivalence assertion tests a deep equality relation.
+ * @param {any} actual
+ * @param {any} expected
+ * @param {string | Error} [message]
+ * @returns {void}
+ */
 assert.deepEqual = function deepEqual(actual, expected, message) {
   if (arguments.length < 2) {
     throw new ERR_MISSING_ARGS('actual', 'expected');
@@ -444,7 +474,13 @@ assert.deepEqual = function deepEqual(actual, expected, message) {
   }
 };
 
-// The non-equivalence assertion tests for any deep inequality.
+/**
+ * The deep non-equivalence assertion tests for any deep inequality.
+ * @param {any} actual
+ * @param {any} expected
+ * @param {string | Error} [message]
+ * @returns {void}
+ */
 assert.notDeepEqual = function notDeepEqual(actual, expected, message) {
   if (arguments.length < 2) {
     throw new ERR_MISSING_ARGS('actual', 'expected');
@@ -462,6 +498,14 @@ assert.notDeepEqual = function notDeepEqual(actual, expected, message) {
 };
 /* eslint-enable */
 
+/**
+ * The deep strict equivalence assertion tests a deep strict equality
+ * relation.
+ * @param {any} actual
+ * @param {any} expected
+ * @param {string | Error} [message]
+ * @returns {void}
+ */
 assert.deepStrictEqual = function deepStrictEqual(actual, expected, message) {
   if (arguments.length < 2) {
     throw new ERR_MISSING_ARGS('actual', 'expected');
@@ -478,6 +522,14 @@ assert.deepStrictEqual = function deepStrictEqual(actual, expected, message) {
   }
 };
 
+/**
+ * The deep strict non-equivalence assertion tests for any deep strict
+ * inequality.
+ * @param {any} actual
+ * @param {any} expected
+ * @param {string | Error} [message]
+ * @returns {void}
+ */
 assert.notDeepStrictEqual = notDeepStrictEqual;
 function notDeepStrictEqual(actual, expected, message) {
   if (arguments.length < 2) {
@@ -495,6 +547,13 @@ function notDeepStrictEqual(actual, expected, message) {
   }
 }
 
+/**
+ * The strict equivalence assertion tests a strict equality relation.
+ * @param {any} actual
+ * @param {any} expected
+ * @param {string | Error} [message]
+ * @returns {void}
+ */
 assert.strictEqual = function strictEqual(actual, expected, message) {
   if (arguments.length < 2) {
     throw new ERR_MISSING_ARGS('actual', 'expected');
@@ -510,6 +569,13 @@ assert.strictEqual = function strictEqual(actual, expected, message) {
   }
 };
 
+/**
+ * The strict non-equivalence assertion tests for any strict inequality.
+ * @param {any} actual
+ * @param {any} expected
+ * @param {string | Error} [message]
+ * @returns {void}
+ */
 assert.notStrictEqual = function notStrictEqual(actual, expected, message) {
   if (arguments.length < 2) {
     throw new ERR_MISSING_ARGS('actual', 'expected');
@@ -820,22 +886,51 @@ function expectsNoError(stackStartFn, actual, error, message) {
   throw actual;
 }
 
+/**
+ * Expects the function `promiseFn` to throw an error.
+ * @param {() => any} promiseFn
+ * @param {...any} [args]
+ * @returns {void}
+ */
 assert.throws = function throws(promiseFn, ...args) {
   expectsError(throws, getActual(promiseFn), ...args);
 };
 
+/**
+ * Expects `promiseFn` function or its value to reject.
+ * @param {() => Promise<any>} promiseFn
+ * @param {...any} [args]
+ * @returns {Promise<void>}
+ */
 assert.rejects = async function rejects(promiseFn, ...args) {
   expectsError(rejects, await waitForActual(promiseFn), ...args);
 };
 
+/**
+ * Asserts that the function `fn` does not throw an error.
+ * @param {() => any} fn
+ * @param {...any} [args]
+ * @returns {void}
+ */
 assert.doesNotThrow = function doesNotThrow(fn, ...args) {
   expectsNoError(doesNotThrow, getActual(fn), ...args);
 };
 
+/**
+ * Expects `fn` or its value to not reject.
+ * @param {() => Promise<any>} fn
+ * @param {...any} [args]
+ * @returns {Promise<void>}
+ */
 assert.doesNotReject = async function doesNotReject(fn, ...args) {
   expectsNoError(doesNotReject, await waitForActual(fn), ...args);
 };
 
+/**
+ * Throws `value` if the value is not `null` or `undefined`.
+ * @param {any} err
+ * @returns {void}
+ */
 assert.ifError = function ifError(err) {
   if (err !== null && err !== undefined) {
     let message = 'ifError got unwanted exception: ';
@@ -919,24 +1014,44 @@ function internalMatch(string, regexp, message, fn) {
   }
 }
 
+/**
+ * Expects the `string` input to match the regular expression.
+ * @param {string} string
+ * @param {RegExp} regexp
+ * @param {string | Error} [message]
+ * @returns {void}
+ */
 assert.match = function match(string, regexp, message) {
   internalMatch(string, regexp, message, match);
 };
 
+/**
+ * Expects the `string` input not to match the regular expression.
+ * @param {string} string
+ * @param {RegExp} regexp
+ * @param {string | Error} [message]
+ * @returns {void}
+ */
 assert.doesNotMatch = function doesNotMatch(string, regexp, message) {
   internalMatch(string, regexp, message, doesNotMatch);
 };
 
 assert.CallTracker = CallTracker;
 
-// Expose a strict only variant of assert
+/**
+ * Expose a strict only variant of assert.
+ * @param {...any} args
+ * @returns {void}
+ */
 function strict(...args) {
   innerOk(strict, args.length, ...args);
 }
+
 assert.strict = ObjectAssign(strict, assert, {
   equal: assert.strictEqual,
   deepEqual: assert.deepStrictEqual,
   notEqual: assert.notStrictEqual,
   notDeepEqual: assert.notDeepStrictEqual
 });
+
 assert.strict.strict = assert.strict;