lib: replace functions with callbacks on jsdoc

lib/internal/validators.js

@@ -34,10 +34,20 @@ const {
 } = require('internal/util/types');
 const { signals } = internalBinding('constants').os;
 
+/**
+ * @callback isInt32
+ * @param {number} value
+ * @returns {boolean}
+ */
 function isInt32(value) {
   return value === (value | 0);
 }
 
+/**
+ * @callback isUint32
+ * @param {number} value
+ * @returns {boolean}
+ */
 function isUint32(value) {
   return value === (value >>> 0);
 }
@@ -71,13 +81,15 @@ function parseFileMode(value, name, def) {
 }
 
 /**
- * @function validateInteger
+ * @callback validateInteger
  * @param {*} value
  * @param {string} name
  * @param {number} [min]
  * @param {number} [max]
  * @returns {asserts value is number}
  */
+
+/** @type {validateInteger} */
 const validateInteger = hideStackFrames(
   (value, name, min = NumberMIN_SAFE_INTEGER, max = NumberMAX_SAFE_INTEGER) => {
     if (typeof value !== 'number')
@@ -90,13 +102,15 @@ const validateInteger = hideStackFrames(
 );
 
 /**
- * @function validateInt32
+ * @callback validateInt32
  * @param {*} value
  * @param {string} name
  * @param {number} [min]
  * @param {number} [max]
  * @returns {asserts value is number}
  */
+
+/** @type {validateInt32} */
 const validateInt32 = hideStackFrames(
   (value, name, min = -2147483648, max = 2147483647) => {
     // The defaults for min and max correspond to the limits of 32-bit integers.
@@ -113,13 +127,15 @@ const validateInt32 = hideStackFrames(
 );
 
 /**
- * @function validateUint32
+ * @callback validateUint32
  * @param {*} value
  * @param {string} name
  * @param {number} [min]
  * @param {number} [max]
  * @returns {asserts value is number}
  */
+
+/** @type {validateUint32} */
 const validateUint32 = hideStackFrames((value, name, positive = false) => {
   if (typeof value !== 'number') {
     throw new ERR_INVALID_ARG_TYPE(name, 'number', value);
@@ -136,48 +152,50 @@ const validateUint32 = hideStackFrames((value, name, positive = false) => {
 });
 
 /**
- * @function validateString
+ * @callback validateString
  * @param {*} value
  * @param {string} name
  * @returns {asserts value is string}
  */
+
+/** @type {validateString} */
 function validateString(value, name) {
   if (typeof value !== 'string')
     throw new ERR_INVALID_ARG_TYPE(name, 'string', value);
-
-  return true;
 }
 
 /**
- * @function validateNumber
+ * @callback validateNumber
  * @param {*} value
  * @param {string} name
  * @param {number} [min]
  * @param {number} [max]
  * @returns {asserts value is number}
  */
+
+/** @type {validateNumber} */
 function validateNumber(value, name, min = undefined, max) {
   if (typeof value !== 'number')
     throw new ERR_INVALID_ARG_TYPE(name, 'number', value);
 
   if ((min != null && value < min) || (max != null && value > max) ||
-      ((min != null || max != null) && NumberIsNaN(value))) {
+    ((min != null || max != null) && NumberIsNaN(value))) {
     throw new ERR_OUT_OF_RANGE(
       name,
       `${min != null ? `>= ${min}` : ''}${min != null && max != null ? ' && ' : ''}${max != null ? `<= ${max}` : ''}`,
       value);
   }
-
-  return true;
 }
 
 /**
- * @function validateOneOf
+ * @callback validateOneOf
  * @template T
  * @param {T} value
  * @param {string} name
  * @param {T[]} oneOf
  */
+
+/** @type {validateOneOf} */
 const validateOneOf = hideStackFrames((value, name, oneOf) => {
   if (!ArrayPrototypeIncludes(oneOf, value)) {
     const allowed = ArrayPrototypeJoin(
@@ -190,16 +208,16 @@ const validateOneOf = hideStackFrames((value, name, oneOf) => {
 });
 
 /**
- * @function validateBoolean
+ * @callback validateBoolean
  * @param {*} value
  * @param {string} name
  * @returns {asserts value is boolean}
  */
+
+/** @type {validateBoolean} */
 function validateBoolean(value, name) {
   if (typeof value !== 'boolean')
     throw new ERR_INVALID_ARG_TYPE(name, 'boolean', value);
-
-  return true;
 }
 
 function getOwnPropertyValueOrDefault(options, key, defaultValue) {
@@ -209,32 +227,36 @@ function getOwnPropertyValueOrDefault(options, key, defaultValue) {
 }
 
 /**
- * @function validateObject
+ * @callback validateObject
  * @param {*} value
  * @param {string} name
  * @param {{allowArray: boolean=, allowFunction: boolean=, nullable: boolean=}} [options]
  */
+
+/** @type {validateObject} */
 const validateObject = hideStackFrames(
   (value, name, options = null) => {
     const allowArray = getOwnPropertyValueOrDefault(options, 'allowArray', false);
     const allowFunction = getOwnPropertyValueOrDefault(options, 'allowFunction', false);
     const nullable = getOwnPropertyValueOrDefault(options, 'nullable', false);
     if ((!nullable && value === null) ||
-        (!allowArray && ArrayIsArray(value)) ||
-        (typeof value !== 'object' && (
-          !allowFunction || typeof value !== 'function'
-        ))) {
+      (!allowArray && ArrayIsArray(value)) ||
+      (typeof value !== 'object' && (
+        !allowFunction || typeof value !== 'function'
+      ))) {
       throw new ERR_INVALID_ARG_TYPE(name, 'Object', value);
     }
   });
 
 /**
- * @function validateArray
+ * @callback validateArray
  * @param {*} value
  * @param {string} name
  * @param {number} [minLength]
  * @returns {asserts value is unknown[]}
  */
+
+/** @type {validateArray} */
 const validateArray = hideStackFrames((value, name, minLength = 0) => {
   if (!ArrayIsArray(value)) {
     throw new ERR_INVALID_ARG_TYPE(name, 'Array', value);
@@ -248,121 +270,137 @@ const validateArray = hideStackFrames((value, name, minLength = 0) => {
 });
 
 /**
- * @function validateSignalName
+ * @callback validateSignalName
  * @param {*} signal
  * @param {string} name
  * @returns {asserts signal is keyof signals}
  */
+
+/** @type {validateSignalName} */
 function validateSignalName(signal, name = 'signal') {
   validateString(signal, name);
 
   if (signals[signal] === undefined) {
     if (signals[StringPrototypeToUpperCase(signal)] !== undefined) {
       throw new ERR_UNKNOWN_SIGNAL(signal +
-                                   ' (signals must use all capital letters)');
+        ' (signals must use all capital letters)');
     }
 
     throw new ERR_UNKNOWN_SIGNAL(signal);
   }
-
-  return true;
 }
 
 /**
- * @function validateBuffer
+ * @callback validateBuffer
  * @param {*} buffer
  * @param {string} [name='buffer']
  */
+
+/** @type {validateBuffer} */
 const validateBuffer = hideStackFrames((buffer, name = 'buffer') => {
   if (!isArrayBufferView(buffer)) {
-    throw new ERR_INVALID_ARG_TYPE(name,
-                                   ['Buffer', 'TypedArray', 'DataView'],
-                                   buffer);
+    throw new ERR_INVALID_ARG_TYPE(name, ['Buffer', 'TypedArray', 'DataView'], buffer);
   }
 });
 
 /**
- * @function validateEncoding
+ * @callback validateEncoding
  * @param {string} data
  * @param {string} encoding
  */
+
+/** @type {validateEncoding} */
 function validateEncoding(data, encoding) {
   const normalizedEncoding = normalizeEncoding(encoding);
   const length = data.length;
 
   if (normalizedEncoding === 'hex' && length % 2 !== 0) {
-    throw new ERR_INVALID_ARG_VALUE('encoding', encoding,
-                                    `is invalid for data of length ${length}`);
+    throw new ERR_INVALID_ARG_VALUE('encoding', encoding, `is invalid for data of length ${length}`);
   }
 }
 
-// Check that the port number is not NaN when coerced to a number,
-// is an integer and that it falls within the legal range of port numbers.
+/**
+ * @callback validatePort
+ * @description Check that the port number is not NaN when coerced to a number,
+ * is an integer and that it falls within the legal range of port numbers.
+ * @param {*} port
+ * @param {string} [name='Port']
+ * @param {boolean} [allowZero=true]
+ * @returns {number}
+ */
 function validatePort(port, name = 'Port', allowZero = true) {
   if ((typeof port !== 'number' && typeof port !== 'string') ||
-      (typeof port === 'string' && StringPrototypeTrim(port).length === 0) ||
-      +port !== (+port >>> 0) ||
-      port > 0xFFFF ||
-      (port === 0 && !allowZero)) {
+    (typeof port === 'string' && StringPrototypeTrim(port).length === 0) ||
+    +port !== (+port >>> 0) ||
+    port > 0xFFFF ||
+    (port === 0 && !allowZero)) {
     throw new ERR_SOCKET_BAD_PORT(name, port, allowZero);
   }
   return port | 0;
 }
 
 /**
- * @function validateAbortSignal
+ * @callback validateAbortSignal
  * @param {string} signal
  * @param {string} name
  */
 const validateAbortSignal = hideStackFrames((signal, name) => {
   if (signal !== undefined &&
-      (signal === null ||
-       typeof signal !== 'object' ||
-       !('aborted' in signal))) {
+    (signal === null ||
+      typeof signal !== 'object' ||
+      !('aborted' in signal))) {
     throw new ERR_INVALID_ARG_TYPE(name, 'AbortSignal', signal);
   }
 });
 
 /**
- * @function validateFunction
+ * @callback validateFunction
  * @param {*} value
  * @param {string} name
  * @returns {asserts value is Function}
  */
+
+/** @type {validateFunction} */
 const validateFunction = hideStackFrames((value, name) => {
   if (typeof value !== 'function')
     throw new ERR_INVALID_ARG_TYPE(name, 'Function', value);
 });
 
 /**
- * @function validatePlainFunction
+ * @callback validatePlainFunction
  * @param {*} value
  * @param {string} name
  * @returns {asserts value is Function}
  */
+
+/** @type {validatePlainFunction} */
 const validatePlainFunction = hideStackFrames((value, name) => {
   if (typeof value !== 'function' || isAsyncFunction(value))
     throw new ERR_INVALID_ARG_TYPE(name, 'Function', value);
 });
 
 /**
- * @function validateUndefined
+ * @callback validateUndefined
  * @param {*} value
  * @param {string} name
  * @returns {asserts value is undefined}
  */
+
+/** @type {validateUndefined} */
 const validateUndefined = hideStackFrames((value, name) => {
   if (value !== undefined)
     throw new ERR_INVALID_ARG_TYPE(name, 'undefined', value);
 });
 
 /**
- * @function validateUnion
+ * @callback validateUnion
  * @template T
  * @param {T} value
  * @param {string} name
  * @param {T[]} union
  */
+
+/** @type {validateUnion} */
 function validateUnion(value, name, union) {
   if (!ArrayPrototypeIncludes(union, value)) {
     throw new ERR_INVALID_ARG_TYPE(name, `('${ArrayPrototypeJoin(union, '|')}')`, value);