eslint-plugin-jsdoc 56.0.0 → 56.0.1

package/dist/cjs/rules/requireTemplate.js

@@ -1,173 +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"));
-const jsdoccomment_1 = require("@es-joy/jsdoccomment");
-exports.default = (0, iterateJsdoc_js_1.default)(({ context, node, report, settings, utils, }) => {
-    if (utils.avoidDocs()) {
-        return;
-    }
-    const { requireSeparateTemplates = false, } = context.options[0] || {};
-    const { mode, } = settings;
-    const usedNames = new Set();
-    const templateTags = utils.getTags('template');
-    const templateNames = templateTags.flatMap((tag) => {
-        return utils.parseClosureTemplateTag(tag);
-    });
-    if (requireSeparateTemplates) {
-        for (const tag of templateTags) {
-            const names = utils.parseClosureTemplateTag(tag);
-            if (names.length > 1) {
-                report(`Missing separate @template for ${names[1]}`, null, tag);
-            }
-        }
-    }
-    /**
-     * @param {import('@typescript-eslint/types').TSESTree.FunctionDeclaration|
-     *   import('@typescript-eslint/types').TSESTree.ClassDeclaration|
-     *   import('@typescript-eslint/types').TSESTree.TSDeclareFunction|
-     *   import('@typescript-eslint/types').TSESTree.TSInterfaceDeclaration|
-     *   import('@typescript-eslint/types').TSESTree.TSTypeAliasDeclaration} aliasDeclaration
-     */
-    const checkTypeParams = (aliasDeclaration) => {
-        const { params,
-        /* c8 ignore next -- Guard */
-         } = aliasDeclaration.typeParameters ?? {
-            /* c8 ignore next -- Guard */
-            params: [],
-        };
-        for (const { name: { name, }, } of params) {
-            usedNames.add(name);
-        }
-        for (const usedName of usedNames) {
-            if (!templateNames.includes(usedName)) {
-                report(`Missing @template ${usedName}`);
-            }
-        }
-    };
-    const handleTypes = () => {
-        const nde = /** @type {import('@typescript-eslint/types').TSESTree.Node} */ (node);
-        if (!nde) {
-            return;
-        }
-        switch (nde.type) {
-            case 'ClassDeclaration':
-            case 'FunctionDeclaration':
-            case 'TSDeclareFunction':
-            case 'TSInterfaceDeclaration':
-            case 'TSTypeAliasDeclaration':
-                checkTypeParams(nde);
-                break;
-            case 'ExportDefaultDeclaration':
-                switch (nde.declaration?.type) {
-                    case 'ClassDeclaration':
-                    case 'FunctionDeclaration':
-                    case 'TSInterfaceDeclaration':
-                        checkTypeParams(nde.declaration);
-                        break;
-                }
-                break;
-            case 'ExportNamedDeclaration':
-                switch (nde.declaration?.type) {
-                    case 'ClassDeclaration':
-                    case 'FunctionDeclaration':
-                    case 'TSDeclareFunction':
-                    case 'TSInterfaceDeclaration':
-                    case 'TSTypeAliasDeclaration':
-                        checkTypeParams(nde.declaration);
-                        break;
-                }
-                break;
-        }
-    };
-    const usedNameToTag = new Map();
-    /**
-     * @param {import('comment-parser').Spec} potentialTag
-     */
-    const checkForUsedTypes = (potentialTag) => {
-        let parsedType;
-        try {
-            parsedType = mode === 'permissive' ?
-                (0, jsdoccomment_1.tryParse)(/** @type {string} */ (potentialTag.type)) :
-                (0, jsdoccomment_1.parse)(/** @type {string} */ (potentialTag.type), mode);
-        }
-        catch {
-            return;
-        }
-        (0, jsdoccomment_1.traverse)(parsedType, (nde) => {
-            const { type, value, } = /** @type {import('jsdoc-type-pratt-parser').NameResult} */ (nde);
-            if (type === 'JsdocTypeName' && (/^[A-Z]$/v).test(value)) {
-                usedNames.add(value);
-                if (!usedNameToTag.has(value)) {
-                    usedNameToTag.set(value, potentialTag);
-                }
-            }
-        });
-    };
-    /**
-     * @param {string[]} tagNames
-     */
-    const checkTagsAndTemplates = (tagNames) => {
-        for (const tagName of tagNames) {
-            const preferredTagName = /** @type {string} */ (utils.getPreferredTagName({
-                tagName,
-            }));
-            const matchingTags = utils.getTags(preferredTagName);
-            for (const matchingTag of matchingTags) {
-                checkForUsedTypes(matchingTag);
-            }
-        }
-        // Could check against whitelist/blacklist
-        for (const usedName of usedNames) {
-            if (!templateNames.includes(usedName)) {
-                report(`Missing @template ${usedName}`, null, usedNameToTag.get(usedName));
-            }
-        }
-    };
-    const callbackTags = utils.getTags('callback');
-    const functionTags = utils.getTags('function');
-    if (callbackTags.length || functionTags.length) {
-        checkTagsAndTemplates([
-            'param', 'returns',
-        ]);
-        return;
-    }
-    const typedefTags = utils.getTags('typedef');
-    if (!typedefTags.length || typedefTags.length >= 2) {
-        handleTypes();
-        return;
-    }
-    const potentialTypedef = typedefTags[0];
-    checkForUsedTypes(potentialTypedef);
-    checkTagsAndTemplates([
-        'property',
-    ]);
-}, {
-    iterateAllJsdocs: true,
-    meta: {
-        docs: {
-            description: 'Requires template tags for each generic type parameter',
-            url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-template.md#repos-sticky-header',
-        },
-        schema: [
-            {
-                additionalProperties: false,
-                properties: {
-                    exemptedBy: {
-                        items: {
-                            type: 'string',
-                        },
-                        type: 'array',
-                    },
-                    requireSeparateTemplates: {
-                        type: 'boolean',
-                    },
-                },
-                type: 'object',
-            },
-        ],
-        type: 'suggestion',
-    },
-});

