eslint-plugin-jsdoc 53.0.1 → 54.0.0

package/src/rules/requireExample.js

@@ -0,0 +1,118 @@
+import iterateJsdoc from '../iterateJsdoc.js';
+
+export default iterateJsdoc(({
+  context,
+  jsdoc,
+  report,
+  utils,
+}) => {
+  if (utils.avoidDocs()) {
+    return;
+  }
+
+  const {
+    enableFixer = true,
+    exemptNoArguments = false,
+  } = context.options[0] || {};
+
+  const targetTagName = 'example';
+
+  const functionExamples = jsdoc.tags.filter(({
+    tag,
+  }) => {
+    return tag === targetTagName;
+  });
+
+  if (!functionExamples.length) {
+    if (exemptNoArguments && utils.isIteratingFunctionOrVariable() &&
+      !utils.hasParams()
+    ) {
+      return;
+    }
+
+    utils.reportJSDoc(`Missing JSDoc @${targetTagName} declaration.`, null, () => {
+      if (enableFixer) {
+        utils.addTag(targetTagName);
+      }
+    });
+
+    return;
+  }
+
+  for (const example of functionExamples) {
+    const exampleContent = `${example.name} ${utils.getTagDescription(example)}`
+      .trim()
+      .split('\n')
+      .filter(Boolean);
+
+    if (!exampleContent.length) {
+      report(`Missing JSDoc @${targetTagName} description.`, null, example);
+    }
+  }
+}, {
+  contextDefaults: true,
+  meta: {
+    docs: {
+      description: 'Requires that all functions have examples.',
+      url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-example.md#repos-sticky-header',
+    },
+    fixable: 'code',
+    schema: [
+      {
+        additionalProperties: false,
+        properties: {
+          checkConstructors: {
+            default: true,
+            type: 'boolean',
+          },
+          checkGetters: {
+            default: false,
+            type: 'boolean',
+          },
+          checkSetters: {
+            default: false,
+            type: 'boolean',
+          },
+          contexts: {
+            items: {
+              anyOf: [
+                {
+                  type: 'string',
+                },
+                {
+                  additionalProperties: false,
+                  properties: {
+                    comment: {
+                      type: 'string',
+                    },
+                    context: {
+                      type: 'string',
+                    },
+                  },
+                  type: 'object',
+                },
+              ],
+            },
+            type: 'array',
+          },
+          enableFixer: {
+            default: true,
+            type: 'boolean',
+          },
+          exemptedBy: {
+            items: {
+              type: 'string',
+            },
+            type: 'array',
+          },
+          exemptNoArguments: {
+            default: false,
+            type: 'boolean',
+          },
+        },
+        type: 'object',
+      },
+    ],
+    type: 'suggestion',
+  },
+});

package/src/rules/requireFileOverview.js

@@ -0,0 +1,154 @@
+import iterateJsdoc from '../iterateJsdoc.js';
+
+const defaultTags = {
+  file: {
+    initialCommentsOnly: true,
+    mustExist: true,
+    preventDuplicates: true,
+  },
+};
+
+/**
+ * @param {import('../iterateJsdoc.js').StateObject} state
+ * @returns {void}
+ */
+const setDefaults = (state) => {
+  // First iteration
+  if (!state.globalTags) {
+    state.globalTags = {};
+    state.hasDuplicates = {};
+    state.hasTag = {};
+    state.hasNonCommentBeforeTag = {};
+  }
+};
+
+export default iterateJsdoc(({
+  context,
+  jsdocNode,
+  state,
+  utils,
+}) => {
+  const {
+    tags = defaultTags,
+  } = context.options[0] || {};
+
+  setDefaults(state);
+
+  for (const tagName of Object.keys(tags)) {
+    const targetTagName = /** @type {string} */ (utils.getPreferredTagName({
+      tagName,
+    }));
+
+    const hasTag = Boolean(targetTagName && utils.hasTag(targetTagName));
+
+    state.hasTag[tagName] = hasTag || state.hasTag[tagName];
+
+    const hasDuplicate = state.hasDuplicates[tagName];
+
+    if (hasDuplicate === false) {
+      // Was marked before, so if a tag now, is a dupe
+      state.hasDuplicates[tagName] = hasTag;
+    } else if (!hasDuplicate && hasTag) {
+      // No dupes set before, but has first tag, so change state
+      //   from `undefined` to `false` so can detect next time
+      state.hasDuplicates[tagName] = false;
+      state.hasNonCommentBeforeTag[tagName] = state.hasNonComment &&
+        state.hasNonComment < jsdocNode.range[0];
+    }
+  }
+}, {
+  exit ({
+    context,
+    state,
+    utils,
+  }) {
+    setDefaults(state);
+    const {
+      tags = defaultTags,
+    } = context.options[0] || {};
+
+    for (const [
+      tagName,
+      {
+        initialCommentsOnly = false,
+        mustExist = false,
+        preventDuplicates = false,
+      },
+    ] of Object.entries(tags)) {
+      const obj = utils.getPreferredTagNameObject({
+        tagName,
+      });
+      if (obj && typeof obj === 'object' && 'blocked' in obj) {
+        utils.reportSettings(
+          `\`settings.jsdoc.tagNamePreference\` cannot block @${obj.tagName} ` +
+          'for the `require-file-overview` rule',
+        );
+      } else {
+        const targetTagName = (
+          obj && typeof obj === 'object' && obj.replacement
+        ) || obj;
+        if (mustExist && !state.hasTag[tagName]) {
+          utils.reportSettings(`Missing @${targetTagName}`);
+        }
+
+        if (preventDuplicates && state.hasDuplicates[tagName]) {
+          utils.reportSettings(
+            `Duplicate @${targetTagName}`,
+          );
+        }
+
+        if (initialCommentsOnly &&
+            state.hasNonCommentBeforeTag[tagName]
+        ) {
+          utils.reportSettings(
+            `@${targetTagName} should be at the beginning of the file`,
+          );
+        }
+      }
+    }
+  },
+  iterateAllJsdocs: true,
+  meta: {
+    docs: {
+      description: 'Checks that all files have one `@file`, `@fileoverview`, or `@overview` tag at the beginning of the file.',
+      url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-file-overview.md#repos-sticky-header',
+    },
+    schema: [
+      {
+        additionalProperties: false,
+        properties: {
+          tags: {
+            patternProperties: {
+              '.*': {
+                additionalProperties: false,
+                properties: {
+                  initialCommentsOnly: {
+                    type: 'boolean',
+                  },
+                  mustExist: {
+                    type: 'boolean',
+                  },
+                  preventDuplicates: {
+                    type: 'boolean',
+                  },
+                },
+                type: 'object',
+              },
+            },
+            type: 'object',
+          },
+        },
+        type: 'object',
+      },
+    ],
+    type: 'suggestion',
+  },
+  nonComment ({
+    node,
+    state,
+  }) {
+    if (!state.hasNonComment) {
+      state.hasNonComment = node.range[0];
+    }
+  },
+});

