eslint-plugin-jsdoc 52.0.4 → 53.0.1

package/src/rules/requireExample.js

@@ -1,118 +0,0 @@
-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.isIteratingFunction() &&
-      !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

@@ -1,154 +0,0 @@
-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

@@ -1,176 +0,0 @@
-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',
-  },
-});