eslint-plugin-jsdoc 52.0.4 → 53.0.1

package/src/rules/requireParamName.js

@@ -1,55 +0,0 @@
-import iterateJsdoc from '../iterateJsdoc.js';
-
-export default iterateJsdoc(({
-  report,
-  utils,
-}) => {
-  utils.forEachPreferredTag('param', (jsdocParameter, targetTagName) => {
-    if (jsdocParameter.tag && jsdocParameter.name === '') {
-      report(
-        `There must be an identifier after @${targetTagName} ${jsdocParameter.type === '' ? 'type' : 'tag'}.`,
-        null,
-        jsdocParameter,
-      );
-    }
-  });
-}, {
-  contextDefaults: true,
-  meta: {
-    docs: {
-      description: 'Requires that all function parameters have names.',
-      url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-param-name.md#repos-sticky-header',
-    },
-    schema: [
-      {
-        additionalProperties: false,
-        properties: {
-          contexts: {
-            items: {
-              anyOf: [
-                {
-                  type: 'string',
-                },
-                {
-                  additionalProperties: false,
-                  properties: {
-                    comment: {
-                      type: 'string',
-                    },
-                    context: {
-                      type: 'string',
-                    },
-                  },
-                  type: 'object',
-                },
-              ],
-            },
-            type: 'array',
-          },
-        },
-        type: 'object',
-      },
-    ],
-    type: 'suggestion',
-  },
-});

package/src/rules/requireParamType.js

@@ -1,89 +0,0 @@
-import iterateJsdoc from '../iterateJsdoc.js';
-
-export default iterateJsdoc(({
-  context,
-  report,
-  settings,
-  utils,
-}) => {
-  const {
-    defaultDestructuredRootType = 'object',
-    setDefaultDestructuredRootType = false,
-  } = context.options[0] || {};
-
-  const functionParameterNames = utils.getFunctionParameterNames();
-
-  let rootCount = -1;
-  utils.forEachPreferredTag('param', (jsdocParameter, targetTagName) => {
-    rootCount += jsdocParameter.name.includes('.') ? 0 : 1;
-    if (!jsdocParameter.type) {
-      if (Array.isArray(functionParameterNames[rootCount])) {
-        if (settings.exemptDestructuredRootsFromChecks) {
-          return;
-        }
-
-        if (setDefaultDestructuredRootType) {
-          utils.reportJSDoc(`Missing root type for @${targetTagName}.`, jsdocParameter, () => {
-            utils.changeTag(jsdocParameter, {
-              postType: ' ',
-              type: `{${defaultDestructuredRootType}}`,
-            });
-          });
-          return;
-        }
-      }
-
-      report(
-        `Missing JSDoc @${targetTagName} "${jsdocParameter.name}" type.`,
-        null,
-        jsdocParameter,
-      );
-    }
-  });
-}, {
-  contextDefaults: true,
-  meta: {
-    docs: {
-      description: 'Requires that each `@param` tag has a `type` value.',
-      url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-param-type.md#repos-sticky-header',
-    },
-    fixable: 'code',
-    schema: [
-      {
-        additionalProperties: false,
-        properties: {
-          contexts: {
-            items: {
-              anyOf: [
-                {
-                  type: 'string',
-                },
-                {
-                  additionalProperties: false,
-                  properties: {
-                    comment: {
-                      type: 'string',
-                    },
-                    context: {
-                      type: 'string',
-                    },
-                  },
-                  type: 'object',
-                },
-              ],
-            },
-            type: 'array',
-          },
-          defaultDestructuredRootType: {
-            type: 'string',
-          },
-          setDefaultDestructuredRootType: {
-            type: 'boolean',
-          },
-        },
-        type: 'object',
-      },
-    ],
-    type: 'suggestion',
-  },
-});

package/src/rules/requireProperty.js

@@ -1,48 +0,0 @@
-import iterateJsdoc from '../iterateJsdoc.js';
-
-export default iterateJsdoc(({
-  utils,
-}) => {
-  const propertyAssociatedTags = utils.filterTags(({
-    tag,
-  }) => {
-    return [
-      'namespace', 'typedef',
-    ].includes(tag);
-  });
-  if (!propertyAssociatedTags.length) {
-    return;
-  }
-
-  const targetTagName = /** @type {string} */ (utils.getPreferredTagName({
-    tagName: 'property',
-  }));
-
-  if (utils.hasATag([
-    targetTagName,
-  ])) {
-    return;
-  }
-
-  for (const propertyAssociatedTag of propertyAssociatedTags) {
-    if (![
-      'object', 'Object', 'PlainObject',
-    ].includes(propertyAssociatedTag.type)) {
-      continue;
-    }
-
-    utils.reportJSDoc(`Missing JSDoc @${targetTagName}.`, null, () => {
-      utils.addTag(targetTagName);
-    });
-  }
-}, {
-  iterateAllJsdocs: true,
-  meta: {
-    docs: {
-      description: 'Requires that all `@typedef` and `@namespace` tags have `@property` when their type is a plain `object`, `Object`, or `PlainObject`.',
-      url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-property.md#repos-sticky-header',
-    },
-    fixable: 'code',
-    type: 'suggestion',
-  },
-});

