lib: fix JSDoc issues

Updating ESLint and dependencies will start flagging a few additional
JSDoc issues. One or two of these are simple fixes. The ESM stuff
requires throwing explicitly in JSDoc'ed functions rather than calling
another function to throw. I think this makes the code easier to
understand--you don't need to know that a particular function that
starts with `throwsIf` *might* throw but something that starts with
`throwsAnythingElse` will always throw. Instead, it's right there in the
code. This also might make it easier to improve stack traces if that's
something we'd like to do at some point.

PR-URL: #45243
Reviewed-By: Moshe Atlow <[email protected]>
Reviewed-By: Tobias Nießen <[email protected]>
Reviewed-By: Jan Krems <[email protected]>
Reviewed-By: Juan José Arboleda <[email protected]>
Reviewed-By: Antoine du Hamel <[email protected]>
Reviewed-By: Darshan Sen <[email protected]>
Reviewed-By: Michaël Zasso <[email protected]>
Reviewed-By: Luigi Pinca <[email protected]>
Reviewed-By: Yagiz Nizipli <[email protected]>
Reviewed-By: Zeyu "Alex" Yang <[email protected]>

Author: Trott

lib/https.js

@@ -178,7 +178,7 @@ function createConnection(port, host, options) {
  *   maxCachedSessions?: number;
  *   servername?: string;
  *   }} [options]
- * @returns {Agent}
+ * @constructor
  */
 function Agent(options) {
   if (!(this instanceof Agent))

lib/internal/modules/esm/assert.js

@@ -81,7 +81,7 @@ function validateAssertions(url, format,
         // `type` wasn't specified at all.
         throw new ERR_IMPORT_ASSERTION_TYPE_MISSING(url, validType);
       }
-      handleInvalidType(url, importAssertions.type);
+      return handleInvalidType(url, importAssertions.type);
   }
 }
 

lib/internal/modules/esm/resolve.js

