FazBrowse GitHub Viewer | Trending |
URL:
| Home
Tools: [Download Repo ZIP]   [Original HTTPS Page]

lib: fix JSDoc issues · nodejs/node@a8e9015 · GitHub

/ node Public

Commit a8e9015

Browse files
Trott
authored and
RafaelGSS
committed
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 <moshe@atlow.co.il> Reviewed-By: Tobias Nießen <tniessen@tnie.de> Reviewed-By: Jan Krems <jan.krems@gmail.com> Reviewed-By: Juan José Arboleda <soyjuanarbol@gmail.com> Reviewed-By: Antoine du Hamel <duhamelantoine1995@gmail.com> Reviewed-By: Darshan Sen <raisinten@gmail.com> Reviewed-By: Michaël Zasso <targos@protonmail.com> Reviewed-By: Luigi Pinca <luigipinca@gmail.com> Reviewed-By: Yagiz Nizipli <yagiz@nizipli.com> Reviewed-By: Zeyu "Alex" Yang <himself65@outlook.com>
1 parent 1f0edde commit a8e9015

4 files changed

Lines changed: 44 additions & 19 deletions

File tree

‎lib/https.js‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -178,7 +178,7 @@ function createConnection(port, host, options) {
178178
* maxCachedSessions?: number;
179179
* servername?: string;
180180
* }} [options]
181-
* @returns {Agent}
181+
* @constructor
182182
*/
183183
function Agent(options) {
184184
if (!(this instanceof Agent))

‎lib/internal/modules/esm/assert.js‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -81,7 +81,7 @@ function validateAssertions(url, format,
8181
// `type` wasn't specified at all.
8282
throw new ERR_IMPORT_ASSERTION_TYPE_MISSING(url, validType);
8383
}
84-
handleInvalidType(url, importAssertions.type);
84+
return handleInvalidType(url, importAssertions.type);
8585
}
8686
}
8787

‎lib/internal/modules/esm/resolve.js‎

