eslint-plugin-jsdoc 58.1.1 → 59.0.0

package/dist/rules/requireDescriptionCompleteSentence.cjs

@@ -258,15 +258,42 @@ var _default = exports.default = (0, _iterateJsdoc.default)(({
       additionalProperties: false,
       properties: {
         abbreviations: {
+          description: `You can provide an \`abbreviations\` options array to avoid such strings of text
+being treated as sentence endings when followed by dots. The \`.\` is not
+necessary at the end of the array items.`,
           items: {
             type: 'string'
           },
           type: 'array'
         },
         newlineBeforeCapsAssumesBadSentenceEnd: {
+          description: `When \`false\` (the new default), we will not assume capital letters after
+newlines are an incorrect way to end the sentence (they may be proper
+nouns, for example).`,
           type: 'boolean'
         },
         tags: {
+          description: `If you want additional tags to be checked for their descriptions, you may
+add them within this option.
+
+\`\`\`js
+{
+  'jsdoc/require-description-complete-sentence': ['error', {
+    tags: ['see', 'copyright']
+  }]
+}
+\`\`\`
+
+The tags \`@param\`/\`@arg\`/\`@argument\` and \`@property\`/\`@prop\` will be properly
+parsed to ensure that the checked "description" text includes only the text
+after the name.
+
+All other tags will treat the text following the tag name, a space, and
+an optional curly-bracketed type expression (and another space) as part of
+its "description" (e.g., for \`@returns {someType} some description\`, the
+description is \`some description\` while for \`@some-tag xyz\`, the description
+is \`xyz\`).
+`,
           items: {
             type: 'string'
           },

package/dist/rules/requireDescriptionCompleteSentence.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"requireDescriptionCompleteSentence.cjs","names":["_iterateJsdoc","_interopRequireDefault","require","_escapeStringRegexp","e","__esModule","default","otherDescriptiveTags","Set","extractParagraphs","text","split","extractSentences","abbreviationsRegex","txt","replaceAll","replace","sentenceEndGrouping","puncts","matchAll","map","sentEnd","sentence","idx","test","isNewLinePrecededByAPeriod","lastLineEndsSentence","lines","some","line","isCapitalized","str","toUpperCase","isTable","charAt","capitalize","slice","validateDescription","description","reportOrig","jsdocNode","sourceCode","tag","newlineBeforeCapsAssumesBadSentenceEnd","descriptionNoHeadings","paragraphs","filter","Boolean","paragraph","parIdx","sentences","fix","fixer","getText","findLast","RegExp","escapeStringRegexp","sentence_","beginning","reg","_$0","$1","replaceText","report","msg","tagObj","source","number","column","paragraphNoAbbreviations","_default","exports","iterateJsdoc","context","jsdoc","utils","abbreviations","options","length","abbreviation","join","getDescription","indices","match","index","toReversed","forEachPreferredTag","matchingJsdocTag","desc","name","getTagDescription","trim","tagsWithNames","getTagsByType","tags","tagsWithoutNames","filterTags","tagName","has","hasOptionTag","trimEnd","iterateAllJsdocs","meta","docs","url","fixable","schema","additionalProperties","properties","items","type","module"],"sources":["../../src/rules/requireDescriptionCompleteSentence.js"],"sourcesContent":["import iterateJsdoc from '../iterateJsdoc.js';\nimport escapeStringRegexp from 'escape-string-regexp';\n\nconst otherDescriptiveTags = new Set([\n  'classdesc', 'deprecated', 'exception', 'file', 'fileoverview', 'overview',\n  // 'copyright' and 'see' might be good addition, but as the former may be\n  //   sensitive text, and the latter may have just a link, they are not\n  //   included by default\n  'summary', 'throws', 'todo', 'yield', 'yields',\n]);\n\n/**\n * @param {string} text\n * @returns {string[]}\n */\nconst extractParagraphs = (text) => {\n  return text.split(/(?<![;:])\\n\\n+/v);\n};\n\n/**\n * @param {string} text\n * @param {string|RegExp} abbreviationsRegex\n * @returns {string[]}\n */\nconst extractSentences = (text, abbreviationsRegex) => {\n  const txt = text\n    // Remove all {} tags.\n    .replaceAll(/(?<!^)\\{[\\s\\S]*?\\}\\s*/gv, '')\n\n    // Remove custom abbreviations\n    .replace(abbreviationsRegex, '');\n\n  const sentenceEndGrouping = /([.?!])(?:\\s+|$)/gv;\n\n  const puncts = [\n    ...txt.matchAll(sentenceEndGrouping),\n  ].map((sentEnd) => {\n    return sentEnd[0];\n  });\n\n  return txt\n    .split(/[.?!](?:\\s+|$)/v)\n\n    // Re-add the dot.\n    .map((sentence, idx) => {\n      return !puncts[idx] && /^\\s*$/v.test(sentence) ? sentence : `${sentence}${puncts[idx] || ''}`;\n    });\n};\n\n/**\n * @param {string} text\n * @returns {boolean}\n */\nconst isNewLinePrecededByAPeriod = (text) => {\n  /** @type {boolean} */\n  let lastLineEndsSentence;\n\n  const lines = text.split('\\n');\n\n  return !lines.some((line) => {\n    if (lastLineEndsSentence === false && /^[A-Z][a-z]/v.test(line)) {\n      return true;\n    }\n\n    lastLineEndsSentence = /[.:?!\\|]$/v.test(line);\n\n    return false;\n  });\n};\n\n/**\n * @param {string} str\n * @returns {boolean}\n */\nconst isCapitalized = (str) => {\n  return str[0] === str[0].toUpperCase();\n};\n\n/**\n * @param {string} str\n * @returns {boolean}\n */\nconst isTable = (str) => {\n  return str.charAt(0) === '|';\n};\n\n/**\n * @param {string} str\n * @returns {string}\n */\nconst capitalize = (str) => {\n  return str.charAt(0).toUpperCase() + str.slice(1);\n};\n\n/**\n * @param {string} description\n * @param {import('../iterateJsdoc.js').Report} reportOrig\n * @param {import('eslint').Rule.Node} jsdocNode\n * @param {string|RegExp} abbreviationsRegex\n * @param {import('eslint').SourceCode} sourceCode\n * @param {import('comment-parser').Spec|{\n *   line: import('../iterateJsdoc.js').Integer\n * }} tag\n * @param {boolean} newlineBeforeCapsAssumesBadSentenceEnd\n * @returns {boolean}\n */\nconst validateDescription = (\n  description, reportOrig, jsdocNode, abbreviationsRegex,\n  sourceCode, tag, newlineBeforeCapsAssumesBadSentenceEnd,\n) => {\n  if (!description || (/^\\n+$/v).test(description)) {\n    return false;\n  }\n\n  const descriptionNoHeadings = description.replaceAll(/^\\s*#[^\\n]*(\\n|$)/gmv, '');\n\n  const paragraphs = extractParagraphs(descriptionNoHeadings).filter(Boolean);\n\n  return paragraphs.some((paragraph, parIdx) => {\n    const sentences = extractSentences(paragraph, abbreviationsRegex);\n\n    const fix = /** @type {import('eslint').Rule.ReportFixer} */ (fixer) => {\n      let text = sourceCode.getText(jsdocNode);\n\n      if (!/[.:?!]$/v.test(paragraph)) {\n        const line = paragraph.split('\\n').findLast(Boolean);\n        text = text.replace(new RegExp(`${escapeStringRegexp(\n          /** @type {string} */\n          (line),\n        )}$`, 'mv'), `${line}.`);\n      }\n\n      for (const sentence of sentences.filter((sentence_) => {\n        return !(/^\\s*$/v).test(sentence_) && !isCapitalized(sentence_) &&\n          !isTable(sentence_);\n      })) {\n        const beginning = sentence.split('\\n')[0];\n\n        if ('tag' in tag && tag.tag) {\n          const reg = new RegExp(`(@${escapeStringRegexp(tag.tag)}.*)${escapeStringRegexp(beginning)}`, 'v');\n\n          text = text.replace(reg, (_$0, $1) => {\n            return $1 + capitalize(beginning);\n          });\n        } else {\n          text = text.replace(new RegExp('((?:[.?!]|\\\\*|\\\\})\\\\s*)' + escapeStringRegexp(beginning), 'v'), '$1' + capitalize(beginning));\n        }\n      }\n\n      return fixer.replaceText(jsdocNode, text);\n    };\n\n    /**\n     * @param {string} msg\n     * @param {import('eslint').Rule.ReportFixer | null | undefined} fixer\n     * @param {{\n     *   line?: number | undefined;\n     *   column?: number | undefined;\n     * } | (import('comment-parser').Spec & {\n     *   line?: number | undefined;\n     *   column?: number | undefined;\n     * })} tagObj\n     * @returns {void}\n     */\n    const report = (msg, fixer, tagObj) => {\n      if ('line' in tagObj) {\n        /**\n         * @type {{\n         *   line: number;\n         * }}\n         */ (tagObj).line += parIdx * 2;\n      } else {\n        /** @type {import('comment-parser').Spec} */ (\n          tagObj\n        ).source[0].number += parIdx * 2;\n      }\n\n      // Avoid errors if old column doesn't exist here\n      tagObj.column = 0;\n      reportOrig(msg, fixer, tagObj);\n    };\n\n    if (sentences.some((sentence) => {\n      return (/^[.?!]$/v).test(sentence);\n    })) {\n      report('Sentences must be more than punctuation.', null, tag);\n    }\n\n    if (sentences.some((sentence) => {\n      return !(/^\\s*$/v).test(sentence) && !isCapitalized(sentence) && !isTable(sentence);\n    })) {\n      report('Sentences should start with an uppercase character.', fix, tag);\n    }\n\n    const paragraphNoAbbreviations = paragraph.replace(abbreviationsRegex, '');\n\n    if (!/(?:[.?!\\|]|```)\\s*$/v.test(paragraphNoAbbreviations)) {\n      report('Sentences must end with a period.', fix, tag);\n      return true;\n    }\n\n    if (newlineBeforeCapsAssumesBadSentenceEnd && !isNewLinePrecededByAPeriod(paragraphNoAbbreviations)) {\n      report('A line of text is started with an uppercase character, but the preceding line does not end the sentence.', null, tag);\n\n      return true;\n    }\n\n    return false;\n  });\n};\n\nexport default iterateJsdoc(({\n  context,\n  jsdoc,\n  jsdocNode,\n  report,\n  sourceCode,\n  utils,\n}) => {\n  const /** @type {{abbreviations: string[], newlineBeforeCapsAssumesBadSentenceEnd: boolean}} */ {\n    abbreviations = [],\n    newlineBeforeCapsAssumesBadSentenceEnd = false,\n  } = context.options[0] || {};\n\n  const abbreviationsRegex = abbreviations.length ?\n    new RegExp('\\\\b' + abbreviations.map((abbreviation) => {\n      return escapeStringRegexp(abbreviation.replaceAll(/\\.$/gv, '') + '.');\n    }).join('|') + '(?:$|\\\\s)', 'gv') :\n    '';\n\n  let {\n    description,\n  } = utils.getDescription();\n\n  const indices = [\n    ...description.matchAll(/```[\\s\\S]*```/gv),\n  ].map((match) => {\n    const {\n      index,\n    } = match;\n    const [\n      {\n        length,\n      },\n    ] = match;\n    return {\n      index,\n      length,\n    };\n  }).toReversed();\n\n  for (const {\n    index,\n    length,\n  } of indices) {\n    description = description.slice(0, index) +\n      description.slice(/** @type {import('../iterateJsdoc.js').Integer} */ (\n        index\n      ) + length);\n  }\n\n  if (validateDescription(description, report, jsdocNode, abbreviationsRegex, sourceCode, {\n    line: jsdoc.source[0].number + 1,\n  }, newlineBeforeCapsAssumesBadSentenceEnd)) {\n    return;\n  }\n\n  utils.forEachPreferredTag('description', (matchingJsdocTag) => {\n    const desc = `${matchingJsdocTag.name} ${utils.getTagDescription(matchingJsdocTag)}`.trim();\n    validateDescription(desc, report, jsdocNode, abbreviationsRegex, sourceCode, matchingJsdocTag, newlineBeforeCapsAssumesBadSentenceEnd);\n  }, true);\n\n  const {\n    tagsWithNames,\n  } = utils.getTagsByType(jsdoc.tags);\n  const tagsWithoutNames = utils.filterTags(({\n    tag: tagName,\n  }) => {\n    return otherDescriptiveTags.has(tagName) ||\n      utils.hasOptionTag(tagName) && !tagsWithNames.some(({\n        tag,\n      }) => {\n        // If user accidentally adds tags with names (or like `returns`\n        //  get parsed as having names), do not add to this list\n        return tag === tagName;\n      });\n  });\n\n  tagsWithNames.some((tag) => {\n    const desc = /** @type {string} */ (\n      utils.getTagDescription(tag)\n    ).replace(/^- /v, '').trimEnd();\n\n    return validateDescription(desc, report, jsdocNode, abbreviationsRegex, sourceCode, tag, newlineBeforeCapsAssumesBadSentenceEnd);\n  });\n\n  tagsWithoutNames.some((tag) => {\n    const desc = `${tag.name} ${utils.getTagDescription(tag)}`.trim();\n\n    return validateDescription(desc, report, jsdocNode, abbreviationsRegex, sourceCode, tag, newlineBeforeCapsAssumesBadSentenceEnd);\n  });\n}, {\n  iterateAllJsdocs: true,\n  meta: {\n    docs: {\n      description: 'Requires that block description, explicit `@description`, and `@param`/`@returns` tag descriptions are written in complete sentences.',\n      url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-description-complete-sentence.md#repos-sticky-header',\n    },\n    fixable: 'code',\n    schema: [\n      {\n        additionalProperties: false,\n        properties: {\n          abbreviations: {\n            items: {\n              type: 'string',\n            },\n            type: 'array',\n          },\n          newlineBeforeCapsAssumesBadSentenceEnd: {\n            type: 'boolean',\n          },\n          tags: {\n            items: {\n              type: 'string',\n            },\n            type: 'array',\n          },\n        },\n        type: 'object',\n      },\n    ],\n    type: 'suggestion',\n  },\n});\n"],"mappings":"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","ignoreList":[]}
+{"version":3,"file":"requireDescriptionCompleteSentence.cjs","names":["_iterateJsdoc","_interopRequireDefault","require","_escapeStringRegexp","e","__esModule","default","otherDescriptiveTags","Set","extractParagraphs","text","split","extractSentences","abbreviationsRegex","txt","replaceAll","replace","sentenceEndGrouping","puncts","matchAll","map","sentEnd","sentence","idx","test","isNewLinePrecededByAPeriod","lastLineEndsSentence","lines","some","line","isCapitalized","str","toUpperCase","isTable","charAt","capitalize","slice","validateDescription","description","reportOrig","jsdocNode","sourceCode","tag","newlineBeforeCapsAssumesBadSentenceEnd","descriptionNoHeadings","paragraphs","filter","Boolean","paragraph","parIdx","sentences","fix","fixer","getText","findLast","RegExp","escapeStringRegexp","sentence_","beginning","reg","_$0","$1","replaceText","report","msg","tagObj","source","number","column","paragraphNoAbbreviations","_default","exports","iterateJsdoc","context","jsdoc","utils","abbreviations","options","length","abbreviation","join","getDescription","indices","match","index","toReversed","forEachPreferredTag","matchingJsdocTag","desc","name","getTagDescription","trim","tagsWithNames","getTagsByType","tags","tagsWithoutNames","filterTags","tagName","has","hasOptionTag","trimEnd","iterateAllJsdocs","meta","docs","url","fixable","schema","additionalProperties","properties","items","type","module"],"sources":["../../src/rules/requireDescriptionCompleteSentence.js"],"sourcesContent":["import iterateJsdoc from '../iterateJsdoc.js';\nimport escapeStringRegexp from 'escape-string-regexp';\n\nconst otherDescriptiveTags = new Set([\n  'classdesc', 'deprecated', 'exception', 'file', 'fileoverview', 'overview',\n  // 'copyright' and 'see' might be good addition, but as the former may be\n  //   sensitive text, and the latter may have just a link, they are not\n  //   included by default\n  'summary', 'throws', 'todo', 'yield', 'yields',\n]);\n\n/**\n * @param {string} text\n * @returns {string[]}\n */\nconst extractParagraphs = (text) => {\n  return text.split(/(?<![;:])\\n\\n+/v);\n};\n\n/**\n * @param {string} text\n * @param {string|RegExp} abbreviationsRegex\n * @returns {string[]}\n */\nconst extractSentences = (text, abbreviationsRegex) => {\n  const txt = text\n    // Remove all {} tags.\n    .replaceAll(/(?<!^)\\{[\\s\\S]*?\\}\\s*/gv, '')\n\n    // Remove custom abbreviations\n    .replace(abbreviationsRegex, '');\n\n  const sentenceEndGrouping = /([.?!])(?:\\s+|$)/gv;\n\n  const puncts = [\n    ...txt.matchAll(sentenceEndGrouping),\n  ].map((sentEnd) => {\n    return sentEnd[0];\n  });\n\n  return txt\n    .split(/[.?!](?:\\s+|$)/v)\n\n    // Re-add the dot.\n    .map((sentence, idx) => {\n      return !puncts[idx] && /^\\s*$/v.test(sentence) ? sentence : `${sentence}${puncts[idx] || ''}`;\n    });\n};\n\n/**\n * @param {string} text\n * @returns {boolean}\n */\nconst isNewLinePrecededByAPeriod = (text) => {\n  /** @type {boolean} */\n  let lastLineEndsSentence;\n\n  const lines = text.split('\\n');\n\n  return !lines.some((line) => {\n    if (lastLineEndsSentence === false && /^[A-Z][a-z]/v.test(line)) {\n      return true;\n    }\n\n    lastLineEndsSentence = /[.:?!\\|]$/v.test(line);\n\n    return false;\n  });\n};\n\n/**\n * @param {string} str\n * @returns {boolean}\n */\nconst isCapitalized = (str) => {\n  return str[0] === str[0].toUpperCase();\n};\n\n/**\n * @param {string} str\n * @returns {boolean}\n */\nconst isTable = (str) => {\n  return str.charAt(0) === '|';\n};\n\n/**\n * @param {string} str\n * @returns {string}\n */\nconst capitalize = (str) => {\n  return str.charAt(0).toUpperCase() + str.slice(1);\n};\n\n/**\n * @param {string} description\n * @param {import('../iterateJsdoc.js').Report} reportOrig\n * @param {import('eslint').Rule.Node} jsdocNode\n * @param {string|RegExp} abbreviationsRegex\n * @param {import('eslint').SourceCode} sourceCode\n * @param {import('comment-parser').Spec|{\n *   line: import('../iterateJsdoc.js').Integer\n * }} tag\n * @param {boolean} newlineBeforeCapsAssumesBadSentenceEnd\n * @returns {boolean}\n */\nconst validateDescription = (\n  description, reportOrig, jsdocNode, abbreviationsRegex,\n  sourceCode, tag, newlineBeforeCapsAssumesBadSentenceEnd,\n) => {\n  if (!description || (/^\\n+$/v).test(description)) {\n    return false;\n  }\n\n  const descriptionNoHeadings = description.replaceAll(/^\\s*#[^\\n]*(\\n|$)/gmv, '');\n\n  const paragraphs = extractParagraphs(descriptionNoHeadings).filter(Boolean);\n\n  return paragraphs.some((paragraph, parIdx) => {\n    const sentences = extractSentences(paragraph, abbreviationsRegex);\n\n    const fix = /** @type {import('eslint').Rule.ReportFixer} */ (fixer) => {\n      let text = sourceCode.getText(jsdocNode);\n\n      if (!/[.:?!]$/v.test(paragraph)) {\n        const line = paragraph.split('\\n').findLast(Boolean);\n        text = text.replace(new RegExp(`${escapeStringRegexp(\n          /** @type {string} */\n          (line),\n        )}$`, 'mv'), `${line}.`);\n      }\n\n      for (const sentence of sentences.filter((sentence_) => {\n        return !(/^\\s*$/v).test(sentence_) && !isCapitalized(sentence_) &&\n          !isTable(sentence_);\n      })) {\n        const beginning = sentence.split('\\n')[0];\n\n        if ('tag' in tag && tag.tag) {\n          const reg = new RegExp(`(@${escapeStringRegexp(tag.tag)}.*)${escapeStringRegexp(beginning)}`, 'v');\n\n          text = text.replace(reg, (_$0, $1) => {\n            return $1 + capitalize(beginning);\n          });\n        } else {\n          text = text.replace(new RegExp('((?:[.?!]|\\\\*|\\\\})\\\\s*)' + escapeStringRegexp(beginning), 'v'), '$1' + capitalize(beginning));\n        }\n      }\n\n      return fixer.replaceText(jsdocNode, text);\n    };\n\n    /**\n     * @param {string} msg\n     * @param {import('eslint').Rule.ReportFixer | null | undefined} fixer\n     * @param {{\n     *   line?: number | undefined;\n     *   column?: number | undefined;\n     * } | (import('comment-parser').Spec & {\n     *   line?: number | undefined;\n     *   column?: number | undefined;\n     * })} tagObj\n     * @returns {void}\n     */\n    const report = (msg, fixer, tagObj) => {\n      if ('line' in tagObj) {\n        /**\n         * @type {{\n         *   line: number;\n         * }}\n         */ (tagObj).line += parIdx * 2;\n      } else {\n        /** @type {import('comment-parser').Spec} */ (\n          tagObj\n        ).source[0].number += parIdx * 2;\n      }\n\n      // Avoid errors if old column doesn't exist here\n      tagObj.column = 0;\n      reportOrig(msg, fixer, tagObj);\n    };\n\n    if (sentences.some((sentence) => {\n      return (/^[.?!]$/v).test(sentence);\n    })) {\n      report('Sentences must be more than punctuation.', null, tag);\n    }\n\n    if (sentences.some((sentence) => {\n      return !(/^\\s*$/v).test(sentence) && !isCapitalized(sentence) && !isTable(sentence);\n    })) {\n      report('Sentences should start with an uppercase character.', fix, tag);\n    }\n\n    const paragraphNoAbbreviations = paragraph.replace(abbreviationsRegex, '');\n\n    if (!/(?:[.?!\\|]|```)\\s*$/v.test(paragraphNoAbbreviations)) {\n      report('Sentences must end with a period.', fix, tag);\n      return true;\n    }\n\n    if (newlineBeforeCapsAssumesBadSentenceEnd && !isNewLinePrecededByAPeriod(paragraphNoAbbreviations)) {\n      report('A line of text is started with an uppercase character, but the preceding line does not end the sentence.', null, tag);\n\n      return true;\n    }\n\n    return false;\n  });\n};\n\nexport default iterateJsdoc(({\n  context,\n  jsdoc,\n  jsdocNode,\n  report,\n  sourceCode,\n  utils,\n}) => {\n  const /** @type {{abbreviations: string[], newlineBeforeCapsAssumesBadSentenceEnd: boolean}} */ {\n    abbreviations = [],\n    newlineBeforeCapsAssumesBadSentenceEnd = false,\n  } = context.options[0] || {};\n\n  const abbreviationsRegex = abbreviations.length ?\n    new RegExp('\\\\b' + abbreviations.map((abbreviation) => {\n      return escapeStringRegexp(abbreviation.replaceAll(/\\.$/gv, '') + '.');\n    }).join('|') + '(?:$|\\\\s)', 'gv') :\n    '';\n\n  let {\n    description,\n  } = utils.getDescription();\n\n  const indices = [\n    ...description.matchAll(/```[\\s\\S]*```/gv),\n  ].map((match) => {\n    const {\n      index,\n    } = match;\n    const [\n      {\n        length,\n      },\n    ] = match;\n    return {\n      index,\n      length,\n    };\n  }).toReversed();\n\n  for (const {\n    index,\n    length,\n  } of indices) {\n    description = description.slice(0, index) +\n      description.slice(/** @type {import('../iterateJsdoc.js').Integer} */ (\n        index\n      ) + length);\n  }\n\n  if (validateDescription(description, report, jsdocNode, abbreviationsRegex, sourceCode, {\n    line: jsdoc.source[0].number + 1,\n  }, newlineBeforeCapsAssumesBadSentenceEnd)) {\n    return;\n  }\n\n  utils.forEachPreferredTag('description', (matchingJsdocTag) => {\n    const desc = `${matchingJsdocTag.name} ${utils.getTagDescription(matchingJsdocTag)}`.trim();\n    validateDescription(desc, report, jsdocNode, abbreviationsRegex, sourceCode, matchingJsdocTag, newlineBeforeCapsAssumesBadSentenceEnd);\n  }, true);\n\n  const {\n    tagsWithNames,\n  } = utils.getTagsByType(jsdoc.tags);\n  const tagsWithoutNames = utils.filterTags(({\n    tag: tagName,\n  }) => {\n    return otherDescriptiveTags.has(tagName) ||\n      utils.hasOptionTag(tagName) && !tagsWithNames.some(({\n        tag,\n      }) => {\n        // If user accidentally adds tags with names (or like `returns`\n        //  get parsed as having names), do not add to this list\n        return tag === tagName;\n      });\n  });\n\n  tagsWithNames.some((tag) => {\n    const desc = /** @type {string} */ (\n      utils.getTagDescription(tag)\n    ).replace(/^- /v, '').trimEnd();\n\n    return validateDescription(desc, report, jsdocNode, abbreviationsRegex, sourceCode, tag, newlineBeforeCapsAssumesBadSentenceEnd);\n  });\n\n  tagsWithoutNames.some((tag) => {\n    const desc = `${tag.name} ${utils.getTagDescription(tag)}`.trim();\n\n    return validateDescription(desc, report, jsdocNode, abbreviationsRegex, sourceCode, tag, newlineBeforeCapsAssumesBadSentenceEnd);\n  });\n}, {\n  iterateAllJsdocs: true,\n  meta: {\n    docs: {\n      description: 'Requires that block description, explicit `@description`, and `@param`/`@returns` tag descriptions are written in complete sentences.',\n      url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-description-complete-sentence.md#repos-sticky-header',\n    },\n    fixable: 'code',\n    schema: [\n      {\n        additionalProperties: false,\n        properties: {\n          abbreviations: {\n            description: `You can provide an \\`abbreviations\\` options array to avoid such strings of text\nbeing treated as sentence endings when followed by dots. The \\`.\\` is not\nnecessary at the end of the array items.`,\n            items: {\n              type: 'string',\n            },\n            type: 'array',\n          },\n          newlineBeforeCapsAssumesBadSentenceEnd: {\n            description: `When \\`false\\` (the new default), we will not assume capital letters after\nnewlines are an incorrect way to end the sentence (they may be proper\nnouns, for example).`,\n            type: 'boolean',\n          },\n          tags: {\n            description: `If you want additional tags to be checked for their descriptions, you may\nadd them within this option.\n\n\\`\\`\\`js\n{\n  'jsdoc/require-description-complete-sentence': ['error', {\n    tags: ['see', 'copyright']\n  }]\n}\n\\`\\`\\`\n\nThe tags \\`@param\\`/\\`@arg\\`/\\`@argument\\` and \\`@property\\`/\\`@prop\\` will be properly\nparsed to ensure that the checked \"description\" text includes only the text\nafter the name.\n\nAll other tags will treat the text following the tag name, a space, and\nan optional curly-bracketed type expression (and another space) as part of\nits \"description\" (e.g., for \\`@returns {someType} some description\\`, the\ndescription is \\`some description\\` while for \\`@some-tag xyz\\`, the description\nis \\`xyz\\`).\n`,\n            items: {\n              type: 'string',\n            },\n            type: 'array',\n          },\n        },\n        type: 'object',\n      },\n    ],\n    type: 'suggestion',\n  },\n});\n"],"mappings":"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","ignoreList":[]}

package/dist/rules/requireExample.cjs

@@ -46,7 +46,7 @@ var _default = exports.default = (0, _iterateJsdoc.default)(({
   contextDefaults: true,
   meta: {
     docs: {
-      description: 'Requires that all functions have examples.',
+      description: 'Requires that all functions (and potentially other contexts) have examples.',
       url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-example.md#repos-sticky-header'
     },
     fixable: 'code',
@@ -55,17 +55,33 @@ var _default = exports.default = (0, _iterateJsdoc.default)(({
       properties: {
         checkConstructors: {
           default: true,
+          description: `A value indicating whether \`constructor\`s should be checked.
+Defaults to \`true\`.`,
           type: 'boolean'
         },
         checkGetters: {
           default: false,
+          description: 'A value indicating whether getters should be checked. Defaults to `false`.',
           type: 'boolean'
         },
         checkSetters: {
           default: false,
+          description: 'A value indicating whether setters should be checked. Defaults to `false`.',
           type: 'boolean'
         },
         contexts: {
+          description: `Set this to an array of strings representing the AST context (or an object with
+optional \`context\` and \`comment\` properties) where you wish the rule to be applied.
+(e.g., \`ClassDeclaration\` for ES6 classes).
+
+\`context\` defaults to \`any\` and \`comment\` defaults to no specific comment context.
+
+Overrides the default contexts (\`ArrowFunctionExpression\`, \`FunctionDeclaration\`,
+\`FunctionExpression\`). Set to \`"any"\` if you want the rule to apply to any
+JSDoc block throughout your files.
+
+See the ["AST and Selectors"](../#advanced-ast-and-selectors)
+section of our Advanced docs for more on the expected format.`,
           items: {
             anyOf: [{
               type: 'string'
@@ -86,9 +102,16 @@ var _default = exports.default = (0, _iterateJsdoc.default)(({
         },
         enableFixer: {
           default: true,
+          description: `A boolean on whether to enable the fixer (which adds an empty \`@example\` block).
+Defaults to \`true\`.`,
           type: 'boolean'
         },
         exemptedBy: {
+          description: `Array of tags (e.g., \`['type']\`) whose presence on the document
+block avoids the need for an \`@example\`. Defaults to an array with
+\`inheritdoc\`. If you set this array, it will overwrite the default,
+so be sure to add back \`inheritdoc\` if you wish its presence to cause
+exemption of the rule.`,
           items: {
             type: 'string'
           },
@@ -96,6 +119,8 @@ var _default = exports.default = (0, _iterateJsdoc.default)(({
         },
         exemptNoArguments: {
           default: false,
+          description: `Boolean to indicate that no-argument functions should not be reported for
+missing \`@example\` declarations.`,
           type: 'boolean'
         }
       },

package/dist/rules/requireExample.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"requireExample.cjs","names":["_iterateJsdoc","_interopRequireDefault","require","e","__esModule","default","_default","exports","iterateJsdoc","context","jsdoc","report","utils","avoidDocs","enableFixer","exemptNoArguments","options","targetTagName","functionExamples","tags","filter","tag","length","isIteratingFunctionOrVariable","hasParams","reportJSDoc","addTag","example","exampleContent","name","getTagDescription","trim","split","Boolean","contextDefaults","meta","docs","description","url","fixable","schema","additionalProperties","properties","checkConstructors","type","checkGetters","checkSetters","contexts","items","anyOf","comment","exemptedBy","module"],"sources":["../../src/rules/requireExample.js"],"sourcesContent":["import iterateJsdoc from '../iterateJsdoc.js';\n\nexport default iterateJsdoc(({\n  context,\n  jsdoc,\n  report,\n  utils,\n}) => {\n  if (utils.avoidDocs()) {\n    return;\n  }\n\n  const {\n    enableFixer = true,\n    exemptNoArguments = false,\n  } = context.options[0] || {};\n\n  const targetTagName = 'example';\n\n  const functionExamples = jsdoc.tags.filter(({\n    tag,\n  }) => {\n    return tag === targetTagName;\n  });\n\n  if (!functionExamples.length) {\n    if (exemptNoArguments && utils.isIteratingFunctionOrVariable() &&\n      !utils.hasParams()\n    ) {\n      return;\n    }\n\n    utils.reportJSDoc(`Missing JSDoc @${targetTagName} declaration.`, null, () => {\n      if (enableFixer) {\n        utils.addTag(targetTagName);\n      }\n    });\n\n    return;\n  }\n\n  for (const example of functionExamples) {\n    const exampleContent = `${example.name} ${utils.getTagDescription(example)}`\n      .trim()\n      .split('\\n')\n      .filter(Boolean);\n\n    if (!exampleContent.length) {\n      report(`Missing JSDoc @${targetTagName} description.`, null, example);\n    }\n  }\n}, {\n  contextDefaults: true,\n  meta: {\n    docs: {\n      description: 'Requires that all functions have examples.',\n      url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-example.md#repos-sticky-header',\n    },\n    fixable: 'code',\n    schema: [\n      {\n        additionalProperties: false,\n        properties: {\n          checkConstructors: {\n            default: true,\n            type: 'boolean',\n          },\n          checkGetters: {\n            default: false,\n            type: 'boolean',\n          },\n          checkSetters: {\n            default: false,\n            type: 'boolean',\n          },\n          contexts: {\n            items: {\n              anyOf: [\n                {\n                  type: 'string',\n                },\n                {\n                  additionalProperties: false,\n                  properties: {\n                    comment: {\n                      type: 'string',\n                    },\n                    context: {\n                      type: 'string',\n                    },\n                  },\n                  type: 'object',\n                },\n              ],\n            },\n            type: 'array',\n          },\n          enableFixer: {\n            default: true,\n            type: 'boolean',\n          },\n          exemptedBy: {\n            items: {\n              type: 'string',\n            },\n            type: 'array',\n          },\n          exemptNoArguments: {\n            default: false,\n            type: 'boolean',\n          },\n        },\n        type: 'object',\n      },\n    ],\n    type: 'suggestion',\n  },\n});\n"],"mappings":"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","ignoreList":[]}
+{"version":3,"file":"requireExample.cjs","names":["_iterateJsdoc","_interopRequireDefault","require","e","__esModule","default","_default","exports","iterateJsdoc","context","jsdoc","report","utils","avoidDocs","enableFixer","exemptNoArguments","options","targetTagName","functionExamples","tags","filter","tag","length","isIteratingFunctionOrVariable","hasParams","reportJSDoc","addTag","example","exampleContent","name","getTagDescription","trim","split","Boolean","contextDefaults","meta","docs","description","url","fixable","schema","additionalProperties","properties","checkConstructors","type","checkGetters","checkSetters","contexts","items","anyOf","comment","exemptedBy","module"],"sources":["../../src/rules/requireExample.js"],"sourcesContent":["import iterateJsdoc from '../iterateJsdoc.js';\n\nexport default iterateJsdoc(({\n  context,\n  jsdoc,\n  report,\n  utils,\n}) => {\n  if (utils.avoidDocs()) {\n    return;\n  }\n\n  const {\n    enableFixer = true,\n    exemptNoArguments = false,\n  } = context.options[0] || {};\n\n  const targetTagName = 'example';\n\n  const functionExamples = jsdoc.tags.filter(({\n    tag,\n  }) => {\n    return tag === targetTagName;\n  });\n\n  if (!functionExamples.length) {\n    if (exemptNoArguments && utils.isIteratingFunctionOrVariable() &&\n      !utils.hasParams()\n    ) {\n      return;\n    }\n\n    utils.reportJSDoc(`Missing JSDoc @${targetTagName} declaration.`, null, () => {\n      if (enableFixer) {\n        utils.addTag(targetTagName);\n      }\n    });\n\n    return;\n  }\n\n  for (const example of functionExamples) {\n    const exampleContent = `${example.name} ${utils.getTagDescription(example)}`\n      .trim()\n      .split('\\n')\n      .filter(Boolean);\n\n    if (!exampleContent.length) {\n      report(`Missing JSDoc @${targetTagName} description.`, null, example);\n    }\n  }\n}, {\n  contextDefaults: true,\n  meta: {\n    docs: {\n      description: 'Requires that all functions (and potentially other contexts) have examples.',\n      url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-example.md#repos-sticky-header',\n    },\n    fixable: 'code',\n    schema: [\n      {\n        additionalProperties: false,\n        properties: {\n          checkConstructors: {\n            default: true,\n            description: `A value indicating whether \\`constructor\\`s should be checked.\nDefaults to \\`true\\`.`,\n            type: 'boolean',\n          },\n          checkGetters: {\n            default: false,\n            description: 'A value indicating whether getters should be checked. Defaults to `false`.',\n            type: 'boolean',\n          },\n          checkSetters: {\n            default: false,\n            description: 'A value indicating whether setters should be checked. Defaults to `false`.',\n            type: 'boolean',\n          },\n          contexts: {\n            description: `Set this to an array of strings representing the AST context (or an object with\noptional \\`context\\` and \\`comment\\` properties) where you wish the rule to be applied.\n(e.g., \\`ClassDeclaration\\` for ES6 classes).\n\n\\`context\\` defaults to \\`any\\` and \\`comment\\` defaults to no specific comment context.\n\nOverrides the default contexts (\\`ArrowFunctionExpression\\`, \\`FunctionDeclaration\\`,\n\\`FunctionExpression\\`). Set to \\`\"any\"\\` if you want the rule to apply to any\nJSDoc block throughout your files.\n\nSee the [\"AST and Selectors\"](../#advanced-ast-and-selectors)\nsection of our Advanced docs for more on the expected format.`,\n            items: {\n              anyOf: [\n                {\n                  type: 'string',\n                },\n                {\n                  additionalProperties: false,\n                  properties: {\n                    comment: {\n                      type: 'string',\n                    },\n                    context: {\n                      type: 'string',\n                    },\n                  },\n                  type: 'object',\n                },\n              ],\n            },\n            type: 'array',\n          },\n          enableFixer: {\n            default: true,\n            description: `A boolean on whether to enable the fixer (which adds an empty \\`@example\\` block).\nDefaults to \\`true\\`.`,\n            type: 'boolean',\n          },\n          exemptedBy: {\n            description: `Array of tags (e.g., \\`['type']\\`) whose presence on the document\nblock avoids the need for an \\`@example\\`. Defaults to an array with\n\\`inheritdoc\\`. If you set this array, it will overwrite the default,\nso be sure to add back \\`inheritdoc\\` if you wish its presence to cause\nexemption of the rule.`,\n            items: {\n              type: 'string',\n            },\n            type: 'array',\n          },\n          exemptNoArguments: {\n            default: false,\n            description: `Boolean to indicate that no-argument functions should not be reported for\nmissing \\`@example\\` declarations.`,\n            type: 'boolean',\n          },\n        },\n        type: 'object',\n      },\n    ],\n    type: 'suggestion',\n  },\n});\n"],"mappings":"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","ignoreList":[]}

package/dist/rules/requireFileOverview.cjs

@@ -98,6 +98,67 @@ var _default = exports.default = (0, _iterateJsdoc.default)(({
       additionalProperties: false,
       properties: {
         tags: {
+          description: `The keys of this object are tag names, and the values are configuration
+objects indicating what will be checked for these whole-file tags.
+
+Each configuration object has 3 potential boolean keys (which default
+to \`false\` when this option is supplied).
+
+1. \`mustExist\` - enforces that all files have a \`@file\`, \`@fileoverview\`, or \`@overview\` tag.
+2. \`preventDuplicates\` - enforces that duplicate file overview tags within a given file will be reported
+3. \`initialCommentsOnly\` - reports file overview tags which are not, as per
+  [the docs](https://jsdoc.app/tags-file.html), "at the beginning of
+  the file"–where beginning of the file is interpreted in this rule
+  as being when the overview tag is not preceded by anything other than
+  a comment.
+
+When no \`tags\` is present, the default is:
+
+\`\`\`json
+{
+  "file": {
+    "initialCommentsOnly": true,
+    "mustExist": true,
+    "preventDuplicates": true,
+  }
+}
+\`\`\`
+
+You can add additional tag names and/or override \`file\` if you supply this
+option, e.g., in place of or in addition to \`file\`, giving other potential
+file global tags like \`@license\`, \`@copyright\`, \`@author\`, \`@module\` or
+\`@exports\`, optionally restricting them to a single use or preventing them
+from being preceded by anything besides comments.
+
+For example:
+
+\`\`\`js
+{
+  "license": {
+    "mustExist": true,
+    "preventDuplicates": true,
+  }
+}
+\`\`\`
+
+This would require one and only one \`@license\` in the file, though because
+\`initialCommentsOnly\` is absent and defaults to \`false\`, the \`@license\`
+can be anywhere.
+
+In the case of \`@license\`, you can use this rule along with the
+\`check-values\` rule (with its \`allowedLicenses\` or \`licensePattern\` options),
+to enforce a license whitelist be present on every JS file.
+
+Note that if you choose to use \`preventDuplicates\` with \`license\`, you still
+have a way to allow multiple licenses for the whole page by using the SPDX
+"AND" expression, e.g., \`@license (MIT AND GPL-3.0)\`.
+
+Note that the tag names are the main JSDoc tag name, so you should use \`file\`
+in this configuration object regardless of whether you have configured
+\`fileoverview\` instead of \`file\` on \`tagNamePreference\` (i.e., \`fileoverview\`
+will be checked, but you must use \`file\` on the configuration object).
+
+`,
           patternProperties: {
             '.*': {
               additionalProperties: false,

package/dist/rules/requireFileOverview.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"requireFileOverview.cjs","names":["_iterateJsdoc","_interopRequireDefault","require","e","__esModule","default","defaultTags","file","initialCommentsOnly","mustExist","preventDuplicates","setDefaults","state","globalTags","hasDuplicates","hasTag","hasNonCommentBeforeTag","_default","exports","iterateJsdoc","context","jsdocNode","utils","tags","options","tagName","Object","keys","targetTagName","getPreferredTagName","Boolean","hasDuplicate","hasNonComment","range","exit","entries","obj","getPreferredTagNameObject","reportSettings","replacement","iterateAllJsdocs","meta","docs","description","url","schema","additionalProperties","properties","patternProperties","type","nonComment","node","module"],"sources":["../../src/rules/requireFileOverview.js"],"sourcesContent":["import iterateJsdoc from '../iterateJsdoc.js';\n\nconst defaultTags = {\n  file: {\n    initialCommentsOnly: true,\n    mustExist: true,\n    preventDuplicates: true,\n  },\n};\n\n/**\n * @param {import('../iterateJsdoc.js').StateObject} state\n * @returns {void}\n */\nconst setDefaults = (state) => {\n  // First iteration\n  if (!state.globalTags) {\n    state.globalTags = {};\n    state.hasDuplicates = {};\n    state.hasTag = {};\n    state.hasNonCommentBeforeTag = {};\n  }\n};\n\nexport default iterateJsdoc(({\n  context,\n  jsdocNode,\n  state,\n  utils,\n}) => {\n  const {\n    tags = defaultTags,\n  } = context.options[0] || {};\n\n  setDefaults(state);\n\n  for (const tagName of Object.keys(tags)) {\n    const targetTagName = /** @type {string} */ (utils.getPreferredTagName({\n      tagName,\n    }));\n\n    const hasTag = Boolean(targetTagName && utils.hasTag(targetTagName));\n\n    state.hasTag[tagName] = hasTag || state.hasTag[tagName];\n\n    const hasDuplicate = state.hasDuplicates[tagName];\n\n    if (hasDuplicate === false) {\n      // Was marked before, so if a tag now, is a dupe\n      state.hasDuplicates[tagName] = hasTag;\n    } else if (!hasDuplicate && hasTag) {\n      // No dupes set before, but has first tag, so change state\n      //   from `undefined` to `false` so can detect next time\n      state.hasDuplicates[tagName] = false;\n      state.hasNonCommentBeforeTag[tagName] = state.hasNonComment &&\n        state.hasNonComment < jsdocNode.range[0];\n    }\n  }\n}, {\n  exit ({\n    context,\n    state,\n    utils,\n  }) {\n    setDefaults(state);\n    const {\n      tags = defaultTags,\n    } = context.options[0] || {};\n\n    for (const [\n      tagName,\n      {\n        initialCommentsOnly = false,\n        mustExist = false,\n        preventDuplicates = false,\n      },\n    ] of Object.entries(tags)) {\n      const obj = utils.getPreferredTagNameObject({\n        tagName,\n      });\n      if (obj && typeof obj === 'object' && 'blocked' in obj) {\n        utils.reportSettings(\n          `\\`settings.jsdoc.tagNamePreference\\` cannot block @${obj.tagName} ` +\n          'for the `require-file-overview` rule',\n        );\n      } else {\n        const targetTagName = (\n          obj && typeof obj === 'object' && obj.replacement\n        ) || obj;\n        if (mustExist && !state.hasTag[tagName]) {\n          utils.reportSettings(`Missing @${targetTagName}`);\n        }\n\n        if (preventDuplicates && state.hasDuplicates[tagName]) {\n          utils.reportSettings(\n            `Duplicate @${targetTagName}`,\n          );\n        }\n\n        if (initialCommentsOnly &&\n            state.hasNonCommentBeforeTag[tagName]\n        ) {\n          utils.reportSettings(\n            `@${targetTagName} should be at the beginning of the file`,\n          );\n        }\n      }\n    }\n  },\n  iterateAllJsdocs: true,\n  meta: {\n    docs: {\n      description: 'Checks that all files have one `@file`, `@fileoverview`, or `@overview` tag at the beginning of the file.',\n      url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-file-overview.md#repos-sticky-header',\n    },\n    schema: [\n      {\n        additionalProperties: false,\n        properties: {\n          tags: {\n            patternProperties: {\n              '.*': {\n                additionalProperties: false,\n                properties: {\n                  initialCommentsOnly: {\n                    type: 'boolean',\n                  },\n                  mustExist: {\n                    type: 'boolean',\n                  },\n                  preventDuplicates: {\n                    type: 'boolean',\n                  },\n                },\n                type: 'object',\n              },\n            },\n            type: 'object',\n          },\n        },\n        type: 'object',\n      },\n    ],\n    type: 'suggestion',\n  },\n  nonComment ({\n    node,\n    state,\n  }) {\n    if (!state.hasNonComment) {\n      state.hasNonComment = node.range[0];\n    }\n  },\n});\n"],"mappings":"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","ignoreList":[]}
+{"version":3,"file":"requireFileOverview.cjs","names":["_iterateJsdoc","_interopRequireDefault","require","e","__esModule","default","defaultTags","file","initialCommentsOnly","mustExist","preventDuplicates","setDefaults","state","globalTags","hasDuplicates","hasTag","hasNonCommentBeforeTag","_default","exports","iterateJsdoc","context","jsdocNode","utils","tags","options","tagName","Object","keys","targetTagName","getPreferredTagName","Boolean","hasDuplicate","hasNonComment","range","exit","entries","obj","getPreferredTagNameObject","reportSettings","replacement","iterateAllJsdocs","meta","docs","description","url","schema","additionalProperties","properties","patternProperties","type","nonComment","node","module"],"sources":["../../src/rules/requireFileOverview.js"],"sourcesContent":["import iterateJsdoc from '../iterateJsdoc.js';\n\nconst defaultTags = {\n  file: {\n    initialCommentsOnly: true,\n    mustExist: true,\n    preventDuplicates: true,\n  },\n};\n\n/**\n * @param {import('../iterateJsdoc.js').StateObject} state\n * @returns {void}\n */\nconst setDefaults = (state) => {\n  // First iteration\n  if (!state.globalTags) {\n    state.globalTags = {};\n    state.hasDuplicates = {};\n    state.hasTag = {};\n    state.hasNonCommentBeforeTag = {};\n  }\n};\n\nexport default iterateJsdoc(({\n  context,\n  jsdocNode,\n  state,\n  utils,\n}) => {\n  const {\n    tags = defaultTags,\n  } = context.options[0] || {};\n\n  setDefaults(state);\n\n  for (const tagName of Object.keys(tags)) {\n    const targetTagName = /** @type {string} */ (utils.getPreferredTagName({\n      tagName,\n    }));\n\n    const hasTag = Boolean(targetTagName && utils.hasTag(targetTagName));\n\n    state.hasTag[tagName] = hasTag || state.hasTag[tagName];\n\n    const hasDuplicate = state.hasDuplicates[tagName];\n\n    if (hasDuplicate === false) {\n      // Was marked before, so if a tag now, is a dupe\n      state.hasDuplicates[tagName] = hasTag;\n    } else if (!hasDuplicate && hasTag) {\n      // No dupes set before, but has first tag, so change state\n      //   from `undefined` to `false` so can detect next time\n      state.hasDuplicates[tagName] = false;\n      state.hasNonCommentBeforeTag[tagName] = state.hasNonComment &&\n        state.hasNonComment < jsdocNode.range[0];\n    }\n  }\n}, {\n  exit ({\n    context,\n    state,\n    utils,\n  }) {\n    setDefaults(state);\n    const {\n      tags = defaultTags,\n    } = context.options[0] || {};\n\n    for (const [\n      tagName,\n      {\n        initialCommentsOnly = false,\n        mustExist = false,\n        preventDuplicates = false,\n      },\n    ] of Object.entries(tags)) {\n      const obj = utils.getPreferredTagNameObject({\n        tagName,\n      });\n      if (obj && typeof obj === 'object' && 'blocked' in obj) {\n        utils.reportSettings(\n          `\\`settings.jsdoc.tagNamePreference\\` cannot block @${obj.tagName} ` +\n          'for the `require-file-overview` rule',\n        );\n      } else {\n        const targetTagName = (\n          obj && typeof obj === 'object' && obj.replacement\n        ) || obj;\n        if (mustExist && !state.hasTag[tagName]) {\n          utils.reportSettings(`Missing @${targetTagName}`);\n        }\n\n        if (preventDuplicates && state.hasDuplicates[tagName]) {\n          utils.reportSettings(\n            `Duplicate @${targetTagName}`,\n          );\n        }\n\n        if (initialCommentsOnly &&\n            state.hasNonCommentBeforeTag[tagName]\n        ) {\n          utils.reportSettings(\n            `@${targetTagName} should be at the beginning of the file`,\n          );\n        }\n      }\n    }\n  },\n  iterateAllJsdocs: true,\n  meta: {\n    docs: {\n      description: 'Checks that all files have one `@file`, `@fileoverview`, or `@overview` tag at the beginning of the file.',\n      url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-file-overview.md#repos-sticky-header',\n    },\n    schema: [\n      {\n        additionalProperties: false,\n        properties: {\n          tags: {\n            description: `The keys of this object are tag names, and the values are configuration\nobjects indicating what will be checked for these whole-file tags.\n\nEach configuration object has 3 potential boolean keys (which default\nto \\`false\\` when this option is supplied).\n\n1. \\`mustExist\\` - enforces that all files have a \\`@file\\`, \\`@fileoverview\\`, or \\`@overview\\` tag.\n2. \\`preventDuplicates\\` - enforces that duplicate file overview tags within a given file will be reported\n3. \\`initialCommentsOnly\\` - reports file overview tags which are not, as per\n  [the docs](https://jsdoc.app/tags-file.html), \"at the beginning of\n  the file\"–where beginning of the file is interpreted in this rule\n  as being when the overview tag is not preceded by anything other than\n  a comment.\n\nWhen no \\`tags\\` is present, the default is:\n\n\\`\\`\\`json\n{\n  \"file\": {\n    \"initialCommentsOnly\": true,\n    \"mustExist\": true,\n    \"preventDuplicates\": true,\n  }\n}\n\\`\\`\\`\n\nYou can add additional tag names and/or override \\`file\\` if you supply this\noption, e.g., in place of or in addition to \\`file\\`, giving other potential\nfile global tags like \\`@license\\`, \\`@copyright\\`, \\`@author\\`, \\`@module\\` or\n\\`@exports\\`, optionally restricting them to a single use or preventing them\nfrom being preceded by anything besides comments.\n\nFor example:\n\n\\`\\`\\`js\n{\n  \"license\": {\n    \"mustExist\": true,\n    \"preventDuplicates\": true,\n  }\n}\n\\`\\`\\`\n\nThis would require one and only one \\`@license\\` in the file, though because\n\\`initialCommentsOnly\\` is absent and defaults to \\`false\\`, the \\`@license\\`\ncan be anywhere.\n\nIn the case of \\`@license\\`, you can use this rule along with the\n\\`check-values\\` rule (with its \\`allowedLicenses\\` or \\`licensePattern\\` options),\nto enforce a license whitelist be present on every JS file.\n\nNote that if you choose to use \\`preventDuplicates\\` with \\`license\\`, you still\nhave a way to allow multiple licenses for the whole page by using the SPDX\n\"AND\" expression, e.g., \\`@license (MIT AND GPL-3.0)\\`.\n\nNote that the tag names are the main JSDoc tag name, so you should use \\`file\\`\nin this configuration object regardless of whether you have configured\n\\`fileoverview\\` instead of \\`file\\` on \\`tagNamePreference\\` (i.e., \\`fileoverview\\`\nwill be checked, but you must use \\`file\\` on the configuration object).\n\n`,\n            patternProperties: {\n              '.*': {\n                additionalProperties: false,\n                properties: {\n                  initialCommentsOnly: {\n                    type: 'boolean',\n                  },\n                  mustExist: {\n                    type: 'boolean',\n                  },\n                  preventDuplicates: {\n                    type: 'boolean',\n                  },\n                },\n                type: 'object',\n              },\n            },\n            type: 'object',\n          },\n        },\n        type: 'object',\n      },\n    ],\n    type: 'suggestion',\n  },\n  nonComment ({\n    node,\n    state,\n  }) {\n    if (!state.hasNonComment) {\n      state.hasNonComment = node.range[0];\n    }\n  },\n});\n"],"mappings":"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BAAsB,CAACS,OAAO,CAAC,EACvC;UACAH,KAAK,CAACgB,cAAc,CAClB,IAAIV,aAAa,yCACnB,CAAC;QACH;MACF;IACF;EACF,CAAC;EACDY,gBAAgB,EAAE,IAAI;EACtBC,IAAI,EAAE;IACJC,IAAI,EAAE;MACJC,WAAW,EAAE,2GAA2G;MACxHC,GAAG,EAAE;IACP,CAAC;IACDC,MAAM,EAAE,CACN;MACEC,oBAAoB,EAAE,KAAK;MAC3BC,UAAU,EAAE;QACVxB,IAAI,EAAE;UACJoB,WAAW,EAAE;AACzB;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,CAAC;UACWK,iBAAiB,EAAE;YACjB,IAAI,EAAE;cACJF,oBAAoB,EAAE,KAAK;cAC3BC,UAAU,EAAE;gBACVvC,mBAAmB,EAAE;kBACnByC,IAAI,EAAE;gBACR,CAAC;gBACDxC,SAAS,EAAE;kBACTwC,IAAI,EAAE;gBACR,CAAC;gBACDvC,iBAAiB,EAAE;kBACjBuC,IAAI,EAAE;gBACR;cACF,CAAC;cACDA,IAAI,EAAE;YACR;UACF,CAAC;UACDA,IAAI,EAAE;QACR;MACF,CAAC;MACDA,IAAI,EAAE;IACR,CAAC,CACF;IACDA,IAAI,EAAE;EACR,CAAC;EACDC,UAAUA,CAAE;IACVC,IAAI;IACJvC;EACF,CAAC,EAAE;IACD,IAAI,CAACA,KAAK,CAACoB,aAAa,EAAE;MACxBpB,KAAK,CAACoB,aAAa,GAAGmB,IAAI,CAAClB,KAAK,CAAC,CAAC,CAAC;IACrC;EACF;AACF,CAAC,CAAC;AAAAmB,MAAA,CAAAlC,OAAA,GAAAA,OAAA,CAAAb,OAAA","ignoreList":[]}

package/dist/rules/requireHyphenBeforeParamDescription.cjs

@@ -115,15 +115,25 @@ var _default = exports.default = (0, _iterateJsdoc.default)(({
   iterateAllJsdocs: true,
   meta: {
     docs: {
-      description: 'Requires a hyphen before the `@param` description.',
+      description: 'Requires a hyphen before the `@param` description (and optionally before `@property` descriptions).',
       url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-hyphen-before-param-description.md#repos-sticky-header'
     },
     fixable: 'code',
     schema: [{
+      description: `If the string is \`"always"\` then a problem is raised when there is no hyphen
+before the description. If it is \`"never"\` then a problem is raised when there
+is a hyphen before the description. The default value is \`"always"\`.
+
+Even if hyphens are set to "always" appear after the tag name, they will
+actually be forbidden in the event that they are followed immediately by
+the end of a line (this will otherwise cause Visual Studio Code to display
+incorrectly).`,
       enum: ['always', 'never'],
       type: 'string'
     }, {
       additionalProperties: false,
+      description: `The options object may have the following property to indicate behavior for
+other tags besides the \`@param\` tag (or the \`@arg\` tag if so set).`,
       properties: {
         tags: {
           anyOf: [{
@@ -137,7 +147,15 @@ var _default = exports.default = (0, _iterateJsdoc.default)(({
           }, {
             enum: ['any'],
             type: 'string'
-          }]
+          }],
+          description: `Object whose keys indicate different tags to check for the
+  presence or absence of hyphens; the key value should be "always" or "never",
+  indicating how hyphens are to be applied, e.g., \`{property: 'never'}\`
+  to ensure \`@property\` never uses hyphens. A key can also be set as \`*\`, e.g.,
+  \`'*': 'always'\` to apply hyphen checking to any tag (besides the preferred
+  \`@param\` tag which follows the main string option setting and besides any
+  other \`tags\` entries).
+`
         }
       },
       type: 'object'

package/dist/rules/requireHyphenBeforeParamDescription.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"requireHyphenBeforeParamDescription.cjs","names":["_iterateJsdoc","_interopRequireDefault","require","e","__esModule","default","_default","exports","iterateJsdoc","context","jsdoc","utils","mainCircumstance","tags","options","tgs","checkHyphens","jsdocTag","targetTagName","circumstance","always","desc","getTagDescription","trim","startsWithHyphen","test","hyphenNewline","lines","tokens","source","description","fixIt","replace","name","reportJSDoc","line","number","postName","forEachPreferredTag","tagEntries","Object","entries","tagName","preferredParamTag","getPreferredTagName","tag","some","tagNme","iterateAllJsdocs","meta","docs","url","fixable","schema","enum","type","additionalProperties","properties","anyOf","patternProperties","module"],"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.',\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        enum: [\n          'always', 'never',\n        ],\n        type: 'string',\n      },\n      {\n        additionalProperties: false,\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          },\n        },\n        type: 'object',\n      },\n    ],\n    type: 'layout',\n  },\n});\n"],"mappings":"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","ignoreList":[]}
+{"version":3,"file":"requireHyphenBeforeParamDescription.cjs","names":["_iterateJsdoc","_interopRequireDefault","require","e","__esModule","default","_default","exports","iterateJsdoc","context","jsdoc","utils","mainCircumstance","tags","options","tgs","checkHyphens","jsdocTag","targetTagName","circumstance","always","desc","getTagDescription","trim","startsWithHyphen","test","hyphenNewline","lines","tokens","source","description","fixIt","replace","name","reportJSDoc","line","number","postName","forEachPreferredTag","tagEntries","Object","entries","tagName","preferredParamTag","getPreferredTagName","tag","some","tagNme","iterateAllJsdocs","meta","docs","url","fixable","schema","enum","type","additionalProperties","properties","anyOf","patternProperties","module"],"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        },\n        type: 'object',\n      },\n    ],\n    type: 'layout',\n  },\n});\n"],"mappings":"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","ignoreList":[]}