meta: enable jsdoc/check-tag-names rule

PR-URL: #58521
Reviewed-By: James M Snell <[email protected]>
Reviewed-By: LiviaMedeiros <[email protected]>
Reviewed-By: Michaël Zasso <[email protected]>
Reviewed-By: Antoine du Hamel <[email protected]>

Author: anonrig

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

@@ -268,6 +268,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();
@@ -295,6 +296,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')
@@ -391,6 +396,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);
@@ -404,6 +410,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);
@@ -414,6 +421,8 @@ Buffer.allocUnsafe = function allocUnsafe(size) {
  * Equivalent to SlowBuffer(num), 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

@@ -442,7 +442,7 @@ function createConnection(...args) {
  *   protocol?: string;
  *   proxyEnv?: object;
  *   }} [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/hash.js

@@ -69,6 +69,7 @@ const kFinalized = Symbol('kFinalized');
 
 /**
  * @param {string} name
+ * @returns {string}
  */
 function normalizeAlgorithm(name) {
   return StringPrototypeReplace(StringPrototypeToLowerCase(name), '-', '');