package/src/rules/requirePropertyDescription.js

@@ -1,25 +0,0 @@
-import iterateJsdoc from '../iterateJsdoc.js';
-
-export default iterateJsdoc(({
-  report,
-  utils,
-}) => {
-  utils.forEachPreferredTag('property', (jsdoc, targetTagName) => {
-    if (!jsdoc.description.trim()) {
-      report(
-        `Missing JSDoc @${targetTagName} "${jsdoc.name}" description.`,
-        null,
-        jsdoc,
-      );
-    }
-  });
-}, {
-  iterateAllJsdocs: true,
-  meta: {
-    docs: {
-      description: 'Requires that each `@property` tag has a `description` value.',
-      url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-property-description.md#repos-sticky-header',
-    },
-    type: 'suggestion',
-  },
-});

package/src/rules/requirePropertyName.js

@@ -1,25 +0,0 @@
-import iterateJsdoc from '../iterateJsdoc.js';
-
-export default iterateJsdoc(({
-  report,
-  utils,
-}) => {
-  utils.forEachPreferredTag('property', (jsdoc, targetTagName) => {
-    if (jsdoc.tag && jsdoc.name === '') {
-      report(
-        `There must be an identifier after @${targetTagName} ${jsdoc.type === '' ? 'type' : 'tag'}.`,
-        null,
-        jsdoc,
-      );
-    }
-  });
-}, {
-  iterateAllJsdocs: true,
-  meta: {
-    docs: {
-      description: 'Requires that all function `@property` tags have names.',
-      url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-property-name.md#repos-sticky-header',
-    },
-    type: 'suggestion',
-  },
-});

package/src/rules/requirePropertyType.js

@@ -1,25 +0,0 @@
-import iterateJsdoc from '../iterateJsdoc.js';
-
-export default iterateJsdoc(({
-  report,
-  utils,
-}) => {
-  utils.forEachPreferredTag('property', (jsdoc, targetTagName) => {
-    if (!jsdoc.type) {
-      report(
-        `Missing JSDoc @${targetTagName} "${jsdoc.name}" type.`,
-        null,
-        jsdoc,
-      );
-    }
-  });
-}, {
-  iterateAllJsdocs: true,
-  meta: {
-    docs: {
-      description: 'Requires that each `@property` tag has a `type` value.',
-      url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-property-type.md#repos-sticky-header',
-    },
-    type: 'suggestion',
-  },
-});

package/src/rules/requireReturns.js

