eslint-plugin-jsdoc/dist/rules/requireHyphenBeforeParamDescription.cjs.map

JSDoc linting rules for ESLint.

{"version":3,"file":"requireHyphenBeforeParamDescription.cjs","names":["iterateJsdoc"],"sources":["../../src/rules/requireHyphenBeforeParamDescription.js"],"sourcesContent":["import iterateJsdoc from '../iterateJsdoc.js';\n\nexport default iterateJsdoc(({\n  context,\n  jsdoc,\n  utils,\n}) => {\n  const [\n    mainCircumstance,\n    {\n      tags = null,\n    } = {},\n  ] = context.options;\n\n  const tgs = /**\n               * @type {null|\"any\"|{[key: string]: \"always\"|\"never\"}}\n               */ (tags);\n\n  /**\n   * @param {import('@es-joy/jsdoccomment').JsdocTagWithInline} jsdocTag\n   * @param {string} targetTagName\n   * @param {\"always\"|\"never\"} [circumstance]\n   * @returns {void}\n   */\n  const checkHyphens = (jsdocTag, targetTagName, circumstance = mainCircumstance) => {\n    const always = !circumstance || circumstance === 'always';\n    const desc = /** @type {string} */ (utils.getTagDescription(jsdocTag));\n    if (!desc.trim()) {\n      return;\n    }\n\n    const startsWithHyphen = (/^\\s*-/v).test(desc);\n    const hyphenNewline = (/^\\s*-\\n/v).test(desc);\n\n    let lines = 0;\n    for (const {\n      tokens,\n    } of jsdocTag.source) {\n      if (tokens.description) {\n        break;\n      }\n\n      lines++;\n    }\n\n    if (always && !hyphenNewline) {\n      if (!startsWithHyphen) {\n        let fixIt = true;\n        for (const {\n          tokens,\n        } of jsdocTag.source) {\n          if (tokens.description) {\n            tokens.description = tokens.description.replace(\n              /^(\\s*)/v, '$1- ',\n            );\n            break;\n          }\n\n          // Linebreak after name since has no description\n          if (tokens.name) {\n            fixIt = false;\n            break;\n          }\n        }\n\n        if (fixIt) {\n          utils.reportJSDoc(\n            `There must be a hyphen before @${targetTagName} description.`,\n            {\n              line: jsdocTag.source[0].number + lines,\n            },\n            () => {},\n          );\n        }\n      }\n    } else if (startsWithHyphen) {\n      utils.reportJSDoc(\n        always ?\n          `There must be no hyphen followed by newline after the @${targetTagName} name.` :\n          `There must be no hyphen before @${targetTagName} description.`,\n        {\n          line: jsdocTag.source[0].number + lines,\n        },\n        () => {\n          for (const {\n            tokens,\n          } of jsdocTag.source) {\n            if (tokens.description) {\n              tokens.description = tokens.description.replace(\n                /^\\s*-\\s*/v, '',\n              );\n              if (hyphenNewline) {\n                tokens.postName = '';\n              }\n\n              break;\n            }\n          }\n        },\n        true,\n      );\n    }\n  };\n\n  utils.forEachPreferredTag('param', checkHyphens);\n  if (tgs) {\n    const tagEntries = Object.entries(tgs);\n    for (const [\n      tagName,\n      circumstance,\n    ] of tagEntries) {\n      if (tagName === '*') {\n        const preferredParamTag = utils.getPreferredTagName({\n          tagName: 'param',\n        });\n        for (const {\n          tag,\n        } of jsdoc.tags) {\n          if (tag === preferredParamTag || tagEntries.some(([\n            tagNme,\n          ]) => {\n            return tagNme !== '*' && tagNme === tag;\n          })) {\n            continue;\n          }\n\n          utils.forEachPreferredTag(tag, (jsdocTag, targetTagName) => {\n            checkHyphens(\n              jsdocTag,\n              targetTagName,\n              /** @type {\"always\"|\"never\"} */ (circumstance),\n            );\n          });\n        }\n\n        continue;\n      }\n\n      utils.forEachPreferredTag(tagName, (jsdocTag, targetTagName) => {\n        checkHyphens(\n          jsdocTag,\n          targetTagName,\n          /** @type {\"always\"|\"never\"} */ (circumstance),\n        );\n      });\n    }\n  }\n}, {\n  iterateAllJsdocs: true,\n  meta: {\n    docs: {\n      description: 'Requires a hyphen before the `@param` description (and optionally before `@property` descriptions).',\n      url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-hyphen-before-param-description.md#repos-sticky-header',\n    },\n    fixable: 'code',\n    schema: [\n      {\n        description: `If the string is \\`\"always\"\\` then a problem is raised when there is no hyphen\nbefore the description. If it is \\`\"never\"\\` then a problem is raised when there\nis a hyphen before the description. The default value is \\`\"always\"\\`.\n\nEven if hyphens are set to \"always\" appear after the tag name, they will\nactually be forbidden in the event that they are followed immediately by\nthe end of a line (this will otherwise cause Visual Studio Code to display\nincorrectly).`,\n        enum: [\n          'always', 'never',\n        ],\n        type: 'string',\n      },\n      {\n        additionalProperties: false,\n        description: `The options object may have the following property to indicate behavior for\nother tags besides the \\`@param\\` tag (or the \\`@arg\\` tag if so set).`,\n        properties: {\n          tags: {\n            anyOf: [\n              {\n                patternProperties: {\n                  '.*': {\n                    enum: [\n                      'always', 'never',\n                    ],\n                    type: 'string',\n                  },\n                },\n                type: 'object',\n              },\n              {\n                enum: [\n                  'any',\n                ],\n                type: 'string',\n              },\n            ],\n            description: `Object whose keys indicate different tags to check for the\n  presence or absence of hyphens; the key value should be \"always\" or \"never\",\n  indicating how hyphens are to be applied, e.g., \\`{property: 'never'}\\`\n  to ensure \\`@property\\` never uses hyphens. A key can also be set as \\`*\\`, e.g.,\n  \\`'*': 'always'\\` to apply hyphen checking to any tag (besides the preferred\n  \\`@param\\` tag which follows the main string option setting and besides any\n  other \\`tags\\` entries).`,\n          },\n        },\n        type: 'object',\n      },\n    ],\n    type: 'layout',\n  },\n});\n"],"mappings":"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","ignoreList":[]}