package/dist/cjs/rules/requireThrows.js

@@ -1,101 +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"));
-/**
- * We can skip checking for a throws value, in case the documentation is inherited
- * or the method is either a constructor or an abstract method.
- * @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 necessary to document that they throw an error.
-        'abstract',
-        'virtual',
-        // The designated type can itself document `@throws`
-        'type',
-    ]) ||
-        utils.avoidDocs();
-};
-exports.default = (0, iterateJsdoc_js_1.default)(({ report, utils, }) => {
-    // A preflight check. We do not need to run a deep check for abstract
-    //  functions.
-    if (canSkip(utils)) {
-        return;
-    }
-    const tagName = /** @type {string} */ (utils.getPreferredTagName({
-        tagName: 'throws',
-    }));
-    if (!tagName) {
-        return;
-    }
-    const tags = utils.getTags(tagName);
-    const iteratingFunction = utils.isIteratingFunction();
-    // In case the code returns something, we expect a return value in JSDoc.
-    const [tag,] = tags;
-    const missingThrowsTag = typeof tag === 'undefined' || tag === null;
-    const shouldReport = () => {
-        if (!missingThrowsTag) {
-            if (tag.type.trim() === 'never' && iteratingFunction && utils.hasThrowValue()) {
-                report(`JSDoc @${tagName} declaration set to "never" but throw value found.`);
-            }
-            return false;
-        }
-        return iteratingFunction && utils.hasThrowValue();
-    };
-    if (shouldReport()) {
-        report(`Missing JSDoc @${tagName} declaration.`);
-    }
-}, {
-    contextDefaults: true,
-    meta: {
-        docs: {
-            description: 'Requires that throw statements are documented.',
-            url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-throws.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',
-                    },
-                    exemptedBy: {
-                        items: {
-                            type: 'string',
-                        },
-                        type: 'array',
-                    },
-                },
-                type: 'object',
-            },
-        ],
-        type: 'suggestion',
-    },
-});

package/dist/cjs/rules/requireYields.js