Lines changed: 42 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -277,8 +277,8 @@ function finalizeResolution(resolved, base, preserveSymlinks) {
277277
* @param {URL} packageJSONUrl
278278
* @param {string | URL | undefined} base
279279
*/
280-
function throwImportNotDefined(specifier, packageJSONUrl, base) {
281-
throw new ERR_PACKAGE_IMPORT_NOT_DEFINED(
280+
function importNotDefined(specifier, packageJSONUrl, base) {
281+
return new ERR_PACKAGE_IMPORT_NOT_DEFINED(
282282
specifier, packageJSONUrl && fileURLToPath(new URL('.', packageJSONUrl)),
283283
fileURLToPath(base));
284284
}
@@ -288,8 +288,8 @@ function throwImportNotDefined(specifier, packageJSONUrl, base) {
288288
* @param {URL} packageJSONUrl
289289
* @param {string | URL | undefined} base
290290
*/
291-
function throwExportsNotFound(subpath, packageJSONUrl, base) {
292-
throw new ERR_PACKAGE_PATH_NOT_EXPORTED(
291+
function exportsNotFound(subpath, packageJSONUrl, base) {
292+
return new ERR_PACKAGE_PATH_NOT_EXPORTED(
293293
fileURLToPath(new URL('.', packageJSONUrl)), subpath,
294294
base && fileURLToPath(base));
295295
}
@@ -310,14 +310,14 @@ function throwInvalidSubpath(request, match, packageJSONUrl, internal, base) {
310310
base && fileURLToPath(base));
311311
}
312312

313-
function throwInvalidPackageTarget(
313+
function invalidPackageTarget(
314314
subpath, target, packageJSONUrl, internal, base) {
315315
if (typeof target === 'object' && target !== null) {
316316
target = JSONStringify(target, null, '');
317317
} else {
318318
target = `${target}`;
319319
}
320-
throw new ERR_INVALID_PACKAGE_TARGET(
320+
return new ERR_INVALID_PACKAGE_TARGET(
321321
fileURLToPath(new URL('.', packageJSONUrl)), subpath, target,
322322
internal, base && fileURLToPath(base));
323323
}
@@ -327,6 +327,19 @@ const deprecatedInvalidSegmentRegEx = /(^|\\|\/)((\.|%2e)(\.|%2e)?|(n|%6e|%4e)(o
327327
const invalidPackageNameRegEx = /^\.|%|\\/;
328328
const patternRegEx = /\*/g;
329329

330+
/**
331+
*
332+
* @param {string} target
333+
* @param {*} subpath
334+
* @param {*} match
335+
* @param {*} packageJSONUrl
336+
* @param {*} base
337+
* @param {*} pattern
338+
* @param {*} internal
339+
* @param {*} isPathMap
340+
* @param {*} conditions
341+
* @returns {URL}
342+
*/
330343
function resolvePackageTargetString(
331344
target,
332345
subpath,
@@ -340,7 +353,7 @@ function resolvePackageTargetString(
340353
) {
341354

342355
if (subpath !== '' && !pattern && target[target.length - 1] !== '/')
343-
throwInvalidPackageTarget(match, target, packageJSONUrl, internal, base);
356+
throw invalidPackageTarget(match, target, packageJSONUrl, internal, base);
344357

345358
if (!StringPrototypeStartsWith(target, './')) {
346359
if (internal && !StringPrototypeStartsWith(target, '../') &&
@@ -360,7 +373,7 @@ function resolvePackageTargetString(
360373
exportTarget, packageJSONUrl, conditions);
361374
}
362375
}
363-
throwInvalidPackageTarget(match, target, packageJSONUrl, internal, base);
376+
throw invalidPackageTarget(match, target, packageJSONUrl, internal, base);
364377
}
365378

366379
if (RegExpPrototypeExec(invalidSegmentRegEx, StringPrototypeSlice(target, 2)) !== null) {
@@ -375,7 +388,7 @@ function resolvePackageTargetString(
375388
emitInvalidSegmentDeprecation(resolvedTarget, request, match, packageJSONUrl, internal, base, true);
376389
}
377390
} else {
378-
throwInvalidPackageTarget(match, target, packageJSONUrl, internal, base);
391+
throw invalidPackageTarget(match, target, packageJSONUrl, internal, base);
379392
}
380393
}
381394

@@ -384,7 +397,7 @@ function resolvePackageTargetString(
384397
const packagePath = new URL('.', packageJSONUrl).pathname;
385398

386399
if (!StringPrototypeStartsWith(resolvedPath, packagePath))
387-
throwInvalidPackageTarget(match, target, packageJSONUrl, internal, base);
400+
throw invalidPackageTarget(match, target, packageJSONUrl, internal, base);
388401

389402
if (subpath === '') return resolved;
390403

@@ -421,6 +434,19 @@ function isArrayIndex(key) {
421434
return keyNum >= 0 && keyNum < 0xFFFF_FFFF;
422435
}
423436

437+
/**
438+
*
439+
* @param {*} packageJSONUrl
440+
* @param {string|[string]} target
441+
* @param {*} subpath
442+
* @param {*} packageSubpath
443+
* @param {*} base
444+
* @param {*} pattern
445+
* @param {*} internal
446+
* @param {*} isPathMap
447+
* @param {*} conditions
448+
* @returns {URL|null}
449+
*/
424450
function resolvePackageTarget(packageJSONUrl, target, subpath, packageSubpath,
425451
base, pattern, internal, isPathMap, conditions) {
426452
if (typeof target === 'string') {
@@ -485,8 +511,8 @@ function resolvePackageTarget(packageJSONUrl, target, subpath, packageSubpath,
485511
} else if (target === null) {
486512
return null;
487513
}
488-
throwInvalidPackageTarget(packageSubpath, target, packageJSONUrl, internal,
489-
base);
514+
throw invalidPackageTarget(packageSubpath, target, packageJSONUrl, internal,
515+
base);
490516
}
491517

492518
/**
@@ -543,7 +569,7 @@ function packageExportsResolve(
543569
);
544570

545571
if (resolveResult == null) {
546-
throwExportsNotFound(packageSubpath, packageJSONUrl, base);
572+
throw exportsNotFound(packageSubpath, packageJSONUrl, base);
547573
}
548574

549575
return resolveResult;
@@ -594,12 +620,12 @@ function packageExportsResolve(
594620
conditions);
595621

596622
if (resolveResult == null) {
597-
throwExportsNotFound(packageSubpath, packageJSONUrl, base);
623+
throw exportsNotFound(packageSubpath, packageJSONUrl, base);
598624
}
599625
return resolveResult;
600626
}
601627

602-
throwExportsNotFound(packageSubpath, packageJSONUrl, base);
628+
throw exportsNotFound(packageSubpath, packageJSONUrl, base);
603629
}
604630

605631
function patternKeyCompare(a, b) {
@@ -679,7 +705,7 @@ function packageImportsResolve(name, base, conditions) {
679705
}
680706
}
681707
}
682-
throwImportNotDefined(name, packageJSONUrl, base);
708+
throw importNotDefined(name, packageJSONUrl, base);
683709
}
684710

685711
/**

‎lib/internal/validators.js‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -325,7 +325,6 @@ function validateBooleanArray(value, name) {
325325
}
326326
}
327327

328-
// eslint-disable-next-line jsdoc/require-returns-check
329328
/**
330329
* @param {*} signal
331330
* @param {string} [name='signal']

0 commit comments

Comments
 (0)
Back | FazBrowse Home | New Git URL