meta: enable eslint jsdoc rules

benchmark/common.js

@@ -386,7 +386,7 @@ function getUrlData(withBase) {
  * @param {number} e The repetition of the data, as exponent of 2
  * @param {boolean} withBase Whether to include a base URL
  * @param {boolean} asUrl Whether to return the results as URL objects
- * @return {string[] | string[][] | URL[]}
+ * @returns {string[] | string[][] | URL[]}
  */
 function bakeUrlData(type, e = 0, withBase = false, asUrl = false) {
   let result = [];

eslint.config.mjs

@@ -262,17 +262,21 @@ export default [
       // ESLint recommended rules that we disable.
       'no-inner-declarations': 'off',
 
-      // JSDoc recommended rules that we disable.
+      // JSDoc rules.
       'jsdoc/require-jsdoc': 'off',
       'jsdoc/require-param-description': 'off',
-      'jsdoc/newline-after-description': 'off',
       'jsdoc/require-returns-description': 'off',
-      'jsdoc/valid-types': 'off',
-      'jsdoc/no-defaults': 'off',
+      'jsdoc/valid-types': 'error',
+      'jsdoc/no-defaults': 'error',
       'jsdoc/no-undefined-types': 'off',
       'jsdoc/require-param': 'off',
-      'jsdoc/check-tag-names': 'off',
-      'jsdoc/require-returns': 'off',
+      'jsdoc/check-tag-names': 'error',
+      'jsdoc/require-returns': 'error',
+      'jsdoc/check-line-alignment': ['error', 'any', {
+        tags: ['param', 'property', 'returns', 'file'],
+        wrapIndent: '  ',
+      }],
+      'jsdoc/check-alignment': 'error',
 
       // Stylistic rules.
       '@stylistic/js/arrow-parens': 'error',

lib/_http_common.js

@@ -206,6 +206,8 @@ const tokenRegExp = /^[\^_`a-zA-Z\-0-9!#$%&'*+.|~]+$/;
  * Verifies that the given val is a valid HTTP token
  * per the rules defined in RFC 7230
  * See https://tools.ietf.org/html/rfc7230#section-3.2.6
+ * @param {string} val
+ * @returns {boolean}
  */
 function checkIsHttpToken(val) {
   return tokenRegExp.test(val);
@@ -217,6 +219,8 @@ const headerCharRegex = /[^\t\x20-\x7e\x80-\xff]/;
  *  field-value    = *( field-content / obs-fold )
  *  field-content  = field-vchar [ 1*( SP / HTAB ) field-vchar ]
  *  field-vchar    = VCHAR / obs-text
+ * @param {string} val
+ * @returns {boolean}
  */
 function checkInvalidHeaderChar(val) {
   return headerCharRegex.test(val);

lib/buffer.js

@@ -266,6 +266,7 @@ function _copyActual(source, target, targetStart, sourceStart, sourceEnd) {
  * runtime deprecation would introduce too much breakage at this time. It's not
  * likely that the Buffer constructors would ever actually be removed.
  * Deprecation Code: DEP0005
+ * @returns {Buffer}
  */
 function Buffer(arg, encodingOrOffset, length) {
   showFlaggedDeprecation();
@@ -293,6 +294,10 @@ ObjectDefineProperty(Buffer, SymbolSpecies, {
  * Buffer.from(array)
  * Buffer.from(buffer)
  * Buffer.from(arrayBuffer[, byteOffset[, length]])
+ * @param {any} value
+ * @param {BufferEncoding|number} encodingOrOffset
+ * @param {number} [length]
+ * @returns {Buffer}
  */
 Buffer.from = function from(value, encodingOrOffset, length) {
   if (typeof value === 'string')
@@ -389,6 +394,7 @@ ObjectSetPrototypeOf(Buffer, Uint8Array);
 /**
  * Creates a new filled Buffer instance.
  * alloc(size[, fill[, encoding]])
+ * @returns {FastBuffer}
  */
 Buffer.alloc = function alloc(size, fill, encoding) {
   validateNumber(size, 'size', 0, kMaxLength);
@@ -402,6 +408,7 @@ Buffer.alloc = function alloc(size, fill, encoding) {
 /**
  * Equivalent to Buffer(num), by default creates a non-zero-filled Buffer
  * instance. If `--zero-fill-buffers` is set, will zero-fill the buffer.
+ * @returns {FastBuffer}
  */
 Buffer.allocUnsafe = function allocUnsafe(size) {
   validateNumber(size, 'size', 0, kMaxLength);
@@ -412,6 +419,8 @@ Buffer.allocUnsafe = function allocUnsafe(size) {
  * By default creates a non-zero-filled Buffer instance that is not allocated
  * off the pre-initialized pool. If `--zero-fill-buffers` is set, will zero-fill
  * the buffer.
+ * @param {number} size
+ * @returns {FastBuffer|undefined}
  */
 Buffer.allocUnsafeSlow = function allocUnsafeSlow(size) {
   validateNumber(size, 'size', 0, kMaxLength);

lib/events.js

@@ -157,8 +157,8 @@ function lazyEventEmitterAsyncResource() {
         }
 
         /**
-         * @param {symbol,string} event
-         * @param  {...any} args
+         * @param {symbol|string} event
+         * @param {any[]} args
          * @returns {boolean}
          */
         emit(event, ...args) {
@@ -203,7 +203,7 @@ function lazyEventEmitterAsyncResource() {
 /**
  * Creates a new `EventEmitter` instance.
  * @param {{ captureRejections?: boolean; }} [opts]
- * @constructs {EventEmitter}
+ * @constructs EventEmitter
  */
 function EventEmitter(opts) {
   EventEmitter.init.call(this, opts);
@@ -1115,24 +1115,28 @@ function on(emitter, event, options = kEmptyObject) {
     [kWatermarkData]: {
       /**
        * The current queue size
+       * @returns {number}
        */
       get size() {
         return size;
       },
       /**
        * The low watermark. The emitter is resumed every time size is lower than it
+       * @returns {number}
        */
       get low() {
         return lowWatermark;
       },
       /**
        * The high watermark. The emitter is paused every time size is higher than it
+       * @returns {number}
        */
       get high() {
         return highWatermark;
       },
       /**
        * It checks whether the emitter is paused by the watermark controller or not
+       * @returns {boolean}
        */
       get isPaused() {
         return paused;

lib/https.js

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

lib/internal/abort_controller.js

@@ -534,6 +534,7 @@ function transferableAbortSignal(signal) {
 
 /**
  * Creates an AbortController with a transferable AbortSignal
+ * @returns {AbortController}
  */
 function transferableAbortController() {
   return AbortController[kMakeTransferable]();

lib/internal/async_hooks.js

@@ -449,7 +449,7 @@ function clearDefaultTriggerAsyncId() {
  * @template {unknown} R
  * @param {number} triggerAsyncId
  * @param { (...T: args) => R } block
- * @param  {T} args
+ * @param {T} args
  * @returns {R}
  */
 function defaultTriggerAsyncIdScope(triggerAsyncId, block, ...args) {

lib/internal/blob.js

@@ -137,7 +137,7 @@ class Blob {
    *   endings? : string,
    *   type? : string,
    * }} [options]
-   * @constructs {Blob}
+   * @constructs Blob
    */
   constructor(sources = [], options) {
     markTransferMode(this, true, false);

lib/internal/crypto/random.js

@@ -503,13 +503,13 @@
  * 48 is the ASCII code for '0', 97 is the ASCII code for 'a'.
  * @param {number} number An integer between 0 and 15.
  * @returns {number} corresponding to the ASCII code of the hex representation
- *                   of the parameter.
+ * of the parameter.
  */
 const numberToHexCharCode = (number) => (number < 10 ? 48 : 87) + number;
 
 /**
  * @param {ArrayBuffer} buf An ArrayBuffer.
- * @return {bigint}
+ * @returns {bigint}
  */
 function arrayBufferToUnsignedBigInt(buf) {
   const length = ArrayBufferPrototypeGetByteLength(buf);

lib/internal/data_url.js

@@ -28,7 +28,10 @@ function lazyEncoder() {
 const ASCII_WHITESPACE_REPLACE_REGEX = /[\u0009\u000A\u000C\u000D\u0020]/g // eslint-disable-line
 
 // https://fetch.spec.whatwg.org/#data-url-processor
-/** @param {URL} dataURL */
+/**
+ * @param {URL} dataURL
+ * @returns {object|'failure'}
+ */
 function dataURLProcessor(dataURL) {
   // 1. Assert: dataURL's scheme is "data".
   assert(dataURL.protocol === 'data:');
@@ -132,6 +135,7 @@ function dataURLProcessor(dataURL) {
 /**
  * @param {URL} url
  * @param {boolean} excludeFragment
+ * @returns {string}
  */
 function URLSerializer(url, excludeFragment = false) {
   const { href } = url;
@@ -155,6 +159,7 @@ function URLSerializer(url, excludeFragment = false) {
  * @param {string} char
  * @param {string} input
  * @param {{ position: number }} position
+ * @returns {string}
  */
 function collectASequenceOfCodePointsFast(char, input, position) {
   const idx = StringPrototypeIndexOf(input, char, position.position);
@@ -170,7 +175,10 @@ function collectASequenceOfCodePointsFast(char, input, position) {
 }
 
 // https://url.spec.whatwg.org/#string-percent-decode
-/** @param {string} input */
+/**
+ * @param {string} input
+ * @returns {Uint8Array}
+ */
 function stringPercentDecode(input) {
   // 1. Let bytes be the UTF-8 encoding of input.
   const bytes = lazyEncoder().encode(input);
@@ -181,6 +189,7 @@ function stringPercentDecode(input) {
 
 /**
  * @param {number} byte
+ * @returns {boolean}
  */
 function isHexCharByte(byte) {
   // 0-9 A-F a-f
@@ -189,6 +198,7 @@ function isHexCharByte(byte) {
 
 /**
  * @param {number} byte
+ * @returns {number}
  */
 function hexByteToNumber(byte) {
   return (
@@ -202,7 +212,10 @@ function hexByteToNumber(byte) {
 }
 
 // https://url.spec.whatwg.org/#percent-decode
-/** @param {Uint8Array} input */
+/**
+ * @param {Uint8Array} input
+ * @returns {Uint8Array}
+ */
 function percentDecode(input) {
   const length = input.length;
   // 1. Let output be an empty byte sequence.
@@ -245,7 +258,10 @@ function percentDecode(input) {
 }
 
 // https://infra.spec.whatwg.org/#forgiving-base64-decode
-/** @param {string} data */
+/**
+ * @param {string} data
+ * @returns {object|'failure'}
+ */
 function forgivingBase64(data) {
   // 1. Remove all ASCII whitespace from data.
   data = RegExpPrototypeSymbolReplace(ASCII_WHITESPACE_REPLACE_REGEX, data, '');
@@ -286,6 +302,7 @@ function forgivingBase64(data) {
 /**
  * @see https://infra.spec.whatwg.org/#ascii-whitespace
  * @param {number} char
+ * @returns {boolean}
  */
 function isASCIIWhitespace(char) {
   // "\r\n\t\f "
@@ -295,8 +312,9 @@ function isASCIIWhitespace(char) {
 /**
  * @see https://infra.spec.whatwg.org/#strip-leading-and-trailing-ascii-whitespace
  * @param {string} str
- * @param {boolean} [leading=true]
- * @param {boolean} [trailing=true]
+ * @param {boolean} [leading]
+ * @param {boolean} [trailing]
+ * @returns {string}
  */
 function removeASCIIWhitespace(str, leading = true, trailing = true) {
   return removeChars(str, leading, trailing, isASCIIWhitespace);
@@ -307,6 +325,7 @@ function removeASCIIWhitespace(str, leading = true, trailing = true) {
  * @param {boolean} leading
  * @param {boolean} trailing
  * @param {(charCode: number) => boolean} predicate
+ * @returns {string}
  */
 function removeChars(str, leading, trailing, predicate) {
   let lead = 0;

lib/internal/dns/promises.js

@@ -124,7 +124,7 @@
  * @param {0 | 4 | 6} family - The IP address family (4 or 6, or 0 for both).
  * @param {string} hostname - The hostname to resolve.
  * @param {boolean} all - Whether to resolve with all IP addresses for the hostname.
  * @param {number} hints - One or more supported getaddrinfo flags (supply multiple via
  * bitwise OR).
  * @param {number} dnsOrder - How to sort results. Must be `ipv4first`, `ipv6first` or `verbatim`.
  * @returns {Promise<DNSLookupResult | DNSLookupResult[]>} The IP address(es) of the hostname.
@@ -185,13 +185,13 @@
  * Get the IP address for a given hostname.
  * @param {string} hostname - The hostname to resolve (ex. 'nodejs.org').
  * @param {object} [options] - Optional settings.
- * @param {boolean} [options.all=false] - Whether to return all or just the first resolved address.
- * @param {0 | 4 | 6} [options.family=0] - The record family. Must be 4, 6, or 0 (for both).
+ * @param {boolean} [options.all] - Whether to return all or just the first resolved address.
+ * @param {0 | 4 | 6} [options.family] - The record family. Must be 4, 6, or 0 (for both).
  * @param {number} [options.hints] - One or more supported getaddrinfo flags (supply multiple via
  * bitwise OR).
- * @param {string} [options.order='verbatim'] - Return results in same order DNS resolved them;
- * Must be `ipv4first`, `ipv6first` or `verbatim`.
+ * @param {'ipv4first' | 'ipv6first' | 'verbatim'} [options.order] - Return results in same order DNS resolved them;
  * New code should supply `verbatim`.
+ * @returns {Promise<object>}
  */
 function lookup(hostname, options) {
   let hints = 0;

lib/internal/errors.js

@@ -90,6 +90,7 @@
  * The default implementation of `Error.prepareStackTrace` with simple
  * concatenation of stack frames.
  * Read more about `Error.prepareStackTrace` at https://v8.dev/docs/stack-trace-api#customizing-stack-traces.
+ * @returns {string}
  */
 function defaultPrepareStackTrace(error, trace) {
   // Normal error formatting:
@@ -121,11 +122,11 @@
  * of error objects created in a VM Context will always invoke the
  * prepareStackTraceCallback of the principal realm.
  * @param {object} globalThis The global object of the realm that the error was
- *   created in. When the error object is created in a VM Context, this is the
- *   global object of that VM Context.
+ * created in. When the error object is created in a VM Context, this is the
+ * global object of that VM Context.
  * @param {object} error The error object.
  * @param {CallSite[]} trace An array of CallSite objects, read more at https://v8.dev/docs/stack-trace-api#customizing-stack-traces.
  * @returns {string}
  */
 function prepareStackTraceCallback(globalThis, error, trace) {
   // API for node internals to override error stack formatting
@@ -157,6 +158,7 @@
 
 /**
  * The default Error.prepareStackTrace implementation.
+ * @returns {string}
  */
 function ErrorPrepareStackTrace(error, trace) {
   return internalPrepareStackTrace(error, trace);

lib/internal/event_target.js

@@ -373,9 +373,11 @@ function isCustomEvent(value) {
   return isEvent(value) && (value?.[kDetail] !== undefined);
 }
 
+/**
+ * @class
+ */
 class CustomEvent extends Event {
   /**
-   * @constructor
    * @param {string} type
    * @param {{
    *   bubbles?: boolean,
@@ -746,6 +748,7 @@ class EventTarget {
 
   /**
    * @param {Event} event
+   * @returns {boolean}
    */
   dispatchEvent(event) {
     if (!isEventTarget(this))

lib/internal/http2/util.js

@@ -607,6 +607,7 @@ const assertValidPseudoHeaderTrailer = hideStackFrames((key) => {
 /**
  * Takes a request headers array, validates it and sets defaults, and returns
  * the resulting headers in NgHeaders string list format.
+ * @returns {object}
  */
 function prepareRequestHeadersArray(headers, session) {
   let method;
@@ -688,6 +689,7 @@ function prepareRequestHeadersArray(headers, session) {
 /**
  * Takes a request headers object, validates it and sets defaults, and returns
  * the resulting headers in object format and NgHeaders string list format.
+ * @returns {object}
  */
 function prepareRequestHeadersObject(headers, session) {
   const headersObject = ObjectAssign({ __proto__: null }, headers);
@@ -734,6 +736,7 @@ const kNoHeaderFlags = StringFromCharCode(NGHTTP2_NV_FLAG_NONE);
  * format, rejecting illegal header configurations, and marking sensitive headers
  * that should not be indexed en route. This takes either a flat map of
  * raw headers ([k1, v1, k2, v2]) or a header object ({ k1: v1, k2: [v2, v3] }).
+ * @returns {[string, number]}
  */
 function buildNgHeaderString(arrayOrMap,
                              assertValuePseudoHeader = assertValidPseudoHeader,