eslint-plugin-jsdoc 61.2.0 → 61.3.0

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/checkIndentation.js

@@ -25,6 +25,17 @@ const maskCodeBlocks = (str) => {
   });
 };
 
+/**
+ * @param {string[]} lines
+ * @param {number} lineIndex
+ * @returns {number}
+ */
+const getLineNumber = (lines, lineIndex) => {
+  const precedingText = lines.slice(0, lineIndex).join('\n');
+  const lineBreaks = precedingText.match(/\n/gv) || [];
+  return lineBreaks.length + 1;
+};
+
 export default iterateJsdoc(({
   context,
   jsdocNode,
@@ -32,21 +43,88 @@ export default iterateJsdoc(({
   sourceCode,
 }) => {
   const options = context.options[0] || {};
-  const /** @type {{excludeTags: string[]}} */ {
+  const /** @type {{excludeTags: string[], allowIndentedSections: boolean}} */ {
+    allowIndentedSections = false,
     excludeTags = [
       'example',
     ],
   } = options;
 
-  const reg = /^(?:\/?\**|[ \t]*)\*[ \t]{2}/gmv;
   const textWithoutCodeBlocks = maskCodeBlocks(sourceCode.getText(jsdocNode));
   const text = excludeTags.length ? maskExcludedContent(textWithoutCodeBlocks, excludeTags) : textWithoutCodeBlocks;
 
-  if (reg.test(text)) {
-    const lineBreaks = text.slice(0, reg.lastIndex).match(/\n/gv) || [];
-    report('There must be no indentation.', null, {
-      line: lineBreaks.length,
-    });
+  if (allowIndentedSections) {
+    // When allowIndentedSections is enabled, only check for indentation on tag lines
+    // and the very first line of the main description
+    const lines = text.split('\n');
+    let hasSeenContent = false;
+    let currentSectionIndent = null;
+
+    for (const [
+      lineIndex,
+      line,
+    ] of lines.entries()) {
+      // Check for indentation (two or more spaces after *)
+      const indentMatch = line.match(/^(?:\/?\**|[\t ]*)\*([\t ]{2,})/v);
+
+      if (indentMatch) {
+        // Check what comes after the indentation
+        const afterIndent = line.slice(indentMatch[0].length);
+        const indentAmount = indentMatch[1].length;
+
+        // If this is a tag line with indentation, always report
+        if (/^@\w+/v.test(afterIndent)) {
+          report('There must be no indentation.', null, {
+            line: getLineNumber(lines, lineIndex),
+          });
+          return;
+        }
+
+        // If we haven't seen any content yet (main description first line) and there's content, report
+        if (!hasSeenContent && afterIndent.trim().length > 0) {
+          report('There must be no indentation.', null, {
+            line: getLineNumber(lines, lineIndex),
+          });
+          return;
+        }
+
+        // For continuation lines, check consistency
+        if (hasSeenContent && afterIndent.trim().length > 0) {
+          if (currentSectionIndent === null) {
+            // First indented line in this section, set the indent level
+            currentSectionIndent = indentAmount;
+          } else if (indentAmount < currentSectionIndent) {
+            // Indentation is less than the established level (inconsistent)
+            report('There must be no indentation.', null, {
+              line: getLineNumber(lines, lineIndex),
+            });
+            return;
+          }
+        }
+      } else if (/^\s*\*\s+\S/v.test(line)) {
+        // No indentation on this line, reset section indent tracking
+        // (unless it's just whitespace or a closing comment)
+        currentSectionIndent = null;
+      }
+
+      // Track if we've seen any content (non-whitespace after the *)
+      if (/^\s*\*\s+\S/v.test(line)) {
+        hasSeenContent = true;
+      }
+
+      // Reset section indent when we encounter a tag
+      if (/@\w+/v.test(line)) {
+        currentSectionIndent = null;
+      }
+    }
+  } else {
+    const reg = /^(?:\/?\**|[ \t]*)\*[ \t]{2}/gmv;
+    if (reg.test(text)) {
+      const lineBreaks = text.slice(0, reg.lastIndex).match(/\n/gv) || [];
+      report('There must be no indentation.', null, {
+        line: lineBreaks.length,
+      });
+    }
   }
 }, {
   iterateAllJsdocs: true,
@@ -59,6 +137,10 @@ export default iterateJsdoc(({
       {
         additionalProperties: false,
         properties: {
+          allowIndentedSections: {
+            description: 'Allows indentation of nested sections on subsequent lines (like bullet lists)',
+            type: 'boolean',
+          },
           excludeTags: {
             description: `Array of tags (e.g., \`['example', 'description']\`) whose content will be
 "hidden" from the \`check-indentation\` rule. Defaults to \`['example']\`.

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/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

@@ -47,6 +47,10 @@ export interface Rules {
     | []
     | [
         {
+          /**
+           * Allows indentation of nested sections on subsequent lines (like bullet lists)
+           */
+          allowIndentedSections?: boolean;
           /**
            * Array of tags (e.g., `['example', 'description']`) whose content will be
            * "hidden" from the `check-indentation` rule. Defaults to `['example']`.