@@ -277,8 +277,8 @@ function finalizeResolution(resolved, base, preserveSymlinks) {
  * @param {URL} packageJSONUrl
  * @param {string | URL | undefined} base
  */
-function throwImportNotDefined(specifier, packageJSONUrl, base) {
-  throw new ERR_PACKAGE_IMPORT_NOT_DEFINED(
+function importNotDefined(specifier, packageJSONUrl, base) {
+  return new ERR_PACKAGE_IMPORT_NOT_DEFINED(
     specifier, packageJSONUrl && fileURLToPath(new URL('.', packageJSONUrl)),
     fileURLToPath(base));
 }
@@ -288,8 +288,8 @@ function throwImportNotDefined(specifier, packageJSONUrl, base) {
  * @param {URL} packageJSONUrl
  * @param {string | URL | undefined} base
  */
-function throwExportsNotFound(subpath, packageJSONUrl, base) {
-  throw new ERR_PACKAGE_PATH_NOT_EXPORTED(
+function exportsNotFound(subpath, packageJSONUrl, base) {
+  return new ERR_PACKAGE_PATH_NOT_EXPORTED(
     fileURLToPath(new URL('.', packageJSONUrl)), subpath,
     base && fileURLToPath(base));
 }
@@ -310,14 +310,14 @@ function throwInvalidSubpath(request, match, packageJSONUrl, internal, base) {
                                          base && fileURLToPath(base));
 }
 
-function throwInvalidPackageTarget(
+function invalidPackageTarget(
   subpath, target, packageJSONUrl, internal, base) {
   if (typeof target === 'object' && target !== null) {
     target = JSONStringify(target, null, '');
   } else {
     target = `${target}`;
   }
-  throw new ERR_INVALID_PACKAGE_TARGET(
+  return new ERR_INVALID_PACKAGE_TARGET(
     fileURLToPath(new URL('.', packageJSONUrl)), subpath, target,
     internal, base && fileURLToPath(base));
 }
@@ -327,6 +327,19 @@ const deprecatedInvalidSegmentRegEx = /(^|\\|\/)((\.|%2e)(\.|%2e)?|(n|%6e|%4e)(o
 const invalidPackageNameRegEx = /^\.|%|\\/;
 const patternRegEx = /\*/g;
 
+/**
+ *
+ * @param {string} target
+ * @param {*} subpath
+ * @param {*} match
+ * @param {*} packageJSONUrl
+ * @param {*} base
+ * @param {*} pattern
+ * @param {*} internal
+ * @param {*} isPathMap
+ * @param {*} conditions
+ * @returns {URL}
+ */
 function resolvePackageTargetString(
   target,
   subpath,
@@ -340,7 +353,7 @@ function resolvePackageTargetString(
 ) {
 
   if (subpath !== '' && !pattern && target[target.length - 1] !== '/')
-    throwInvalidPackageTarget(match, target, packageJSONUrl, internal, base);
+    throw invalidPackageTarget(match, target, packageJSONUrl, internal, base);
 
   if (!StringPrototypeStartsWith(target, './')) {
     if (internal && !StringPrototypeStartsWith(target, '../') &&
@@ -360,7 +373,7 @@ function resolvePackageTargetString(
           exportTarget, packageJSONUrl, conditions);
       }
     }
-    throwInvalidPackageTarget(match, target, packageJSONUrl, internal, base);
+    throw invalidPackageTarget(match, target, packageJSONUrl, internal, base);
   }
 
   if (RegExpPrototypeExec(invalidSegmentRegEx, StringPrototypeSlice(target, 2)) !== null) {
@@ -375,7 +388,7 @@ function resolvePackageTargetString(
         emitInvalidSegmentDeprecation(resolvedTarget, request, match, packageJSONUrl, internal, base, true);
       }
     } else {
-      throwInvalidPackageTarget(match, target, packageJSONUrl, internal, base);
+      throw invalidPackageTarget(match, target, packageJSONUrl, internal, base);
     }
   }
 
@@ -384,7 +397,7 @@ function resolvePackageTargetString(
   const packagePath = new URL('.', packageJSONUrl).pathname;
 
   if (!StringPrototypeStartsWith(resolvedPath, packagePath))
-    throwInvalidPackageTarget(match, target, packageJSONUrl, internal, base);
+    throw invalidPackageTarget(match, target, packageJSONUrl, internal, base);
 
   if (subpath === '') return resolved;
 
@@ -421,6 +434,19 @@ function isArrayIndex(key) {
   return keyNum >= 0 && keyNum < 0xFFFF_FFFF;
 }
 
+/**
+ *
+ * @param {*} packageJSONUrl
+ * @param {string|[string]} target
+ * @param {*} subpath
+ * @param {*} packageSubpath
+ * @param {*} base
+ * @param {*} pattern
+ * @param {*} internal
+ * @param {*} isPathMap
+ * @param {*} conditions
+ * @returns {URL|null}
+ */
 function resolvePackageTarget(packageJSONUrl, target, subpath, packageSubpath,
                               base, pattern, internal, isPathMap, conditions) {
   if (typeof target === 'string') {
@@ -485,8 +511,8 @@ function resolvePackageTarget(packageJSONUrl, target, subpath, packageSubpath,
   } else if (target === null) {
     return null;
   }
-  throwInvalidPackageTarget(packageSubpath, target, packageJSONUrl, internal,
-                            base);
+  throw invalidPackageTarget(packageSubpath, target, packageJSONUrl, internal,
+                             base);
 }
 
 /**
@@ -543,7 +569,7 @@ function packageExportsResolve(
     );
 
     if (resolveResult == null) {
-      throwExportsNotFound(packageSubpath, packageJSONUrl, base);
+      throw exportsNotFound(packageSubpath, packageJSONUrl, base);
     }
 
     return resolveResult;
@@ -594,12 +620,12 @@ function packageExportsResolve(
       conditions);
 
     if (resolveResult == null) {
-      throwExportsNotFound(packageSubpath, packageJSONUrl, base);
+      throw exportsNotFound(packageSubpath, packageJSONUrl, base);
     }
     return resolveResult;
   }
 
-  throwExportsNotFound(packageSubpath, packageJSONUrl, base);
+  throw exportsNotFound(packageSubpath, packageJSONUrl, base);
 }
 
 function patternKeyCompare(a, b) {
@@ -679,7 +705,7 @@ function packageImportsResolve(name, base, conditions) {
       }
     }
   }
-  throwImportNotDefined(name, packageJSONUrl, base);
+  throw importNotDefined(name, packageJSONUrl, base);
 }
 
 /**

lib/internal/validators.js

@@ -325,7 +325,6 @@ function validateBooleanArray(value, name) {
   }
 }
 
-// eslint-disable-next-line jsdoc/require-returns-check
 /**
  * @param {*} signal
  * @param {string} [name='signal']