lib: update validator jdoc declarations

Author: anonrig

lib/internal/validators.js

@@ -71,7 +71,12 @@ function parseFileMode(value, name, def) {
 }
 
 /**
- * @type {(function(unknown, string, number=, number=): void)}
+ * @function validateInteger
+ * @param {*} value
+ * @param {string} name
+ * @param {number} [min]
+ * @param {number} [max]
+ * @returns {asserts value is number}
  */
 const validateInteger = hideStackFrames(
   (value, name, min = NumberMIN_SAFE_INTEGER, max = NumberMAX_SAFE_INTEGER) => {
@@ -85,7 +90,12 @@ const validateInteger = hideStackFrames(
 );
 
 /**
- * @type {(function(unknown, string, number=, number=): void)}
+ * @function validateInt32
+ * @param {*} value
+ * @param {string} name
+ * @param {number} [min]
+ * @param {number} [max]
+ * @returns {asserts value is number}
  */
 const validateInt32 = hideStackFrames(
   (value, name, min = -2147483648, max = 2147483647) => {
@@ -103,7 +113,12 @@ const validateInt32 = hideStackFrames(
 );
 
 /**
- * @type {(function(unknown, string, boolean=): void)}
+ * @function validateUint32
+ * @param {*} value
+ * @param {string} name
+ * @param {number} [min]
+ * @param {number} [max]
+ * @returns {asserts value is number}
  */
 const validateUint32 = hideStackFrames((value, name, positive = false) => {
   if (typeof value !== 'number') {
@@ -120,11 +135,25 @@ const validateUint32 = hideStackFrames((value, name, positive = false) => {
   }
 });
 
+/**
+ * @function validateString
+ * @param {*} value
+ * @param {string} name
+ * @returns {asserts value is string}
+ */
 function validateString(value, name) {
   if (typeof value !== 'string')
     throw new ERR_INVALID_ARG_TYPE(name, 'string', value);
 }
 
+/**
+ * @function validateNumber
+ * @param {*} value
+ * @param {string} name
+ * @param {number} [min]
+ * @param {number} [max]
+ * @returns {asserts value is number}
+ */
 function validateNumber(value, name, min = undefined, max) {
   if (typeof value !== 'number')
     throw new ERR_INVALID_ARG_TYPE(name, 'number', value);
@@ -139,7 +168,11 @@ function validateNumber(value, name, min = undefined, max) {
 }
 
 /**
- * @type {(function(unknown, string, unknown[]): void)}
+ * @function validateOneOf
+ * @template T
+ * @param {T} value
+ * @param {string} name
+ * @param {T[]} oneOf
  */
 const validateOneOf = hideStackFrames((value, name, oneOf) => {
   if (!ArrayPrototypeIncludes(oneOf, value)) {
@@ -152,6 +185,12 @@ const validateOneOf = hideStackFrames((value, name, oneOf) => {
   }
 });
 
+/**
+ * @function validateBoolean
+ * @param {*} value
+ * @param {string} name
+ * @returns {asserts value is boolean}
+ */
 function validateBoolean(value, name) {
   if (typeof value !== 'boolean')
     throw new ERR_INVALID_ARG_TYPE(name, 'boolean', value);
@@ -164,11 +203,10 @@ function getOwnPropertyValueOrDefault(options, key, defaultValue) {
 }
 
 /**
- * @type {(function(unknown, string, {
- *   allowArray?: boolean,
- *   allowFunction?: boolean,
- *   nullable?: boolean
- * }): void)}
+ * @function validateObject
+ * @param {*} value
+ * @param {string} name
+ * @param {{allowArray: boolean=, allowFunction: boolean=, nullable: boolean=}} [options]
  */
 const validateObject = hideStackFrames(
   (value, name, options) => {
@@ -185,7 +223,11 @@ const validateObject = hideStackFrames(
   });
 
 /**
- * @type {(function(unknown, string, number=): void)}
+ * @function validateArray
+ * @param {*} value
+ * @param {string} name
+ * @param {number} [minLength]
+ * @returns {asserts value is unknown[]}
  */
 const validateArray = hideStackFrames((value, name, minLength = 0) => {
   if (!ArrayIsArray(value)) {
@@ -197,6 +239,12 @@ const validateArray = hideStackFrames((value, name, minLength = 0) => {
   }
 });
 
+/**
+ * @function validateSignalName
+ * @param {*} signal
+ * @param {string} name
+ * @returns {asserts signal is keyof signals}
+ */
 function validateSignalName(signal, name = 'signal') {
   validateString(signal, name);
 
@@ -211,7 +259,9 @@ function validateSignalName(signal, name = 'signal') {
 }
 
 /**
- * @type {(function(unknown, string=): void)}
+ * @function validateBuffer
+ * @param {*} buffer
+ * @param {string} [name='buffer']
  */
 const validateBuffer = hideStackFrames((buffer, name = 'buffer') => {
   if (!isArrayBufferView(buffer)) {
@@ -221,6 +271,11 @@ const validateBuffer = hideStackFrames((buffer, name = 'buffer') => {
   }
 });
 
+/**
+ * @function validateEncoding
+ * @param {string} data
+ * @param {string} encoding
+ */
 function validateEncoding(data, encoding) {
   const normalizedEncoding = normalizeEncoding(encoding);
   const length = data.length;
@@ -245,7 +300,9 @@ function validatePort(port, name = 'Port', allowZero = true) {
 }
 
 /**
- * @type {(function(unknown, string): void)}
+ * @function validateAbortSignal
+ * @param {string} signal
+ * @param {string} name
  */
 const validateAbortSignal = hideStackFrames((signal, name) => {
   if (signal !== undefined &&
@@ -257,29 +314,45 @@ const validateAbortSignal = hideStackFrames((signal, name) => {
 });
 
 /**
- * @type {(function(unknown, string): void)}
+ * @function validateFunction
+ * @param {*} value
+ * @param {string} name
+ * @returns {asserts value is Function}
  */
 const validateFunction = hideStackFrames((value, name) => {
   if (typeof value !== 'function')
     throw new ERR_INVALID_ARG_TYPE(name, 'Function', value);
 });
 
 /**
- * @type {(function(unknown, string): void)}
+ * @function validatePlainFunction
+ * @param {*} value
+ * @param {string} name
+ * @returns {asserts value is Function}
  */
 const validatePlainFunction = hideStackFrames((value, name) => {
   if (typeof value !== 'function' || isAsyncFunction(value))
     throw new ERR_INVALID_ARG_TYPE(name, 'Function', value);
 });
 
 /**
- * @type {(function(unknown, string): void)}
+ * @function validateUndefined
+ * @param {*} value
+ * @param {string} name
+ * @returns {asserts name is undefined}
  */
 const validateUndefined = hideStackFrames((value, name) => {
   if (value !== undefined)
     throw new ERR_INVALID_ARG_TYPE(name, 'undefined', value);
 });
 
+/**
+ * @function validateUnion
+ * @template T
+ * @param {T} value
+ * @param {string} name
+ * @param {T[]} union
+ */
 function validateUnion(value, name, union) {
   if (!ArrayPrototypeIncludes(union, value)) {
     throw new ERR_INVALID_ARG_TYPE(name, `('${ArrayPrototypeJoin(union, '|')}')`, value);