eslint-plugin-jsdoc 55.3.0 → 56.0.0

package/dist/cjs/rules/requireHyphenBeforeParamDescription.js

@@ -0,0 +1,144 @@
+"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, jsdoc, utils, }) => {
+    const [mainCircumstance, { tags = null, } = {},] = context.options;
+    const tgs = /**
+                 * @type {null|"any"|{[key: string]: "always"|"never"}}
+                 */ (tags);
+    /**
+     * @param {import('@es-joy/jsdoccomment').JsdocTagWithInline} jsdocTag
+     * @param {string} targetTagName
+     * @param {"always"|"never"} [circumstance]
+     * @returns {void}
+     */
+    const checkHyphens = (jsdocTag, targetTagName, circumstance = mainCircumstance) => {
+        const always = !circumstance || circumstance === 'always';
+        const desc = /** @type {string} */ (utils.getTagDescription(jsdocTag));
+        if (!desc.trim()) {
+            return;
+        }
+        const startsWithHyphen = (/^\s*-/v).test(desc);
+        const hyphenNewline = (/^\s*-\n/v).test(desc);
+        let lines = 0;
+        for (const { tokens, } of jsdocTag.source) {
+            if (tokens.description) {
+                break;
+            }
+            lines++;
+        }
+        if (always && !hyphenNewline) {
+            if (!startsWithHyphen) {
+                let fixIt = true;
+                for (const { tokens, } of jsdocTag.source) {
+                    if (tokens.description) {
+                        tokens.description = tokens.description.replace(/^(\s*)/v, '$1- ');
+                        break;
+                    }
+                    // Linebreak after name since has no description
+                    if (tokens.name) {
+                        fixIt = false;
+                        break;
+                    }
+                }
+                if (fixIt) {
+                    utils.reportJSDoc(`There must be a hyphen before @${targetTagName} description.`, {
+                        line: jsdocTag.source[0].number + lines,
+                    }, () => { });
+                }
+            }
+        }
+        else if (startsWithHyphen) {
+            utils.reportJSDoc(always ?
+                `There must be no hyphen followed by newline after the @${targetTagName} name.` :
+                `There must be no hyphen before @${targetTagName} description.`, {
+                line: jsdocTag.source[0].number + lines,
+            }, () => {
+                for (const { tokens, } of jsdocTag.source) {
+                    if (tokens.description) {
+                        tokens.description = tokens.description.replace(/^\s*-\s*/v, '');
+                        if (hyphenNewline) {
+                            tokens.postName = '';
+                        }
+                        break;
+                    }
+                }
+            }, true);
+        }
+    };
+    utils.forEachPreferredTag('param', checkHyphens);
+    if (tgs) {
+        const tagEntries = Object.entries(tgs);
+        for (const [tagName, circumstance,] of tagEntries) {
+            if (tagName === '*') {
+                const preferredParamTag = utils.getPreferredTagName({
+                    tagName: 'param',
+                });
+                for (const { tag, } of jsdoc.tags) {
+                    if (tag === preferredParamTag || tagEntries.some(([tagNme,]) => {
+                        return tagNme !== '*' && tagNme === tag;
+                    })) {
+                        continue;
+                    }
+                    utils.forEachPreferredTag(tag, (jsdocTag, targetTagName) => {
+                        checkHyphens(jsdocTag, targetTagName, 
+                        /** @type {"always"|"never"} */ (circumstance));
+                    });
+                }
+                continue;
+            }
+            utils.forEachPreferredTag(tagName, (jsdocTag, targetTagName) => {
+                checkHyphens(jsdocTag, targetTagName, 
+                /** @type {"always"|"never"} */ (circumstance));
+            });
+        }
+    }
+}, {
+    iterateAllJsdocs: true,
+    meta: {
+        docs: {
+            description: 'Requires a hyphen before the `@param` description.',
+            url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-hyphen-before-param-description.md#repos-sticky-header',
+        },
+        fixable: 'code',
+        schema: [
+            {
+                enum: [
+                    'always', 'never',
+                ],
+                type: 'string',
+            },
+            {
+                additionalProperties: false,
+                properties: {
+                    tags: {
+                        anyOf: [
+                            {
+                                patternProperties: {
+                                    '.*': {
+                                        enum: [
+                                            'always', 'never',
+                                        ],
+                                        type: 'string',
+                                    },
+                                },
+                                type: 'object',
+                            },
+                            {
+                                enum: [
+                                    'any',
+                                ],
+                                type: 'string',
+                            },
+                        ],
+                    },
+                },
+                type: 'object',
+            },
+        ],
+        type: 'layout',
+    },
+});

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

@@ -0,0 +1,25 @@
+declare const _default: {
+    create(context: import("eslint").Rule.RuleContext): {};
+    meta: {
+        docs: {
+            category: string;
+            description: string;
+            recommended: boolean;
+            url: string;
+        };
+        fixable: "code";
+        messages: {
+            missingJsDoc: string;
+        };
+        schema: import("json-schema").JSONSchema4[];
+        type: "suggestion";
+    };
+};
+export default _default;
+export type RequireJsdocOpts = {
+    ancestorsOnly: boolean;
+    esm: boolean;
+    initModuleExports: boolean;
+    initWindow: boolean;
+};
+export type ESLintOrTSNode = import("eslint").Rule.Node | import("@typescript-eslint/types").TSESTree.Node;