eslint-plugin-jsdoc 55.3.0 → 56.0.0

package/dist/cjs/rules/requireParamType.js

@@ -0,0 +1,77 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const iterateJsdoc_js_1 = __importDefault(require("../iterateJsdoc.js"));
+exports.default = (0, iterateJsdoc_js_1.default)(({ 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/dist/cjs/rules/requireProperty.d.ts

@@ -0,0 +1,2 @@
+declare const _default: import("eslint").Rule.RuleModule;
+export default _default;

package/dist/cjs/rules/requireProperty.js

@@ -0,0 +1,44 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const iterateJsdoc_js_1 = __importDefault(require("../iterateJsdoc.js"));
+exports.default = (0, iterateJsdoc_js_1.default)(({ 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/dist/cjs/rules/requirePropertyDescription.d.ts

@@ -0,0 +1,2 @@
+declare const _default: import("eslint").Rule.RuleModule;
+export default _default;

package/dist/cjs/rules/requirePropertyDescription.js

@@ -0,0 +1,22 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const iterateJsdoc_js_1 = __importDefault(require("../iterateJsdoc.js"));
+exports.default = (0, iterateJsdoc_js_1.default)(({ 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/dist/cjs/rules/requirePropertyName.d.ts

@@ -0,0 +1,2 @@
+declare const _default: import("eslint").Rule.RuleModule;
+export default _default;

package/dist/cjs/rules/requirePropertyName.js

@@ -0,0 +1,22 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const iterateJsdoc_js_1 = __importDefault(require("../iterateJsdoc.js"));
+exports.default = (0, iterateJsdoc_js_1.default)(({ 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/dist/cjs/rules/requirePropertyType.d.ts

@@ -0,0 +1,2 @@
+declare const _default: import("eslint").Rule.RuleModule;
+export default _default;

package/dist/cjs/rules/requirePropertyType.js

@@ -0,0 +1,22 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const iterateJsdoc_js_1 = __importDefault(require("../iterateJsdoc.js"));
+exports.default = (0, iterateJsdoc_js_1.default)(({ 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/dist/cjs/rules/requireReturns.d.ts

@@ -0,0 +1,2 @@
+declare const _default: import("eslint").Rule.RuleModule;
+export default _default;

package/dist/cjs/rules/requireReturns.js

@@ -0,0 +1,197 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const exportParser_js_1 = __importDefault(require("../exportParser.js"));
+const iterateJsdoc_js_1 = __importDefault(require("../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();
+};
+exports.default = (0, iterateJsdoc_js_1.default)(({ 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_js_1.default.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/dist/cjs/rules/requireReturnsCheck.d.ts

@@ -0,0 +1,2 @@
+declare const _default: import("eslint").Rule.RuleModule;
+export default _default;

package/dist/cjs/rules/requireReturnsCheck.js

@@ -0,0 +1,108 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const iterateJsdoc_js_1 = __importDefault(require("../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
+exports.default = (0, iterateJsdoc_js_1.default)(({ 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',
+    },
+});

package/dist/cjs/rules/requireReturnsDescription.d.ts

@@ -0,0 +1,2 @@
+declare const _default: import("eslint").Rule.RuleModule;
+export default _default;

package/dist/cjs/rules/requireReturnsDescription.js

@@ -0,0 +1,58 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const iterateJsdoc_js_1 = __importDefault(require("../iterateJsdoc.js"));
+exports.default = (0, iterateJsdoc_js_1.default)(({ report, utils, }) => {
+    utils.forEachPreferredTag('returns', (jsdocTag, targetTagName) => {
+        const type = jsdocTag.type && jsdocTag.type.trim();
+        if ([
+            'Promise<undefined>', 'Promise<void>', 'undefined', 'void',
+        ].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',
+    },
+});

package/dist/cjs/rules/requireReturnsType.d.ts

@@ -0,0 +1,2 @@
+declare const _default: import("eslint").Rule.RuleModule;
+export default _default;

package/dist/cjs/rules/requireReturnsType.js

@@ -0,0 +1,52 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const iterateJsdoc_js_1 = __importDefault(require("../iterateJsdoc.js"));
+exports.default = (0, iterateJsdoc_js_1.default)(({ report, utils, }) => {
+    utils.forEachPreferredTag('returns', (jsdocTag, targetTagName) => {
+        if (!jsdocTag.type) {
+            report(`Missing JSDoc @${targetTagName} type.`, null, jsdocTag);
+        }
+    });
+}, {
+    contextDefaults: true,
+    meta: {
+        docs: {
+            description: 'Requires that `@returns` tag has `type` value.',
+            url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-returns-type.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/dist/cjs/rules/requireTemplate.d.ts

@@ -0,0 +1,2 @@
+declare const _default: import("eslint").Rule.RuleModule;
+export default _default;