eslint-plugin-jsdoc 56.0.0 → 56.0.2

package/dist/cjs/rules/requireProperty.js

@@ -1,44 +0,0 @@
-"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.js

@@ -1,22 +0,0 @@
-"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.js

@@ -1,22 +0,0 @@
-"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.js

@@ -1,22 +0,0 @@
-"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.js

@@ -1,197 +0,0 @@
-"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.js

@@ -1,108 +0,0 @@
-"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.js

@@ -1,58 +0,0 @@
-"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.js

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