@@ -1,172 +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"));
-/**
- * We can skip checking for a yield value, in case the documentation is inherited
- * or the method has a constructor or abstract tag.
- *
- * In either of these cases the yield 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 yield value but does not implement it.
-        'abstract',
-        'virtual',
-        // Constructors do not have a yield value
-        // so we can bail out here, too.
-        'class',
-        'constructor',
-        // Yield (and any `next`) type is specified accompanying the targeted
-        //   @type
-        'type',
-        // This seems to imply a class as well
-        'interface',
-    ]) ||
-        utils.avoidDocs();
-};
-/**
- * @param {import('../iterateJsdoc.js').Utils} utils
- * @param {import('../iterateJsdoc.js').Report} report
- * @param {string} tagName
- * @returns {[preferredTagName?: string, missingTag?: boolean]}
- */
-const checkTagName = (utils, report, tagName) => {
-    const preferredTagName = /** @type {string} */ (utils.getPreferredTagName({
-        tagName,
-    }));
-    if (!preferredTagName) {
-        return [];
-    }
-    const tags = utils.getTags(preferredTagName);
-    if (tags.length > 1) {
-        report(`Found more than one @${preferredTagName} declaration.`);
-    }
-    // In case the code yields something, we expect a yields value in JSDoc.
-    const [tag,] = tags;
-    const missingTag = typeof tag === 'undefined' || tag === null;
-    return [
-        preferredTagName, missingTag,
-    ];
-};
-exports.default = (0, iterateJsdoc_js_1.default)(({ context, report, utils, }) => {
-    const { forceRequireNext = false, forceRequireYields = false, next = false, nextWithGeneratorTag = false, withGeneratorTag = true, } = context.options[0] || {};
-    // A preflight check. We do not need to run a deep check
-    // in case the @yield comment is optional or undefined.
-    if (canSkip(utils)) {
-        return;
-    }
-    const iteratingFunction = utils.isIteratingFunction();
-    const [preferredYieldTagName, missingYieldTag,] = checkTagName(utils, report, 'yields');
-    if (preferredYieldTagName) {
-        const shouldReportYields = () => {
-            if (!missingYieldTag) {
-                return false;
-            }
-            if (withGeneratorTag && utils.hasTag('generator') ||
-                forceRequireYields && iteratingFunction && utils.isGenerator()) {
-                return true;
-            }
-            return iteratingFunction && utils.isGenerator() && utils.hasYieldValue();
-        };
-        if (shouldReportYields()) {
-            report(`Missing JSDoc @${preferredYieldTagName} declaration.`);
-        }
-    }
-    if (next || nextWithGeneratorTag || forceRequireNext) {
-        const [preferredNextTagName, missingNextTag,] = checkTagName(utils, report, 'next');
-        if (!preferredNextTagName) {
-            return;
-        }
-        const shouldReportNext = () => {
-            if (!missingNextTag) {
-                return false;
-            }
-            if (nextWithGeneratorTag && utils.hasTag('generator')) {
-                return true;
-            }
-            if (!next && !forceRequireNext ||
-                !iteratingFunction ||
-                !utils.isGenerator()) {
-                return false;
-            }
-            return forceRequireNext || utils.hasYieldReturnValue();
-        };
-        if (shouldReportNext()) {
-            report(`Missing JSDoc @${preferredNextTagName} declaration.`);
-        }
-    }
-}, {
-    contextDefaults: true,
-    meta: {
-        docs: {
-            description: 'Requires yields are documented.',
-            url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-yields.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',
-                    },
-                    exemptedBy: {
-                        items: {
-                            type: 'string',
-                        },
-                        type: 'array',
-                    },
-                    forceRequireNext: {
-                        default: false,
-                        type: 'boolean',
-                    },
-                    forceRequireYields: {
-                        default: false,
-                        type: 'boolean',
-                    },
-                    next: {
-                        default: false,
-                        type: 'boolean',
-                    },
-                    nextWithGeneratorTag: {
-                        default: false,
-                        type: 'boolean',
-                    },
-                    withGeneratorTag: {
-                        default: true,
-                        type: 'boolean',
-                    },
-                },
-                type: 'object',
-            },
-        ],
-        type: 'suggestion',
-    },
-});

package/dist/cjs/rules/requireYieldsCheck.js