package/src/rules/requireHyphenBeforeParamDescription.js

@@ -0,0 +1,176 @@
+import iterateJsdoc from '../iterateJsdoc.js';
+
+export default iterateJsdoc(({
+  context,
+  jsdoc,
+  utils,
+}) => {
+  const [
+    mainCircumstance,
+    {
+      tags = null,
+    } = {},
+  ] = context.options;
+
+  const tgs = /**
+               * @type {null|"any"|{[key: string]: "always"|"never"}}
+               */ (tags);
+
+  /**
+   * @param {import('@es-joy/jsdoccomment').JsdocTagWithInline} jsdocTag
+   * @param {string} targetTagName
+   * @param {"always"|"never"} [circumstance]
+   * @returns {void}
+   */
+  const checkHyphens = (jsdocTag, targetTagName, circumstance = mainCircumstance) => {
+    const always = !circumstance || circumstance === 'always';
+    const desc = /** @type {string} */ (utils.getTagDescription(jsdocTag));
+    if (!desc.trim()) {
+      return;
+    }
+
+    const startsWithHyphen = (/^\s*-/v).test(desc);
+    let lines = 0;
+    for (const {
+      tokens,
+    } of jsdocTag.source) {
+      if (tokens.description) {
+        break;
+      }
+
+      lines++;
+    }
+
+    if (always) {
+      if (!startsWithHyphen) {
+        utils.reportJSDoc(
+          `There must be a hyphen before @${targetTagName} description.`,
+          {
+            line: jsdocTag.source[0].number + lines,
+          },
+          () => {
+            for (const {
+              tokens,
+            } of jsdocTag.source) {
+              if (tokens.description) {
+                tokens.description = tokens.description.replace(
+                  /^(\s*)/v, '$1- ',
+                );
+                break;
+              }
+            }
+          },
+        );
+      }
+    } else if (startsWithHyphen) {
+      utils.reportJSDoc(
+        `There must be no hyphen before @${targetTagName} description.`,
+        {
+          line: jsdocTag.source[0].number + lines,
+        },
+        () => {
+          for (const {
+            tokens,
+          } of jsdocTag.source) {
+            if (tokens.description) {
+              tokens.description = tokens.description.replace(
+                /^\s*-\s*/v, '',
+              );
+              break;
+            }
+          }
+        },
+        true,
+      );
+    }
+  };
+
+  utils.forEachPreferredTag('param', checkHyphens);
+  if (tgs) {
+    const tagEntries = Object.entries(tgs);
+    for (const [
+      tagName,
+      circumstance,
+    ] of tagEntries) {
+      if (tagName === '*') {
+        const preferredParamTag = utils.getPreferredTagName({
+          tagName: 'param',
+        });
+        for (const {
+          tag,
+        } of jsdoc.tags) {
+          if (tag === preferredParamTag || tagEntries.some(([
+            tagNme,
+          ]) => {
+            return tagNme !== '*' && tagNme === tag;
+          })) {
+            continue;
+          }
+
+          utils.forEachPreferredTag(tag, (jsdocTag, targetTagName) => {
+            checkHyphens(
+              jsdocTag,
+              targetTagName,
+              /** @type {"always"|"never"} */ (circumstance),
+            );
+          });
+        }
+
+        continue;
+      }
+
+      utils.forEachPreferredTag(tagName, (jsdocTag, targetTagName) => {
+        checkHyphens(
+          jsdocTag,
+          targetTagName,
+          /** @type {"always"|"never"} */ (circumstance),
+        );
+      });
+    }
+  }
+}, {
+  iterateAllJsdocs: true,
+  meta: {
+    docs: {
+      description: 'Requires a hyphen before the `@param` description.',
+      url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-hyphen-before-param-description.md#repos-sticky-header',
+    },
+    fixable: 'code',
+    schema: [
+      {
+        enum: [
+          'always', 'never',
+        ],
+        type: 'string',
+      },
+      {
+        additionalProperties: false,
+        properties: {
+          tags: {
+            anyOf: [
+              {
+                patternProperties: {
+                  '.*': {
+                    enum: [
+                      'always', 'never',
+                    ],
+                    type: 'string',
+                  },
+                },
+                type: 'object',
+              },
+              {
+                enum: [
+                  'any',
+                ],
+                type: 'string',
+              },
+            ],
+          },
+        },
+        type: 'object',
+      },
+    ],
+    type: 'layout',
+  },
+});