eslint-plugin-jsdoc 65.2.0 → 65.2.1

package/dist/iterateJsdoc.d.ts

@@ -180,6 +180,8 @@ export type Utils = BasicUtils & {
     addLine: AddLine;
     addLines: AddLines;
     makeMultiline: MakeMultiline;
+    moveClosingDelimiterToOwnLine: () => boolean;
+    newLineEnd: string;
     flattenRoots: import("./jsdocUtils.js").FlattenRoots;
     getFunctionParameterNames: GetFunctionParameterNames;
     hasParams: HasParams;

package/package.json

@@ -163,5 +163,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": "65.2.0"
+  "version": "65.2.1"
 }

package/src/iterateJsdoc.js

@@ -520,6 +520,8 @@ import esquery from 'esquery';
  *   addLine: AddLine,
  *   addLines: AddLines,
  *   makeMultiline: MakeMultiline,
+ *   moveClosingDelimiterToOwnLine: () => boolean,
+ *   newLineEnd: string,
  *   flattenRoots: import('./jsdocUtils.js').FlattenRoots,
  *   getFunctionParameterNames: GetFunctionParameterNames,
  *   hasParams: HasParams,
@@ -1188,30 +1190,150 @@ const getUtils = (
     //         correct information will be available)
   };
 
-  /** @type {AddTag} */
-  utils.addTag = (
-    targetTagName,
-    number = (jsdoc.tags[jsdoc.tags.length - 1]?.source[0]?.number ?? jsdoc.source.findIndex(({
+  // `comment-parser` keeps the `\r` of a CRLF line break in `lineEnd`
+  const newLineEnd = sourceCode.text.includes('\r\n') ? '\r' : '';
+  utils.newLineEnd = newLineEnd;
+
+  // From last to first, as printed on a line
+  const contentKeys = /** @type {const} */ ([
+    'description',
+    'postName',
+    'name',
+    'postType',
+    'type',
+    'postTag',
+    'tag',
+  ]);
+
+  /**
+   * @param {import('comment-parser').Tokens} lineTokens
+   * @returns {boolean}
+   */
+  const hasContent = (lineTokens) => {
+    return contentKeys.some((key) => {
+      return lineTokens[key];
+    });
+  };
+
+  /**
+   * Moves a closing delimiter which follows content on the same line to a
+   * line of its own.
+   * @returns {boolean} Whether a change was made
+   */
+  utils.moveClosingDelimiterToOwnLine = () => {
+    const closingIndex = jsdoc.source.length - 1;
+    const {
+      tokens: closingTokens,
+    } = jsdoc.source[closingIndex];
+
+    if (!closingTokens.end || !hasContent(closingTokens)) {
+      return false;
+    }
+
+    const {
+      end,
+      lineEnd,
+    } = closingTokens;
+
+    // Tags may hold their own copies of the line (see `rewireSpecs`)
+    const {
+      number: closingNumber,
+    } = jsdoc.source[closingIndex];
+    const lines = [
+      jsdoc.source[closingIndex],
+      ...jsdoc.tags.flatMap(({
+        source,
+      }) => {
+        return source.filter(({
+          number,
+        }) => {
+          return number === closingNumber;
+        });
+      }),
+    ];
+
+    for (const {
+      tokens: lineTokens,
+    } of lines) {
+      lineTokens.end = '';
+      lineTokens.lineEnd = newLineEnd;
+
+      // Strip the whitespace which preceded the closing delimiter
+      const lastKey = /** @type {NonNullable<typeof contentKeys[number]>} */ (
+        contentKeys.find((key) => {
+          return lineTokens[key];
+        })
+      );
+      lineTokens[lastKey] = lineTokens[lastKey].trimEnd();
+    }
+
+    utils.addLine(closingIndex + 1, {
+      end,
+      lineEnd,
+      start: indent + ' ',
+    });
+
+    return true;
+  };
+
+  /**
+   * Prepares the block for, and gets, the index at which a new tag belongs:
+   * after the last line of the last tag (including its continuation lines),
+   * or at the end of a description if there are no tags, and in any case
+   * before the closing delimiter, which is moved to a line of its own
+   * (mutating `jsdoc.source`) if need be.
+   * @returns {Integer}
+   */
+  const prepareTagInsertionIndex = () => {
+    const closingIndex = jsdoc.source.length - 1;
+
+    if (utils.moveClosingDelimiterToOwnLine()) {
+      return closingIndex + 1;
+    }
+
+    if (!jsdoc.source.some(({
       tokens: {
         tag,
       },
     }) => {
       return tag;
-    }) - 1) + 1,
+    })) {
+      return closingIndex;
+    }
+
+    // Blank lines before the closing delimiter do not belong to the tag
+    return jsdoc.source.findLastIndex(({
+      tokens: lineTokens,
+    }, idx) => {
+      return idx < closingIndex && hasContent(lineTokens);
+    }) + 1;
+  };
+
+  /** @type {AddTag} */
+  utils.addTag = (
+    targetTagName,
+    number,
     tokens = {},
   ) => {
-    jsdoc.source.splice(number, 0, {
-      number,
+    if (number === undefined && jsdoc.source.length === 1) {
+      utils.makeMultiline();
+    }
+
+    const insertionIndex = number ?? prepareTagInsertionIndex();
+
+    jsdoc.source.splice(insertionIndex, 0, {
+      number: insertionIndex,
       source: '',
       tokens: seedTokens({
         delimiter: '*',
+        lineEnd: newLineEnd,
         postDelimiter: ' ',
         start: indent + ' ',
         tag: `@${targetTagName}`,
         ...tokens,
       }),
     });
-    for (const src of jsdoc.source.slice(number + 1)) {
+    for (const src of jsdoc.source.slice(insertionIndex + 1)) {
       src.number++;
     }
   };
@@ -1376,6 +1498,7 @@ const getUtils = (
     }
 
     utils.emptyTokens(tokens);
+    tokens.lineEnd = newLineEnd;
 
     utils.addLine(1, {
       delimiter: '*',
@@ -1383,6 +1506,7 @@ const getUtils = (
       // If a description were present, it may have whitespace attached
       //   due to being at the end of the single line
       description: description.trimEnd(),
+      lineEnd: newLineEnd,
       name,
       postDelimiter,
       postName,

package/src/rules/checkParamNames.js

@@ -22,6 +22,52 @@ const getSimpleParameterName = (parameter) => {
   return parameter.name;
 };
 
+const contentKeys = /** @type {const} */ ([
+  'description',
+  'postName',
+  'name',
+  'postType',
+  'type',
+  'postTag',
+  'tag',
+]);
+
+/**
+ * @param {import('comment-parser').Tokens} tokens
+ * @returns {boolean}
+ */
+const hasContent = (tokens) => {
+  return contentKeys.some((key) => {
+    return tokens[key];
+  });
+};
+
+/**
+ * Copies tokens, omitting any closing delimiter (and the whitespace
+ * preceding it).
+ * @param {import('comment-parser').Tokens} tokens
+ * @param {string} newLineEnd
+ * @returns {import('comment-parser').Tokens}
+ */
+const withoutClosing = (tokens, newLineEnd) => {
+  const copy = {
+    ...tokens,
+    end: '',
+  };
+  if (tokens.end) {
+    copy.lineEnd = newLineEnd;
+
+    const lastKey = contentKeys.find((key) => {
+      return copy[key];
+    });
+    if (lastKey) {
+      copy[lastKey] = copy[lastKey].trimEnd();
+    }
+  }
+
+  return copy;
+};
+
 /**
  * @param {import('../iterateJsdoc.js').Integer} firstChangedTagIndex
  * @param {import('comment-parser').Spec[]} orderedTags
@@ -33,6 +79,9 @@ const makeParamOrderFix = (
   firstChangedTagIndex, orderedTags, jsdoc, utils,
 ) => {
   return () => {
+    // Otherwise, the closing delimiter would be copied along with the last tag
+    utils.moveClosingDelimiterToOwnLine();
+
     const itemsToMoveRange = [
       ...Array.from({
         length: jsdoc.tags.length - firstChangedTagIndex,
@@ -62,25 +111,25 @@ const makeParamOrderFix = (
     for (const index of itemsToMoveRange) {
       const changedTag = changedTags[index];
 
+      const [
+        firstLine,
+        ...otherLines
+      ] = changedTag.source;
+
       utils.addTag(
         changedTag.tag,
         extraTagCount + initialOffset + index,
-        {
-          ...changedTag.source[0].tokens,
-          end: '',
-        },
+        withoutClosing(firstLine.tokens, utils.newLineEnd),
       );
 
       for (const {
         tokens,
-      } of changedTag.source.slice(1)) {
-        if (!tokens.end) {
+      } of otherLines) {
+        // A closing delimiter alone on its line is not part of the tag
+        if (!tokens.end || hasContent(tokens)) {
           utils.addLine(
             extraTagCount + initialOffset + index + 1,
-            {
-              ...tokens,
-              end: '',
-            },
+            withoutClosing(tokens, utils.newLineEnd),
           );
           extraTagCount++;
         }