@@ -1,164 +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 yield is documented but
-        // not present within the function.
-        // A subclass may inherit the doc and implement the
-        // missing yield.
-        'abstract',
-        'virtual',
-        // Constructor functions do not have a yield value
-        //  so we can bail here, too.
-        'class',
-        'constructor',
-        // This seems to imply a class as well
-        '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');
-};
-/**
- * @param {import('../iterateJsdoc.js').Utils} utils
- * @param {import('../iterateJsdoc.js').Report} report
- * @param {string} tagName
- * @returns {[]|[preferredTagName: string, tag: import('comment-parser').Spec]}
- */
-const checkTagName = (utils, report, tagName) => {
-    const preferredTagName = /** @type {string} */ (utils.getPreferredTagName({
-        tagName,
-    }));
-    if (!preferredTagName) {
-        return [];
-    }
-    const tags = utils.getTags(preferredTagName);
-    if (tags.length === 0) {
-        return [];
-    }
-    if (tags.length > 1) {
-        report(`Found more than one @${preferredTagName} declaration.`);
-        return [];
-    }
-    return [
-        preferredTagName, tags[0],
-    ];
-};
-exports.default = (0, iterateJsdoc_js_1.default)(({ context, report, settings, utils, }) => {
-    if (canSkip(utils, settings)) {
-        return;
-    }
-    const { checkGeneratorsOnly = false, next = false, } = context.options[0] || {};
-    const [preferredYieldTagName, yieldTag,] = checkTagName(utils, report, 'yields');
-    if (preferredYieldTagName) {
-        const shouldReportYields = () => {
-            if (
-            /** @type {import('comment-parser').Spec} */ (yieldTag).type.trim() === 'never') {
-                if (utils.hasYieldValue()) {
-                    report(`JSDoc @${preferredYieldTagName} declaration set with "never" but yield expression is present in function.`);
-                }
-                return false;
-            }
-            if (checkGeneratorsOnly && !utils.isGenerator()) {
-                return true;
-            }
-            return !utils.mayBeUndefinedTypeTag(
-            /** @type {import('comment-parser').Spec} */
-            (yieldTag)) && !utils.hasYieldValue();
-        };
-        // In case a yield value is declared in JSDoc, we also expect one in the code.
-        if (shouldReportYields()) {
-            report(`JSDoc @${preferredYieldTagName} declaration present but yield expression not available in function.`);
-        }
-    }
-    if (next) {
-        const [preferredNextTagName, nextTag,] = checkTagName(utils, report, 'next');
-        if (preferredNextTagName) {
-            const shouldReportNext = () => {
-                if (
-                /** @type {import('comment-parser').Spec} */ (nextTag).type.trim() === 'never') {
-                    if (utils.hasYieldReturnValue()) {
-                        report(`JSDoc @${preferredNextTagName} declaration set with "never" but yield expression with return value is present in function.`);
-                    }
-                    return false;
-                }
-                if (checkGeneratorsOnly && !utils.isGenerator()) {
-                    return true;
-                }
-                return !utils.mayBeUndefinedTypeTag(
-                /** @type {import('comment-parser').Spec} */
-                (nextTag)) && !utils.hasYieldReturnValue();
-            };
-            if (shouldReportNext()) {
-                report(`JSDoc @${preferredNextTagName} declaration present but yield expression with return value not available in function.`);
-            }
-        }
-    }
-}, {
-    meta: {
-        docs: {
-            description: 'Requires a yield statement in function body if a `@yields` tag is specified in jsdoc comment.',
-            url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-yields-check.md#repos-sticky-header',
-        },
-        schema: [
-            {
-                additionalProperties: false,
-                properties: {
-                    checkGeneratorsOnly: {
-                        default: false,
-                        type: 'boolean',
-                    },
-                    contexts: {
-                        items: {
-                            anyOf: [
-                                {
-                                    type: 'string',
-                                },
-                                {
-                                    additionalProperties: false,
-                                    properties: {
-                                        comment: {
-                                            type: 'string',
-                                        },
-                                        context: {
-                                            type: 'string',
-                                        },
-                                    },
-                                    type: 'object',
-                                },
-                            ],
-                        },
-                        type: 'array',
-                    },
-                    exemptedBy: {
-                        items: {
-                            type: 'string',
-                        },
-                        type: 'array',
-                    },
-                    next: {
-                        default: false,
-                        type: 'boolean',
-                    },
-                },
-                type: 'object',
-            },
-        ],
-        type: 'suggestion',
-    },
-});