jsdoc/require-description-complete-sentence: Autofix adds dot in wrong place

[iliubinskii]

Expected behavior

Should add dot here:

/**
 * Description.
 *
 * @param str - String.
 */
export function f(str: string): void {}

Actual behavior

Adds dots like this:

/**.
 * .
 * .
 * .
 * Description
 *
 * @param str - String.
 */
export function f(str: string): void {}

ESLint Config

"jsdoc/require-description-complete-sentence": "warn"

ESLint sample

/**
 * Description
 *
 * @param str - String.
 */
export function f(str: string): void {}

// Format JS code here

Environment

"eslint-plugin-jsdoc": "^36.0.7",

---

Want to back this issue? Post a bounty on it! We accept bounties via Bountysource.

[brettz9]

Here's it in test case form for any who might be able to take a look at this:

    {
      code: `
      /**
       * Description
       *
       * @param str - String.
       */
      export function f(str: string): void {}
      `,
      errors: [
        {
          line: 3,
          message: 'Sentence must end with a period.',
        },
      ],
      output: `
      /**
       * Description.
       *
       * @param str - String.
       */
      export function f(str: string): void {}
      `,
      parser: require.resolve('@typescript-eslint/parser'),
      parserOptions: {
        sourceType: 'module',
      },
    },

[ghost]

same issue with jsdoc/require-description-complete-sentence and auto --fix eslint-plugin-jsdoc version 36.1.0 and eslint version 7.32.0

[cobaltt7]

/**
 * ...
 * @returns {Promise<
 * 	(T extends true ? import("./src/types").ShallowGallery : import("./src/types").Gallery)[]
 * >}
 *   - Array of gallery data.
 */

This rule autofixes as

// /**
//  * .
//  * ...
//  * @returns {Promise<
//  * 	(T extends true ? import("./src/types").ShallowGallery : import("./src/types").Gallery)[]
//  * >}
//  *   - Array of gallery data.
//  */

[maribethb]

I am also having issues with long record types and this rule. For example

/**
 * Render the playground layout.
 * @param {HTMLElement} container The container to render the playground in.
 * @return {{
 *     blocklyDiv: HTMLElement,
 *     minimizeButton: HTMLElement,
 *     monacoDiv: HTMLElement,
 *     guiContainer: HTMLElement,
 *     playgroundDiv: HTMLElement,
 *     tabsDiv: HTMLElement,
 *     tabButtons: HTMLElement
 * }} An object with the various playground components.
 */

With the settings set to 'mode': 'closure'. With the jsdoc/require-description-complete-sentence rule I am getting this line as an error and when autofixing, it adds periods to the beginning of the comment block when none are needed anywhere. I ended up having to disable this rule. I'm on 37.2.3 and also happens in v36.

[Roseidon]

Will there be anything on this issue? This auto-fix prevents us from automatically enable auto-fixing, because on every run it adds random dots in wrong places. Or is there at least a possibility to disable the auto-fix for this rule?

[scott-lc]

@Roseidon - The way I worked around this was to disable the jsdoc/require-description-complete-sentence rule entirely and, instead, configure the jsdoc/match-description rule to require a complete sentence.

    'jsdoc/match-description': [
      'error',
      {
        contexts, // see below
        matchDescription: '^[A-Z`\\d][\\s\\S]*[.?!:`]\\s*$',
        message: 'Description must begin with a capital letter and end with a period',
        tags: {
          param: true,
          returns: true,
          throws: true
        }
      }
    ],

Your use case will certainly be different, but in my my environment the contexts I use are:

// https://astexplorer.net
const contexts = [
  'ExportNamedDeclaration[declaration.type="VariableDeclaration"]',
  'ArrowFunctionExpression',
  'ClassDeclaration',
  'ClassExpression',
  'FunctionDeclaration',
  'MethodDefinition',
  'TSClassProperty',
  'TSDeclareFunction',
  'TSEnumDeclaration',
  'TSInterfaceDeclaration',
  'TSMethodSignature',
  'TSPropertySignature',
  'TSTypeAliasDeclaration'
];

Since the jsdoc/match-description rule is not "fixable", you can turn auto-fix back on.

[le-elvidge]

There are a few other rules with "fixerEnable" option. Would it make sense to have one on the "jsdoc/require-description-complete-sentence" rule as well?