@@ -1,238 +0,0 @@
-import exportParser from '../exportParser.js';
-import iterateJsdoc from '../iterateJsdoc.js';
-
-/**
- * We can skip checking for a return value, in case the documentation is inherited
- * or the method is either a constructor or an abstract method.
- *
- * In either of these cases the return value is optional or not defined.
- * @param {import('../iterateJsdoc.js').Utils} utils
- *   a reference to the utils which are used to probe if a tag is present or not.
- * @returns {boolean}
- *   true in case deep checking can be skipped; otherwise false.
- */
-const canSkip = (utils) => {
-  return utils.hasATag([
-    // inheritdoc implies that all documentation is inherited
-    // see https://jsdoc.app/tags-inheritdoc.html
-    //
-    // Abstract methods are by definition incomplete,
-    // so it is not an error if it declares a return value but does not implement it.
-    'abstract',
-    'virtual',
-
-    // Constructors do not have a return value by definition (https://jsdoc.app/tags-class.html)
-    // So we can bail out here, too.
-    'class',
-    'constructor',
-
-    // Return type is specified by type in @type
-    'type',
-
-    // This seems to imply a class as well
-    'interface',
-  ]) ||
-    utils.avoidDocs();
-};
-
-export default iterateJsdoc(({
-  context,
-  info: {
-    comment,
-  },
-  node,
-  report,
-  settings,
-  utils,
-}) => {
-  const {
-    contexts,
-    enableFixer = false,
-    forceRequireReturn = false,
-    forceReturnsWithAsync = false,
-    publicOnly = false,
-  } = context.options[0] || {};
-
-  // A preflight check. We do not need to run a deep check
-  // in case the @returns comment is optional or undefined.
-  if (canSkip(utils)) {
-    return;
-  }
-
-  /** @type {boolean|undefined} */
-  let forceRequireReturnContext;
-  if (contexts) {
-    const {
-      foundContext,
-    } = utils.findContext(contexts, comment);
-    if (typeof foundContext === 'object') {
-      forceRequireReturnContext = foundContext.forceRequireReturn;
-    }
-  }
-
-  const tagName = /** @type {string} */ (utils.getPreferredTagName({
-    tagName: 'returns',
-  }));
-  if (!tagName) {
-    return;
-  }
-
-  const tags = utils.getTags(tagName);
-
-  if (tags.length > 1) {
-    report(`Found more than one @${tagName} declaration.`);
-  }
-
-  const iteratingFunction = utils.isIteratingFunction();
-
-  // In case the code returns something, we expect a return value in JSDoc.
-  const [
-    tag,
-  ] = tags;
-  const missingReturnTag = typeof tag === 'undefined' || tag === null;
-
-  const shouldReport = () => {
-    if (!missingReturnTag) {
-      return false;
-    }
-
-    if (publicOnly) {
-      /** @type {import('./requireJsdoc.js').RequireJsdocOpts} */
-      const opt = {
-        ancestorsOnly: Boolean(publicOnly?.ancestorsOnly ?? false),
-        esm: Boolean(publicOnly?.esm ?? true),
-        initModuleExports: Boolean(publicOnly?.cjs ?? true),
-        initWindow: Boolean(publicOnly?.window ?? false),
-      };
-      /* c8 ignore next -- Fallback to deprecated method */
-      const {
-        sourceCode = context.getSourceCode(),
-      } = context;
-      const exported = exportParser.isUncommentedExport(
-        /** @type {import('eslint').Rule.Node} */ (node), sourceCode, opt, settings,
-      );
-
-      if (!exported) {
-        return false;
-      }
-    }
-
-    if ((forceRequireReturn || forceRequireReturnContext) && (
-      iteratingFunction || utils.isVirtualFunction()
-    )) {
-      return true;
-    }
-
-    const isAsync = !iteratingFunction && utils.hasTag('async') ||
-      iteratingFunction && utils.isAsync();
-
-    if (forceReturnsWithAsync && isAsync) {
-      return true;
-    }
-
-    return iteratingFunction && utils.hasValueOrExecutorHasNonEmptyResolveValue(
-      forceReturnsWithAsync,
-    );
-  };
-
-  if (shouldReport()) {
-    utils.reportJSDoc(`Missing JSDoc @${tagName} declaration.`, null, enableFixer ? () => {
-      utils.addTag(tagName);
-    } : null);
-  }
-}, {
-  contextDefaults: true,
-  meta: {
-    docs: {
-      description: 'Requires that returns are documented.',
-      url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-returns.md#repos-sticky-header',
-    },
-    fixable: 'code',
-    schema: [
-      {
-        additionalProperties: false,
-        properties: {
-          checkConstructors: {
-            default: false,
-            type: 'boolean',
-          },
-          checkGetters: {
-            default: true,
-            type: 'boolean',
-          },
-          contexts: {
-            items: {
-              anyOf: [
-                {
-                  type: 'string',
-                },
-                {
-                  additionalProperties: false,
-                  properties: {
-                    comment: {
-                      type: 'string',
-                    },
-                    context: {
-                      type: 'string',
-                    },
-                    forceRequireReturn: {
-                      type: 'boolean',
-                    },
-                  },
-                  type: 'object',
-                },
-              ],
-            },
-            type: 'array',
-          },
-          enableFixer: {
-            type: 'boolean',
-          },
-          exemptedBy: {
-            items: {
-              type: 'string',
-            },
-            type: 'array',
-          },
-          forceRequireReturn: {
-            default: false,
-            type: 'boolean',
-          },
-          forceReturnsWithAsync: {
-            default: false,
-            type: 'boolean',
-          },
-          publicOnly: {
-            oneOf: [
-              {
-                default: false,
-                type: 'boolean',
-              },
-              {
-                additionalProperties: false,
-                default: {},
-                properties: {
-                  ancestorsOnly: {
-                    type: 'boolean',
-                  },
-                  cjs: {
-                    type: 'boolean',
-                  },
-                  esm: {
-                    type: 'boolean',
-                  },
-                  window: {
-                    type: 'boolean',
-                  },
-                },
-                type: 'object',
-              },
-            ],
-          },
-        },
-        type: 'object',
-      },
-    ],
-    type: 'suggestion',
-  },
-});

