From a8e901555a721a867b745690041fc2d9df5b6ee1 Mon Sep 17 00:00:00 2001 From: Rich Trott Date: Sun, 30 Oct 2022 09:03:10 -0700 Subject: [PATCH] lib: fix JSDoc issues MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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: https://github.com/nodejs/node/pull/45243 Reviewed-By: Moshe Atlow Reviewed-By: Tobias Nießen Reviewed-By: Jan Krems Reviewed-By: Juan José Arboleda Reviewed-By: Antoine du Hamel Reviewed-By: Darshan Sen Reviewed-By: Michaël Zasso Reviewed-By: Luigi Pinca Reviewed-By: Yagiz Nizipli Reviewed-By: Zeyu "Alex" Yang --- lib/https.js | 2 +- lib/internal/modules/esm/assert.js | 2 +- lib/internal/modules/esm/resolve.js | 58 +++++++++++++++++++++-------- lib/internal/validators.js | 1 - 4 files changed, 44 insertions(+), 19 deletions(-) diff --git a/lib/https.js b/lib/https.js index 0ecd13b1dd36ed..e871b35bcacbc5 100644 --- a/lib/https.js +++ b/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)) diff --git a/lib/internal/modules/esm/assert.js b/lib/internal/modules/esm/assert.js index f0f8387bea1cbf..4402306b934af7 100644 --- a/lib/internal/modules/esm/assert.js +++ b/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); } } diff --git a/lib/internal/modules/esm/resolve.js b/lib/internal/modules/esm/resolve.js index 0b3414535ba3ee..561bbbe32e626e 100644 --- a/lib/internal/modules/esm/resolve.js +++ b/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); } /** diff --git a/lib/internal/validators.js b/lib/internal/validators.js index 753b135d3d0361..a971e6574621c5 100644 --- a/lib/internal/validators.js +++ b/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']