From 4ef86b59b5c6e2f8b34607ba0af1bc08227caae6 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 7ae8ab2987538b..e92c9ecb6ec1f0 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 76cff6dd3ee581..bfcc422bc1f0cd 100644 --- a/lib/internal/modules/esm/resolve.js +++ b/lib/internal/modules/esm/resolve.js @@ -343,8 +343,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)); } @@ -354,8 +354,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)); } @@ -376,14 +376,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)); } @@ -393,6 +393,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, @@ -406,7 +419,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, '../') && @@ -426,7 +439,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) { @@ -441,7 +454,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); } } @@ -450,7 +463,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; @@ -487,6 +500,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') { @@ -551,8 +577,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); } /** @@ -609,7 +635,7 @@ function packageExportsResolve( ); if (resolveResult == null) { - throwExportsNotFound(packageSubpath, packageJSONUrl, base); + throw exportsNotFound(packageSubpath, packageJSONUrl, base); } return resolveResult; @@ -660,12 +686,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) { @@ -745,7 +771,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 efb18fc43c0556..ad9b849f86056e 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']