package/src/rules/requireReturnsCheck.js

@@ -1,145 +0,0 @@
-import iterateJsdoc from '../iterateJsdoc.js';
-
-/**
- * @param {import('../iterateJsdoc.js').Utils} utils
- * @param {import('../iterateJsdoc.js').Settings} settings
- * @returns {boolean}
- */
-const canSkip = (utils, settings) => {
-  const voidingTags = [
-    // An abstract function is by definition incomplete
-    // so it is perfectly fine if a return is documented but
-    // not present within the function.
-    // A subclass may inherit the doc and implement the
-    // missing return.
-    'abstract',
-    'virtual',
-
-    // A constructor function returns `this` by default, so may be `@returns`
-    //   tag indicating this but no explicit return
-    'class',
-    'constructor',
-    'interface',
-  ];
-
-  if (settings.mode === 'closure') {
-    // Structural Interface in GCC terms, equivalent to @interface tag as far as this rule is concerned
-    voidingTags.push('record');
-  }
-
-  return utils.hasATag(voidingTags) ||
-    utils.isConstructor() ||
-    utils.classHasTag('interface') ||
-    settings.mode === 'closure' && utils.classHasTag('record');
-};
-
-// eslint-disable-next-line complexity -- Temporary
-export default iterateJsdoc(({
-  context,
-  node,
-  report,
-  settings,
-  utils,
-}) => {
-  const {
-    exemptAsync = true,
-    exemptGenerators = settings.mode === 'typescript',
-    reportMissingReturnForUndefinedTypes = false,
-  } = context.options[0] || {};
-
-  if (canSkip(utils, settings)) {
-    return;
-  }
-
-  if (exemptAsync && utils.isAsync()) {
-    return;
-  }
-
-  const tagName = /** @type {string} */ (utils.getPreferredTagName({
-    tagName: 'returns',
-  }));
-  if (!tagName) {
-    return;
-  }
-
-  const tags = utils.getTags(tagName);
-
-  if (tags.length === 0) {
-    return;
-  }
-
-  if (tags.length > 1) {
-    report(`Found more than one @${tagName} declaration.`);
-
-    return;
-  }
-
-  const [
-    tag,
-  ] = tags;
-
-  const type = tag.type.trim();
-
-  // https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-7.html#assertion-functions
-  if (/asserts\s/v.test(type)) {
-    return;
-  }
-
-  const returnNever = type === 'never';
-
-  if (returnNever && utils.hasValueOrExecutorHasNonEmptyResolveValue(false)) {
-    report(`JSDoc @${tagName} declaration set with "never" but return expression is present in function.`);
-
-    return;
-  }
-
-  // In case a return value is declared in JSDoc, we also expect one in the code.
-  if (
-    !returnNever &&
-    (
-      reportMissingReturnForUndefinedTypes ||
-      !utils.mayBeUndefinedTypeTag(tag)
-    ) &&
-    (tag.type === '' && !utils.hasValueOrExecutorHasNonEmptyResolveValue(
-      exemptAsync,
-    ) ||
-    tag.type !== '' && !utils.hasValueOrExecutorHasNonEmptyResolveValue(
-      exemptAsync,
-      true,
-    )) &&
-    Boolean(
-      !exemptGenerators || !node ||
-      !('generator' in /** @type {import('../iterateJsdoc.js').Node} */ (node)) ||
-      !(/** @type {import('@typescript-eslint/types').TSESTree.FunctionDeclaration} */ (node)).generator,
-    )
-  ) {
-    report(`JSDoc @${tagName} declaration present but return expression not available in function.`);
-  }
-}, {
-  meta: {
-    docs: {
-      description: 'Requires a return statement in function body if a `@returns` tag is specified in jsdoc comment.',
-      url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-returns-check.md#repos-sticky-header',
-    },
-    schema: [
-      {
-        additionalProperties: false,
-        properties: {
-          exemptAsync: {
-            default: true,
-            type: 'boolean',
-          },
-          exemptGenerators: {
-            type: 'boolean',
-          },
-          reportMissingReturnForUndefinedTypes: {
-            default: false,
-            type: 'boolean',
-          },
-        },
-        type: 'object',
-      },
-    ],
-    type: 'suggestion',
-  },
-});