eslint-plugin-jsdoc 61.1.12 → 61.2.1

package/dist/rules.d.ts

@@ -2660,6 +2660,16 @@ export interface Rules {
            * may wish to use the `endLines` option of the `tag-lines` rule.
            */
           reportTagGroupSpacing?: boolean;
+          /**
+           * Allows specification by tag of a specific higher maximum number of lines. Keys are tags and values are the maximum number of lines allowed for such tags. Overrides `linesBetween`. Defaults to no special exceptions per tag.
+           */
+          tagExceptions?: {
+            /**
+             * This interface was referenced by `undefined`'s JSON-Schema definition
+             * via the `patternProperty` ".*".
+             */
+            [k: string]: number;
+          };
           /**
            * An array of tag group objects indicating the preferred sequence for sorting tags.
            *

package/dist/to-valid-identifier.cjs

@@ -43,13 +43,15 @@ const identifiers = [
 	'with',
 	'yield',
 
-	// Future reserved keywords
+	// Future reserved keywords (strict mode)
 	'implements',
 	'interface',
+	'let',
 	'package',
 	'private',
 	'protected',
 	'public',
+	'static',
 
 	// Not keywords, but still restricted
 	'arguments',

package/package.json

@@ -192,5 +192,5 @@
     "test-cov": "TIMING=1 c8 --reporter text pnpm run test-no-cov",
     "test-index": "pnpm run test-no-cov test/rules/index.js"
   },
-  "version": "61.1.12"
+  "version": "61.2.1"
 }

package/src/iterateJsdoc.js

@@ -170,7 +170,8 @@ import esquery from 'esquery';
  *   seedTokens: (
  *     tokens?: Partial<import('comment-parser').Tokens>
  *   ) => import('comment-parser').Tokens,
- *   descLines: string[]
+ *   descLines: string[],
+ *   postDelims: string[]
  * ) => import('comment-parser').Line[]} setter
  * @returns {void}
  */
@@ -257,6 +258,7 @@ import esquery from 'esquery';
 /**
  * @callback GetFunctionParameterNames
  * @param {boolean} [useDefaultObjectProperties]
+ * @param {boolean} [ignoreInterfacedParameters]
  * @returns {import('./jsdocUtils.js').ParamNameInfo[]}
  */
 
@@ -927,6 +929,8 @@ const getUtils = (
   utils.setBlockDescription = (setter) => {
     /** @type {string[]} */
     const descLines = [];
+    /** @type {string[]} */
+    const postDelims = [];
     /**
      * @type {undefined|Integer}
      */
@@ -973,6 +977,7 @@ const getUtils = (
         return true;
       }
 
+      postDelims.push(postDelimiter);
       descLines.push(description);
       return false;
     });
@@ -993,6 +998,7 @@ const getUtils = (
           (info),
           seedTokens,
           descLines,
+          postDelims,
         ),
       );
     }
