eslint-plugin-jsdoc 46.5.1 → 46.7.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
|
@@ -65,8 +65,9 @@ var _default = (0, _iterateJsdoc.default)(({
|
|
|
65
65
|
report,
|
|
66
66
|
utils
|
|
67
67
|
}) => {
|
|
68
|
-
const {
|
|
68
|
+
const /** @type {{aliases: {[key: string]: string[]}, excludedTags: string[], uselessWords: string[]}} */{
|
|
69
69
|
aliases = defaultAliases,
|
|
70
|
+
excludedTags = [],
|
|
70
71
|
uselessWords = defaultUselessWords
|
|
71
72
|
} = context.options[0] || {};
|
|
72
73
|
const nodeNames = getNamesFromNode(node);
|
|
@@ -89,6 +90,9 @@ var _default = (0, _iterateJsdoc.default)(({
|
|
|
89
90
|
} = utils.getDescription();
|
|
90
91
|
let descriptionReported = false;
|
|
91
92
|
for (const tag of jsdoc.tags) {
|
|
93
|
+
if (excludedTags.includes(tag.tag)) {
|
|
94
|
+
continue;
|
|
95
|
+
}
|
|
92
96
|
if (descriptionIsRedundant(tag.description, tag.name)) {
|
|
93
97
|
utils.reportJSDoc('This tag description only repeats the name it describes.', tag);
|
|
94
98
|
}
|
|
@@ -109,6 +113,16 @@ var _default = (0, _iterateJsdoc.default)(({
|
|
|
109
113
|
additionalProperties: false,
|
|
110
114
|
properties: {
|
|
111
115
|
aliases: {
|
|
116
|
+
patternProperties: {
|
|
117
|
+
'.*': {
|
|
118
|
+
items: {
|
|
119
|
+
type: 'string'
|
|
120
|
+
},
|
|
121
|
+
type: 'array'
|
|
122
|
+
}
|
|
123
|
+
}
|
|
124
|
+
},
|
|
125
|
+
excludedTags: {
|
|
112
126
|
items: {
|
|
113
127
|
type: 'string'
|
|
114
128
|
},
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"informativeDocs.js","names":["_iterateJsdoc","_interopRequireDefault","require","_areDocsInformative","obj","__esModule","default","defaultAliases","a","defaultUselessWords","getNamesFromNode","node","type","parent","key","id","name","declarations","init","filter","Boolean","_default","iterateJsdoc","context","jsdoc","report","utils","aliases","uselessWords","options","nodeNames","descriptionIsRedundant","text","extraName","textTrimmed","trim","areDocsInformative","join","description","lastDescriptionLine","getDescription","descriptionReported","tag","tags","reportJSDoc","line","iterateAllJsdocs","meta","docs","url","schema","additionalProperties","properties","items","exports","module"],"sources":["../../src/rules/informativeDocs.js"],"sourcesContent":["import iterateJsdoc from '../iterateJsdoc.js';\nimport {\n areDocsInformative,\n} from 'are-docs-informative';\n\nconst defaultAliases = {\n a: [\n 'an', 'our',\n ],\n};\n\nconst defaultUselessWords = [\n 'a', 'an', 'i', 'in', 'of', 's', 'the',\n];\n\n/* eslint-disable complexity -- Temporary */\n\n/**\n * @param {import('eslint').Rule.Node|import('@typescript-eslint/types').TSESTree.Node|null|undefined} node\n * @returns {string[]}\n */\nconst getNamesFromNode = (node) => {\n switch (node?.type) {\n case 'AccessorProperty':\n case 'MethodDefinition':\n case 'PropertyDefinition':\n case 'TSAbstractAccessorProperty':\n case 'TSAbstractMethodDefinition':\n case 'TSAbstractPropertyDefinition':\n return [\n ...getNamesFromNode(\n /** @type {import('@typescript-eslint/types').TSESTree.Node} */ (\n node.parent\n ).parent,\n ),\n ...getNamesFromNode(\n /** @type {import('@typescript-eslint/types').TSESTree.Node} */\n (node.key),\n ),\n ];\n case 'ClassDeclaration':\n case 'ClassExpression':\n case 'FunctionDeclaration':\n case 'FunctionExpression':\n case 'TSModuleDeclaration':\n case 'TSMethodSignature':\n case 'TSDeclareFunction':\n case 'TSEnumDeclaration':\n case 'TSEnumMember':\n case 'TSInterfaceDeclaration':\n case 'TSTypeAliasDeclaration':\n return getNamesFromNode(\n /** @type {import('@typescript-eslint/types').TSESTree.ClassDeclaration} */\n (node).id,\n );\n case 'Identifier':\n return [\n node.name,\n ];\n case 'Property':\n return getNamesFromNode(\n /** @type {import('@typescript-eslint/types').TSESTree.Node} */\n (node.key),\n );\n case 'VariableDeclaration':\n return getNamesFromNode(\n /** @type {import('@typescript-eslint/types').TSESTree.Node} */\n (node.declarations[0]),\n );\n case 'VariableDeclarator':\n return [\n ...getNamesFromNode(\n /** @type {import('@typescript-eslint/types').TSESTree.Node} */\n (node.id),\n ),\n ...getNamesFromNode(\n /** @type {import('@typescript-eslint/types').TSESTree.Node} */\n (node.init),\n ),\n ].filter(Boolean);\n default:\n return [];\n }\n};\n/* eslint-enable complexity -- Temporary */\n\nexport default iterateJsdoc(({\n context,\n jsdoc,\n node,\n report,\n utils,\n}) => {\n const {\n aliases = defaultAliases,\n uselessWords = defaultUselessWords,\n } = context.options[0] || {};\n const nodeNames = getNamesFromNode(node);\n\n /**\n * @param {string} text\n * @param {string} extraName\n * @returns {boolean}\n */\n const descriptionIsRedundant = (text, extraName = '') => {\n const textTrimmed = text.trim();\n return Boolean(textTrimmed) && !areDocsInformative(textTrimmed, [\n extraName, nodeNames,\n ].filter(Boolean).join(' '), {\n aliases,\n uselessWords,\n });\n };\n\n const {\n description,\n lastDescriptionLine,\n } = utils.getDescription();\n let descriptionReported = false;\n\n for (const tag of jsdoc.tags) {\n if (descriptionIsRedundant(tag.description, tag.name)) {\n utils.reportJSDoc(\n 'This tag description only repeats the name it describes.',\n tag,\n );\n }\n\n descriptionReported ||= tag.description === description &&\n /** @type {import('comment-parser').Spec & {line: import('../iterateJsdoc.js').Integer}} */\n (tag).line === lastDescriptionLine;\n }\n\n if (!descriptionReported && descriptionIsRedundant(description)) {\n report('This description only repeats the name it describes.');\n }\n}, {\n iterateAllJsdocs: true,\n meta: {\n docs: {\n description:\n 'This rule reports doc comments that only restate their attached name.',\n url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/informative-docs.md#repos-sticky-header',\n },\n schema: [\n {\n additionalProperties: false,\n properties: {\n aliases: {\n items: {\n type: 'string',\n },\n type: 'array',\n },\n uselessWords: {\n items: {\n type: 'string',\n },\n type: 'array',\n },\n },\n type: 'object',\n },\n ],\n type: 'suggestion',\n },\n});\n"],"mappings":";;;;;;AAAA,IAAAA,aAAA,GAAAC,sBAAA,CAAAC,OAAA;AACA,IAAAC,mBAAA,GAAAD,OAAA;AAE8B,SAAAD,uBAAAG,GAAA,WAAAA,GAAA,IAAAA,GAAA,CAAAC,UAAA,GAAAD,GAAA,KAAAE,OAAA,EAAAF,GAAA;AAE9B,MAAMG,cAAc,GAAG;EACrBC,CAAC,EAAE,CACD,IAAI,EAAE,KAAK;AAEf,CAAC;AAED,MAAMC,mBAAmB,GAAG,CAC1B,GAAG,EAAE,IAAI,EAAE,GAAG,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,EAAE,KAAK,CACvC;;AAED;;AAEA;AACA;AACA;AACA;AACA,MAAMC,gBAAgB,GAAIC,IAAI,IAAK;EACjC,QAAQA,IAAI,aAAJA,IAAI,uBAAJA,IAAI,CAAEC,IAAI;IAClB,KAAK,kBAAkB;IACvB,KAAK,kBAAkB;IACvB,KAAK,oBAAoB;IACzB,KAAK,4BAA4B;IACjC,KAAK,4BAA4B;IACjC,KAAK,8BAA8B;MACjC,OAAO,CACL,GAAGF,gBAAgB,EACjB,+DACEC,IAAI,CAACE,MAAM,CACXA,MACJ,CAAC,EACD,GAAGH,gBAAgB,EACjB;MACCC,IAAI,CAACG,GACR,CAAC,CACF;IACH,KAAK,kBAAkB;IACvB,KAAK,iBAAiB;IACtB,KAAK,qBAAqB;IAC1B,KAAK,oBAAoB;IACzB,KAAK,qBAAqB;IAC1B,KAAK,mBAAmB;IACxB,KAAK,mBAAmB;IACxB,KAAK,mBAAmB;IACxB,KAAK,cAAc;IACnB,KAAK,wBAAwB;IAC7B,KAAK,wBAAwB;MAC3B,OAAOJ,gBAAgB,EACrB;MACCC,IAAI,CAAEI,EACT,CAAC;IACH,KAAK,YAAY;MACf,OAAO,CACLJ,IAAI,CAACK,IAAI,CACV;IACH,KAAK,UAAU;MACb,OAAON,gBAAgB,EACrB;MACCC,IAAI,CAACG,GACR,CAAC;IACH,KAAK,qBAAqB;MACxB,OAAOJ,gBAAgB,EACrB;MACCC,IAAI,CAACM,YAAY,CAAC,CAAC,CACtB,CAAC;IACH,KAAK,oBAAoB;MACvB,OAAO,CACL,GAAGP,gBAAgB,EACjB;MACCC,IAAI,CAACI,EACR,CAAC,EACD,GAAGL,gBAAgB,EACjB;MACCC,IAAI,CAACO,IACR,CAAC,CACF,CAACC,MAAM,CAACC,OAAO,CAAC;IACnB;MACE,OAAO,EAAE;EACX;AACF,CAAC;AACD;AAAA,IAAAC,QAAA,GAEe,IAAAC,qBAAY,EAAC,CAAC;EAC3BC,OAAO;EACPC,KAAK;EACLb,IAAI;EACJc,MAAM;EACNC;AACF,CAAC,KAAK;EACJ,MAAM;
|
|
1
|
+
{"version":3,"file":"informativeDocs.js","names":["_iterateJsdoc","_interopRequireDefault","require","_areDocsInformative","obj","__esModule","default","defaultAliases","a","defaultUselessWords","getNamesFromNode","node","type","parent","key","id","name","declarations","init","filter","Boolean","_default","iterateJsdoc","context","jsdoc","report","utils","aliases","excludedTags","uselessWords","options","nodeNames","descriptionIsRedundant","text","extraName","textTrimmed","trim","areDocsInformative","join","description","lastDescriptionLine","getDescription","descriptionReported","tag","tags","includes","reportJSDoc","line","iterateAllJsdocs","meta","docs","url","schema","additionalProperties","properties","patternProperties","items","exports","module"],"sources":["../../src/rules/informativeDocs.js"],"sourcesContent":["import iterateJsdoc from '../iterateJsdoc.js';\nimport {\n areDocsInformative,\n} from 'are-docs-informative';\n\nconst defaultAliases = {\n a: [\n 'an', 'our',\n ],\n};\n\nconst defaultUselessWords = [\n 'a', 'an', 'i', 'in', 'of', 's', 'the',\n];\n\n/* eslint-disable complexity -- Temporary */\n\n/**\n * @param {import('eslint').Rule.Node|import('@typescript-eslint/types').TSESTree.Node|null|undefined} node\n * @returns {string[]}\n */\nconst getNamesFromNode = (node) => {\n switch (node?.type) {\n case 'AccessorProperty':\n case 'MethodDefinition':\n case 'PropertyDefinition':\n case 'TSAbstractAccessorProperty':\n case 'TSAbstractMethodDefinition':\n case 'TSAbstractPropertyDefinition':\n return [\n ...getNamesFromNode(\n /** @type {import('@typescript-eslint/types').TSESTree.Node} */ (\n node.parent\n ).parent,\n ),\n ...getNamesFromNode(\n /** @type {import('@typescript-eslint/types').TSESTree.Node} */\n (node.key),\n ),\n ];\n case 'ClassDeclaration':\n case 'ClassExpression':\n case 'FunctionDeclaration':\n case 'FunctionExpression':\n case 'TSModuleDeclaration':\n case 'TSMethodSignature':\n case 'TSDeclareFunction':\n case 'TSEnumDeclaration':\n case 'TSEnumMember':\n case 'TSInterfaceDeclaration':\n case 'TSTypeAliasDeclaration':\n return getNamesFromNode(\n /** @type {import('@typescript-eslint/types').TSESTree.ClassDeclaration} */\n (node).id,\n );\n case 'Identifier':\n return [\n node.name,\n ];\n case 'Property':\n return getNamesFromNode(\n /** @type {import('@typescript-eslint/types').TSESTree.Node} */\n (node.key),\n );\n case 'VariableDeclaration':\n return getNamesFromNode(\n /** @type {import('@typescript-eslint/types').TSESTree.Node} */\n (node.declarations[0]),\n );\n case 'VariableDeclarator':\n return [\n ...getNamesFromNode(\n /** @type {import('@typescript-eslint/types').TSESTree.Node} */\n (node.id),\n ),\n ...getNamesFromNode(\n /** @type {import('@typescript-eslint/types').TSESTree.Node} */\n (node.init),\n ),\n ].filter(Boolean);\n default:\n return [];\n }\n};\n/* eslint-enable complexity -- Temporary */\n\nexport default iterateJsdoc(({\n context,\n jsdoc,\n node,\n report,\n utils,\n}) => {\n const /** @type {{aliases: {[key: string]: string[]}, excludedTags: string[], uselessWords: string[]}} */ {\n aliases = defaultAliases,\n excludedTags = [],\n uselessWords = defaultUselessWords,\n } = context.options[0] || {};\n const nodeNames = getNamesFromNode(node);\n\n /**\n * @param {string} text\n * @param {string} extraName\n * @returns {boolean}\n */\n const descriptionIsRedundant = (text, extraName = '') => {\n const textTrimmed = text.trim();\n return Boolean(textTrimmed) && !areDocsInformative(textTrimmed, [\n extraName, nodeNames,\n ].filter(Boolean).join(' '), {\n aliases,\n uselessWords,\n });\n };\n\n const {\n description,\n lastDescriptionLine,\n } = utils.getDescription();\n let descriptionReported = false;\n\n for (const tag of jsdoc.tags) {\n if (excludedTags.includes(tag.tag)) {\n continue;\n }\n\n if (descriptionIsRedundant(tag.description, tag.name)) {\n utils.reportJSDoc(\n 'This tag description only repeats the name it describes.',\n tag,\n );\n }\n\n descriptionReported ||= tag.description === description &&\n /** @type {import('comment-parser').Spec & {line: import('../iterateJsdoc.js').Integer}} */\n (tag).line === lastDescriptionLine;\n }\n\n if (!descriptionReported && descriptionIsRedundant(description)) {\n report('This description only repeats the name it describes.');\n }\n}, {\n iterateAllJsdocs: true,\n meta: {\n docs: {\n description:\n 'This rule reports doc comments that only restate their attached name.',\n url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/informative-docs.md#repos-sticky-header',\n },\n schema: [\n {\n additionalProperties: false,\n properties: {\n aliases: {\n patternProperties: {\n '.*': {\n items: {\n type: 'string',\n },\n type: 'array',\n },\n },\n },\n excludedTags: {\n items: {\n type: 'string',\n },\n type: 'array',\n },\n uselessWords: {\n items: {\n type: 'string',\n },\n type: 'array',\n },\n },\n type: 'object',\n },\n ],\n type: 'suggestion',\n },\n});\n"],"mappings":"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"}
|
|
@@ -42,6 +42,7 @@ var _default = (0, _iterateJsdoc.default)(({
|
|
|
42
42
|
}) => {
|
|
43
43
|
const {
|
|
44
44
|
contexts,
|
|
45
|
+
enableFixer = false,
|
|
45
46
|
forceRequireReturn = false,
|
|
46
47
|
forceReturnsWithAsync = false
|
|
47
48
|
} = context.options[0] || {};
|
|
@@ -91,7 +92,9 @@ var _default = (0, _iterateJsdoc.default)(({
|
|
|
91
92
|
return iteratingFunction && utils.hasValueOrExecutorHasNonEmptyResolveValue(forceReturnsWithAsync);
|
|
92
93
|
};
|
|
93
94
|
if (shouldReport()) {
|
|
94
|
-
|
|
95
|
+
utils.reportJSDoc(`Missing JSDoc @${tagName} declaration.`, null, enableFixer ? () => {
|
|
96
|
+
utils.addTag(tagName);
|
|
97
|
+
} : null);
|
|
95
98
|
}
|
|
96
99
|
}, {
|
|
97
100
|
contextDefaults: true,
|
|
@@ -100,6 +103,7 @@ var _default = (0, _iterateJsdoc.default)(({
|
|
|
100
103
|
description: 'Requires that returns are documented.',
|
|
101
104
|
url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-returns.md#repos-sticky-header'
|
|
102
105
|
},
|
|
106
|
+
fixable: 'code',
|
|
103
107
|
schema: [{
|
|
104
108
|
additionalProperties: false,
|
|
105
109
|
properties: {
|
|
@@ -133,6 +137,9 @@ var _default = (0, _iterateJsdoc.default)(({
|
|
|
133
137
|
},
|
|
134
138
|
type: 'array'
|
|
135
139
|
},
|
|
140
|
+
enableFixer: {
|
|
141
|
+
type: 'boolean'
|
|
142
|
+
},
|
|
136
143
|
exemptedBy: {
|
|
137
144
|
items: {
|
|
138
145
|
type: 'string'
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"requireReturns.js","names":["_iterateJsdoc","_interopRequireDefault","require","obj","__esModule","default","canSkip","utils","hasATag","avoidDocs","_default","iterateJsdoc","info","comment","report","context","contexts","forceRequireReturn","forceReturnsWithAsync","options","forceRequireReturnContext","foundContext","findContext","tagName","getPreferredTagName","tags","getTags","length","iteratingFunction","isIteratingFunction","tag","missingReturnTag","shouldReport","isVirtualFunction","isAsync","hasTag","hasValueOrExecutorHasNonEmptyResolveValue","contextDefaults","meta","docs","description","url","schema","additionalProperties","properties","checkConstructors","type","checkGetters","items","anyOf","exemptedBy","exports","module"],"sources":["../../src/rules/requireReturns.js"],"sourcesContent":["import iterateJsdoc from '../iterateJsdoc.js';\n\n/**\n * We can skip checking for a return value, in case the documentation is inherited\n * or the method is either a constructor or an abstract method.\n *\n * In either of these cases the return value is optional or not defined.\n * @param {import('../iterateJsdoc.js').Utils} utils\n * a reference to the utils which are used to probe if a tag is present or not.\n * @returns {boolean}\n * true in case deep checking can be skipped; otherwise false.\n */\nconst canSkip = (utils) => {\n return utils.hasATag([\n // inheritdoc implies that all documentation is inherited\n // see https://jsdoc.app/tags-inheritdoc.html\n //\n // Abstract methods are by definition incomplete,\n // so it is not an error if it declares a return value but does not implement it.\n 'abstract',\n 'virtual',\n\n // Constructors do not have a return value by definition (https://jsdoc.app/tags-class.html)\n // So we can bail out here, too.\n 'class',\n 'constructor',\n\n // Return type is specified by type in @type\n 'type',\n\n // This seems to imply a class as well\n 'interface',\n ]) ||\n utils.avoidDocs();\n};\n\nexport default iterateJsdoc(({\n info: {\n comment,\n },\n report,\n utils,\n context,\n}) => {\n const {\n contexts,\n forceRequireReturn = false,\n forceReturnsWithAsync = false,\n } = context.options[0] || {};\n\n // A preflight check. We do not need to run a deep check\n // in case the @returns comment is optional or undefined.\n if (canSkip(utils)) {\n return;\n }\n\n /** @type {boolean|undefined} */\n let forceRequireReturnContext;\n if (contexts) {\n const {\n foundContext,\n } = utils.findContext(contexts, comment);\n if (typeof foundContext === 'object') {\n forceRequireReturnContext = foundContext.forceRequireReturn;\n }\n }\n\n const tagName = /** @type {string} */ (utils.getPreferredTagName({\n tagName: 'returns',\n }));\n if (!tagName) {\n return;\n }\n\n const tags = utils.getTags(tagName);\n\n if (tags.length > 1) {\n report(`Found more than one @${tagName} declaration.`);\n }\n\n const iteratingFunction = utils.isIteratingFunction();\n\n // In case the code returns something, we expect a return value in JSDoc.\n const [\n tag,\n ] = tags;\n const missingReturnTag = typeof tag === 'undefined' || tag === null;\n\n const shouldReport = () => {\n if (!missingReturnTag) {\n return false;\n }\n\n if ((forceRequireReturn || forceRequireReturnContext) && (\n iteratingFunction || utils.isVirtualFunction()\n )) {\n return true;\n }\n\n const isAsync = !iteratingFunction && utils.hasTag('async') ||\n iteratingFunction && utils.isAsync();\n\n if (forceReturnsWithAsync && isAsync) {\n return true;\n }\n\n return iteratingFunction && utils.hasValueOrExecutorHasNonEmptyResolveValue(\n forceReturnsWithAsync,\n );\n };\n\n if (shouldReport()) {\n
|
|
1
|
+
{"version":3,"file":"requireReturns.js","names":["_iterateJsdoc","_interopRequireDefault","require","obj","__esModule","default","canSkip","utils","hasATag","avoidDocs","_default","iterateJsdoc","info","comment","report","context","contexts","enableFixer","forceRequireReturn","forceReturnsWithAsync","options","forceRequireReturnContext","foundContext","findContext","tagName","getPreferredTagName","tags","getTags","length","iteratingFunction","isIteratingFunction","tag","missingReturnTag","shouldReport","isVirtualFunction","isAsync","hasTag","hasValueOrExecutorHasNonEmptyResolveValue","reportJSDoc","addTag","contextDefaults","meta","docs","description","url","fixable","schema","additionalProperties","properties","checkConstructors","type","checkGetters","items","anyOf","exemptedBy","exports","module"],"sources":["../../src/rules/requireReturns.js"],"sourcesContent":["import iterateJsdoc from '../iterateJsdoc.js';\n\n/**\n * We can skip checking for a return value, in case the documentation is inherited\n * or the method is either a constructor or an abstract method.\n *\n * In either of these cases the return value is optional or not defined.\n * @param {import('../iterateJsdoc.js').Utils} utils\n * a reference to the utils which are used to probe if a tag is present or not.\n * @returns {boolean}\n * true in case deep checking can be skipped; otherwise false.\n */\nconst canSkip = (utils) => {\n return utils.hasATag([\n // inheritdoc implies that all documentation is inherited\n // see https://jsdoc.app/tags-inheritdoc.html\n //\n // Abstract methods are by definition incomplete,\n // so it is not an error if it declares a return value but does not implement it.\n 'abstract',\n 'virtual',\n\n // Constructors do not have a return value by definition (https://jsdoc.app/tags-class.html)\n // So we can bail out here, too.\n 'class',\n 'constructor',\n\n // Return type is specified by type in @type\n 'type',\n\n // This seems to imply a class as well\n 'interface',\n ]) ||\n utils.avoidDocs();\n};\n\nexport default iterateJsdoc(({\n info: {\n comment,\n },\n report,\n utils,\n context,\n}) => {\n const {\n contexts,\n enableFixer = false,\n forceRequireReturn = false,\n forceReturnsWithAsync = false,\n } = context.options[0] || {};\n\n // A preflight check. We do not need to run a deep check\n // in case the @returns comment is optional or undefined.\n if (canSkip(utils)) {\n return;\n }\n\n /** @type {boolean|undefined} */\n let forceRequireReturnContext;\n if (contexts) {\n const {\n foundContext,\n } = utils.findContext(contexts, comment);\n if (typeof foundContext === 'object') {\n forceRequireReturnContext = foundContext.forceRequireReturn;\n }\n }\n\n const tagName = /** @type {string} */ (utils.getPreferredTagName({\n tagName: 'returns',\n }));\n if (!tagName) {\n return;\n }\n\n const tags = utils.getTags(tagName);\n\n if (tags.length > 1) {\n report(`Found more than one @${tagName} declaration.`);\n }\n\n const iteratingFunction = utils.isIteratingFunction();\n\n // In case the code returns something, we expect a return value in JSDoc.\n const [\n tag,\n ] = tags;\n const missingReturnTag = typeof tag === 'undefined' || tag === null;\n\n const shouldReport = () => {\n if (!missingReturnTag) {\n return false;\n }\n\n if ((forceRequireReturn || forceRequireReturnContext) && (\n iteratingFunction || utils.isVirtualFunction()\n )) {\n return true;\n }\n\n const isAsync = !iteratingFunction && utils.hasTag('async') ||\n iteratingFunction && utils.isAsync();\n\n if (forceReturnsWithAsync && isAsync) {\n return true;\n }\n\n return iteratingFunction && utils.hasValueOrExecutorHasNonEmptyResolveValue(\n forceReturnsWithAsync,\n );\n };\n\n if (shouldReport()) {\n utils.reportJSDoc(`Missing JSDoc @${tagName} declaration.`, null, enableFixer ? () => {\n utils.addTag(tagName);\n } : null);\n }\n}, {\n contextDefaults: true,\n meta: {\n docs: {\n description: 'Requires that returns are documented.',\n url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-returns.md#repos-sticky-header',\n },\n fixable: 'code',\n schema: [\n {\n additionalProperties: false,\n properties: {\n checkConstructors: {\n default: false,\n type: 'boolean',\n },\n checkGetters: {\n default: true,\n type: 'boolean',\n },\n contexts: {\n items: {\n anyOf: [\n {\n type: 'string',\n },\n {\n additionalProperties: false,\n properties: {\n comment: {\n type: 'string',\n },\n context: {\n type: 'string',\n },\n forceRequireReturn: {\n type: 'boolean',\n },\n },\n type: 'object',\n },\n ],\n },\n type: 'array',\n },\n enableFixer: {\n type: 'boolean',\n },\n exemptedBy: {\n items: {\n type: 'string',\n },\n type: 'array',\n },\n forceRequireReturn: {\n default: false,\n type: 'boolean',\n },\n forceReturnsWithAsync: {\n default: false,\n type: 'boolean',\n },\n },\n type: 'object',\n },\n ],\n type: 'suggestion',\n },\n});\n"],"mappings":"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"}
|
package/package.json
CHANGED