eslint-plugin-jsdoc 48.0.0 → 48.0.1

package/src/rules/requireParamName.js

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

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

@@ -0,0 +1,48 @@
+import iterateJsdoc from '../iterateJsdoc.js';
+
+export default iterateJsdoc(({
+  utils,
+}) => {
+  const propertyAssociatedTags = utils.filterTags(({
+    tag,
+  }) => {
+    return [
+      'typedef', 'namespace',
+    ].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

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

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

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

@@ -0,0 +1,238 @@
+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(({
+  info: {
+    comment,
+  },
+  node,
+  report,
+  settings,
+  utils,
+  context,
+}) => {
+  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

@@ -0,0 +1,141 @@
+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/u.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,
+    )) &&
+    (!exemptGenerators || !('generator' in /** @type {import('../iterateJsdoc.js').Node} */ (node)) || !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',
+  },
+});

package/src/rules/requireReturnsDescription.js

@@ -0,0 +1,59 @@
+import iterateJsdoc from '../iterateJsdoc.js';
+
+export default iterateJsdoc(({
+  report,
+  utils,
+}) => {
+  utils.forEachPreferredTag('returns', (jsdocTag, targetTagName) => {
+    const type = jsdocTag.type && jsdocTag.type.trim();
+
+    if ([
+      'void', 'undefined', 'Promise<void>', 'Promise<undefined>',
+    ].includes(type)) {
+      return;
+    }
+
+    if (!jsdocTag.description.trim()) {
+      report(`Missing JSDoc @${targetTagName} description.`, null, jsdocTag);
+    }
+  });
+}, {
+  contextDefaults: true,
+  meta: {
+    docs: {
+      description: 'Requires that the `@returns` tag has a `description` value.',
+      url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-returns-description.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',
+  },
+});