@@ -1369,8 +1375,8 @@ const getUtils = (
   utils.flattenRoots = jsdocUtils.flattenRoots;
 
   /** @type {GetFunctionParameterNames} */
-  utils.getFunctionParameterNames = (useDefaultObjectProperties) => {
-    return jsdocUtils.getFunctionParameterNames(node, useDefaultObjectProperties);
+  utils.getFunctionParameterNames = (useDefaultObjectProperties, ignoreInterfacedParameters) => {
+    return jsdocUtils.getFunctionParameterNames(node, useDefaultObjectProperties, ignoreInterfacedParameters);
   };
 
   /** @type {HasParams} */

package/src/jsdocUtils.js

@@ -203,11 +203,12 @@ const getPropertiesFromPropertySignature = (propSignature) => {
 /**
  * @param {ESTreeOrTypeScriptNode|null} functionNode
  * @param {boolean} [checkDefaultObjects]
+ * @param {boolean} [ignoreInterfacedParameters]
  * @throws {Error}
  * @returns {ParamNameInfo[]}
  */
 const getFunctionParameterNames = (
-  functionNode, checkDefaultObjects,
+  functionNode, checkDefaultObjects, ignoreInterfacedParameters,
 ) => {
   /* eslint-disable complexity -- Temporary */
   /**
@@ -230,6 +231,19 @@ const getFunctionParameterNames = (
     const hasLeftTypeAnnotation = 'left' in param && 'typeAnnotation' in param.left;
 
     if ('typeAnnotation' in param || hasLeftTypeAnnotation) {
+      if (ignoreInterfacedParameters && 'typeAnnotation' in param &&
+        param.typeAnnotation) {
+        // No-op
+        return [
+          undefined, {
+            hasPropertyRest: false,
+            hasRestElement: false,
+            names: [],
+            rests: [],
+          },
+        ];
+      }
+
       const typeAnnotation = hasLeftTypeAnnotation ?
         /** @type {import('@typescript-eslint/types').TSESTree.Identifier} */ (
           param.left

package/src/rules/requireParam.js

@@ -65,19 +65,10 @@ export default iterateJsdoc(({
     useDefaultObjectProperties = false,
   } = context.options[0] || {};
 
-  if (interfaceExemptsParamsCheck) {
-    if (node && 'params' in node && node.params.length === 1 &&
-        node.params?.[0] && typeof node.params[0] === 'object' &&
-        node.params[0].type === 'ObjectPattern' &&
-        'typeAnnotation' in node.params[0] && node.params[0].typeAnnotation
-    ) {
-      return;
-    }
-
-    if (node && node.parent?.type === 'VariableDeclarator' &&
-        'typeAnnotation' in node.parent.id && node.parent.id.typeAnnotation) {
-      return;
-    }
+  if (interfaceExemptsParamsCheck && node &&
+    node.parent?.type === 'VariableDeclarator' &&
+    'typeAnnotation' in node.parent.id && node.parent.id.typeAnnotation) {
+    return;
   }
 
   const preferredTagName = /** @type {string} */ (utils.getPreferredTagName({
@@ -87,7 +78,7 @@ export default iterateJsdoc(({
     return;
   }
 
-  const functionParameterNames = utils.getFunctionParameterNames(useDefaultObjectProperties);
+  const functionParameterNames = utils.getFunctionParameterNames(useDefaultObjectProperties, interfaceExemptsParamsCheck);
   if (!functionParameterNames.length) {
     return;
   }

package/src/rules/sortTags.js

@@ -5,11 +5,13 @@ export default iterateJsdoc(({
   context,
   jsdoc,
   utils,
+// eslint-disable-next-line complexity -- Temporary
 }) => {
   const
     /**
      * @type {{
      *   linesBetween: import('../iterateJsdoc.js').Integer,
+     *   tagExceptions: Record<string, number>,
      *   tagSequence: {
      *     tags: string[]
      *   }[],
@@ -22,6 +24,7 @@ export default iterateJsdoc(({
       linesBetween = 1,
       reportIntraTagGroupSpacing = true,
       reportTagGroupSpacing = true,
+      tagExceptions = {},
       tagSequence = defaultTagOrder,
     } = context.options[0] || {};
 
@@ -328,7 +331,7 @@ export default iterateJsdoc(({
       }
 
       const ct = countTagEmptyLines(tag);
-      if (ct) {
+      if (ct && (!tagExceptions[tag.tag] || tagExceptions[tag.tag] < ct)) {
         const fixer = () => {
           let foundFirstTag = false;
 
@@ -548,6 +551,15 @@ will not have spacing applied regardless. For adding line breaks there, you
 may wish to use the \`endLines\` option of the \`tag-lines\` rule.`,
             type: 'boolean',
           },
+          tagExceptions: {
+            description: 'Allows specification by tag of a specific higher maximum number of lines. Keys are tags and values are the maximum number of lines allowed for such tags. Overrides `linesBetween`. Defaults to no special exceptions per tag.',
+            patternProperties: {
+              '.*': {
+                type: 'number',
+              },
+            },
+            type: 'object',
+          },
           tagSequence: {
             description: `An array of tag group objects indicating the preferred sequence for sorting tags.
 

package/src/rules/tagLines.js

@@ -37,18 +37,22 @@ const checkMaxBlockLines = ({
         line: excessIndexLine,
       },
       () => {
-        utils.setBlockDescription((info, seedTokens, descLines) => {
+        utils.setBlockDescription((info, seedTokens, descLines, postDelims) => {
+          const newPostDelims = [
+            ...postDelims.slice(0, excessIndexLine),
+            ...postDelims.slice(excessIndexLine + excessBlockLines - 1 - maxBlockLines),
+          ];
           return [
             ...descLines.slice(0, excessIndexLine),
             ...descLines.slice(excessIndexLine + excessBlockLines - 1 - maxBlockLines),
-          ].map((desc) => {
+          ].map((desc, idx) => {
             return {
               number: 0,
               source: '',
               tokens: seedTokens({
                 ...info,
                 description: desc,
-                postDelimiter: desc.trim() ? ' ' : '',
+                postDelimiter: newPostDelims[idx],
               }),
             };
           });
@@ -310,15 +314,15 @@ export default iterateJsdoc(({
           line: lastDescriptionLine - trailingDiff,
         },
         () => {
-          utils.setBlockDescription((info, seedTokens, descLines) => {
-            return descLines.slice(0, -trailingDiff).map((desc) => {
+          utils.setBlockDescription((info, seedTokens, descLines, postDelims) => {
+            return descLines.slice(0, -trailingDiff).map((desc, idx) => {
               return {
                 number: 0,
                 source: '',
                 tokens: seedTokens({
                   ...info,
                   description: desc,
-                  postDelimiter: desc.trim() ? info.postDelimiter : '',
+                  postDelimiter: postDelims[idx],
                 }),
               };
             });
@@ -332,7 +336,7 @@ export default iterateJsdoc(({
           line: lastDescriptionLine,
         },
         () => {
-          utils.setBlockDescription((info, seedTokens, descLines) => {
+          utils.setBlockDescription((info, seedTokens, descLines, postDelims) => {
             return [
               ...descLines,
               ...Array.from({
@@ -340,14 +344,14 @@ export default iterateJsdoc(({
               }, () => {
                 return '';
               }),
-            ].map((desc) => {
+            ].map((desc, idx) => {
               return {
                 number: 0,
                 source: '',
                 tokens: seedTokens({
                   ...info,
                   description: desc,
-                  postDelimiter: desc.trim() ? info.postDelimiter : '',
+                  postDelimiter: desc.trim() ? postDelims[idx] : '',
                 }),
               };
             });

package/src/rules.d.ts

@@ -2660,6 +2660,16 @@ export interface Rules {
            * may wish to use the `endLines` option of the `tag-lines` rule.
            */
           reportTagGroupSpacing?: boolean;
+          /**
+           * Allows specification by tag of a specific higher maximum number of lines. Keys are tags and values are the maximum number of lines allowed for such tags. Overrides `linesBetween`. Defaults to no special exceptions per tag.
+           */
+          tagExceptions?: {
+            /**
+             * This interface was referenced by `undefined`'s JSON-Schema definition
+             * via the `patternProperty` ".*".
+             */
+            [k: string]: number;
+          };
           /**
            * An array of tag group objects indicating the preferred sequence for sorting tags.
            *