eslint-plugin-jsdoc 63.3.2 → 64.0.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.
Files changed (270) hide show
  1. package/dist/index.d.ts +7 -4
  2. package/package.json +27 -52
  3. package/src/index.js +7 -8
  4. package/dist/WarnSettings.cjs +0 -38
  5. package/dist/WarnSettings.cjs.map +0 -1
  6. package/dist/alignTransform.cjs +0 -402
  7. package/dist/alignTransform.cjs.map +0 -1
  8. package/dist/buildForbidRuleDefinition.cjs +0 -101
  9. package/dist/buildForbidRuleDefinition.cjs.map +0 -1
  10. package/dist/buildRejectOrPreferRuleDefinition.cjs +0 -352
  11. package/dist/buildRejectOrPreferRuleDefinition.cjs.map +0 -1
  12. package/dist/cjs/WarnSettings.d.ts +0 -16
  13. package/dist/cjs/alignTransform.d.ts +0 -33
  14. package/dist/cjs/buildForbidRuleDefinition.d.ts +0 -14
  15. package/dist/cjs/buildRejectOrPreferRuleDefinition.d.ts +0 -8
  16. package/dist/cjs/defaultTagOrder.d.ts +0 -4
  17. package/dist/cjs/exportParser.d.ts +0 -40
  18. package/dist/cjs/getDefaultTagStructureForMode.d.ts +0 -10
  19. package/dist/cjs/getJsdocProcessorPlugin.d.cts +0 -5
  20. package/dist/cjs/getJsdocProcessorPlugin.d.ts +0 -66
  21. package/dist/cjs/index-cjs.d.ts +0 -23
  22. package/dist/cjs/index.cjs.d.cts +0 -2
  23. package/dist/cjs/iterateJsdoc.d.cts +0 -7
  24. package/dist/cjs/iterateJsdoc.d.ts +0 -495
  25. package/dist/cjs/jsdocUtils.d.ts +0 -500
  26. package/dist/cjs/rules/checkAccess.d.ts +0 -2
  27. package/dist/cjs/rules/checkAlignment.d.ts +0 -2
  28. package/dist/cjs/rules/checkExamples.d.ts +0 -3
  29. package/dist/cjs/rules/checkIndentation.d.ts +0 -2
  30. package/dist/cjs/rules/checkLineAlignment.d.ts +0 -9
  31. package/dist/cjs/rules/checkParamNames.d.ts +0 -2
  32. package/dist/cjs/rules/checkPropertyNames.d.ts +0 -2
  33. package/dist/cjs/rules/checkSyntax.d.ts +0 -2
  34. package/dist/cjs/rules/checkTagNames.d.ts +0 -2
  35. package/dist/cjs/rules/checkTemplateNames.d.ts +0 -2
  36. package/dist/cjs/rules/checkTypes.d.ts +0 -7
  37. package/dist/cjs/rules/checkValues.d.ts +0 -2
  38. package/dist/cjs/rules/convertToJsdocComments.d.ts +0 -266
  39. package/dist/cjs/rules/emptyTags.d.ts +0 -2
  40. package/dist/cjs/rules/escapeInlineTags.d.ts +0 -2
  41. package/dist/cjs/rules/implementsOnClasses.d.ts +0 -2
  42. package/dist/cjs/rules/importsAsDependencies.d.ts +0 -2
  43. package/dist/cjs/rules/informativeDocs.d.ts +0 -2
  44. package/dist/cjs/rules/linesBeforeBlock.d.ts +0 -2
  45. package/dist/cjs/rules/matchDescription.d.ts +0 -2
  46. package/dist/cjs/rules/matchName.d.ts +0 -2
  47. package/dist/cjs/rules/multilineBlocks.d.ts +0 -2
  48. package/dist/cjs/rules/noBadBlocks.d.ts +0 -2
  49. package/dist/cjs/rules/noBlankBlockDescriptions.d.ts +0 -2
  50. package/dist/cjs/rules/noBlankBlocks.d.ts +0 -2
  51. package/dist/cjs/rules/noDefaults.d.ts +0 -2
  52. package/dist/cjs/rules/noMissingSyntax.d.ts +0 -9
  53. package/dist/cjs/rules/noMultiAsterisks.d.ts +0 -2
  54. package/dist/cjs/rules/noRestrictedSyntax.d.ts +0 -2
  55. package/dist/cjs/rules/noTypes.d.ts +0 -2
  56. package/dist/cjs/rules/noUndefinedTypes.d.ts +0 -2
  57. package/dist/cjs/rules/normalizeSeeLinks.d.ts +0 -2
  58. package/dist/cjs/rules/preferImportTag.d.ts +0 -2
  59. package/dist/cjs/rules/requireAsteriskPrefix.d.ts +0 -2
  60. package/dist/cjs/rules/requireDescription.d.ts +0 -2
  61. package/dist/cjs/rules/requireDescriptionCompleteSentence.d.ts +0 -2
  62. package/dist/cjs/rules/requireExample.d.ts +0 -2
  63. package/dist/cjs/rules/requireFileOverview.d.ts +0 -2
  64. package/dist/cjs/rules/requireHyphenBeforeParamDescription.d.ts +0 -2
  65. package/dist/cjs/rules/requireJsdoc.d.ts +0 -24
  66. package/dist/cjs/rules/requireParam.d.ts +0 -3
  67. package/dist/cjs/rules/requireParamDescription.d.ts +0 -2
  68. package/dist/cjs/rules/requireParamName.d.ts +0 -2
  69. package/dist/cjs/rules/requireParamType.d.ts +0 -2
  70. package/dist/cjs/rules/requireProperty.d.ts +0 -2
  71. package/dist/cjs/rules/requirePropertyDescription.d.ts +0 -2
  72. package/dist/cjs/rules/requirePropertyName.d.ts +0 -2
  73. package/dist/cjs/rules/requirePropertyType.d.ts +0 -2
  74. package/dist/cjs/rules/requireRejects.d.ts +0 -2
  75. package/dist/cjs/rules/requireReturns.d.ts +0 -2
  76. package/dist/cjs/rules/requireReturnsCheck.d.ts +0 -2
  77. package/dist/cjs/rules/requireReturnsDescription.d.ts +0 -2
  78. package/dist/cjs/rules/requireReturnsType.d.ts +0 -2
  79. package/dist/cjs/rules/requireTags.d.ts +0 -2
  80. package/dist/cjs/rules/requireTemplate.d.ts +0 -2
  81. package/dist/cjs/rules/requireThrows.d.ts +0 -2
  82. package/dist/cjs/rules/requireYields.d.ts +0 -2
  83. package/dist/cjs/rules/requireYieldsCheck.d.ts +0 -2
  84. package/dist/cjs/rules/sortTags.d.ts +0 -2
  85. package/dist/cjs/rules/tagLines.d.ts +0 -2
  86. package/dist/cjs/rules/textEscaping.d.ts +0 -2
  87. package/dist/cjs/rules/tsMethodSignatureStyle.d.ts +0 -2
  88. package/dist/cjs/rules/tsNoEmptyObjectType.d.ts +0 -2
  89. package/dist/cjs/rules/tsNoUnnecessaryTemplateExpression.d.ts +0 -2
  90. package/dist/cjs/rules/tsPreferFunctionType.d.ts +0 -2
  91. package/dist/cjs/rules/typeFormatting.d.ts +0 -2
  92. package/dist/cjs/rules/validTypes.d.ts +0 -2
  93. package/dist/cjs/tagNames.d.ts +0 -15
  94. package/dist/cjs/utils/hasReturnValue.d.ts +0 -19
  95. package/dist/defaultTagOrder.cjs +0 -46
  96. package/dist/defaultTagOrder.cjs.map +0 -1
  97. package/dist/exportParser.cjs +0 -732
  98. package/dist/exportParser.cjs.map +0 -1
  99. package/dist/generateDocs.cjs +0 -342
  100. package/dist/generateDocs.cjs.map +0 -1
  101. package/dist/generateOptions.cjs +0 -62
  102. package/dist/generateOptions.cjs.map +0 -1
  103. package/dist/generateRule.cjs +0 -248
  104. package/dist/generateRule.cjs.map +0 -1
  105. package/dist/generateRuleTypes.cjs +0 -24
  106. package/dist/generateRuleTypes.cjs.map +0 -1
  107. package/dist/getDefaultTagStructureForMode.cjs +0 -289
  108. package/dist/getDefaultTagStructureForMode.cjs.map +0 -1
  109. package/dist/getJsdocProcessorPlugin.cjs +0 -587
  110. package/dist/getJsdocProcessorPlugin.cjs.map +0 -1
  111. package/dist/getJsdocProcessorPlugin.cts +0 -5
  112. package/dist/index-cjs.cjs +0 -598
  113. package/dist/index-cjs.cjs.map +0 -1
  114. package/dist/index-cjs.d.ts +0 -24
  115. package/dist/index-esm.cjs +0 -162
  116. package/dist/index-esm.cjs.map +0 -1
  117. package/dist/index-esm.d.ts +0 -72
  118. package/dist/index.cjs +0 -746
  119. package/dist/index.cjs.cts +0 -3
  120. package/dist/index.cjs.map +0 -1
  121. package/dist/iterateJsdoc.cjs +0 -2150
  122. package/dist/iterateJsdoc.cjs.map +0 -1
  123. package/dist/iterateJsdoc.cts +0 -7
  124. package/dist/jsdocUtils.cjs +0 -1786
  125. package/dist/jsdocUtils.cjs.map +0 -1
  126. package/dist/rules/checkAccess.cjs +0 -40
  127. package/dist/rules/checkAccess.cjs.map +0 -1
  128. package/dist/rules/checkAlignment.cjs +0 -78
  129. package/dist/rules/checkAlignment.cjs.map +0 -1
  130. package/dist/rules/checkExamples.cjs +0 -521
  131. package/dist/rules/checkExamples.cjs.map +0 -1
  132. package/dist/rules/checkIndentation.cjs +0 -170
  133. package/dist/rules/checkIndentation.cjs.map +0 -1
  134. package/dist/rules/checkLineAlignment.cjs +0 -398
  135. package/dist/rules/checkLineAlignment.cjs.map +0 -1
  136. package/dist/rules/checkParamNames.cjs +0 -407
  137. package/dist/rules/checkParamNames.cjs.map +0 -1
  138. package/dist/rules/checkPropertyNames.cjs +0 -135
  139. package/dist/rules/checkPropertyNames.cjs.map +0 -1
  140. package/dist/rules/checkSyntax.cjs +0 -38
  141. package/dist/rules/checkSyntax.cjs.map +0 -1
  142. package/dist/rules/checkTagNames.cjs +0 -312
  143. package/dist/rules/checkTagNames.cjs.map +0 -1
  144. package/dist/rules/checkTemplateNames.cjs +0 -192
  145. package/dist/rules/checkTemplateNames.cjs.map +0 -1
  146. package/dist/rules/checkTypes.cjs +0 -111
  147. package/dist/rules/checkTypes.cjs.map +0 -1
  148. package/dist/rules/checkValues.cjs +0 -166
  149. package/dist/rules/checkValues.cjs.map +0 -1
  150. package/dist/rules/convertToJsdocComments.cjs +0 -356
  151. package/dist/rules/convertToJsdocComments.cjs.map +0 -1
  152. package/dist/rules/emptyTags.cjs +0 -98
  153. package/dist/rules/emptyTags.cjs.map +0 -1
  154. package/dist/rules/escapeInlineTags.cjs +0 -234
  155. package/dist/rules/escapeInlineTags.cjs.map +0 -1
  156. package/dist/rules/implementsOnClasses.cjs +0 -74
  157. package/dist/rules/implementsOnClasses.cjs.map +0 -1
  158. package/dist/rules/importsAsDependencies.cjs +0 -104
  159. package/dist/rules/importsAsDependencies.cjs.map +0 -1
  160. package/dist/rules/informativeDocs.cjs +0 -187
  161. package/dist/rules/informativeDocs.cjs.map +0 -1
  162. package/dist/rules/linesBeforeBlock.cjs +0 -120
  163. package/dist/rules/linesBeforeBlock.cjs.map +0 -1
  164. package/dist/rules/matchDescription.cjs +0 -356
  165. package/dist/rules/matchDescription.cjs.map +0 -1
  166. package/dist/rules/matchName.cjs +0 -160
  167. package/dist/rules/matchName.cjs.map +0 -1
  168. package/dist/rules/multilineBlocks.cjs +0 -431
  169. package/dist/rules/multilineBlocks.cjs.map +0 -1
  170. package/dist/rules/noBadBlocks.cjs +0 -100
  171. package/dist/rules/noBadBlocks.cjs.map +0 -1
  172. package/dist/rules/noBlankBlockDescriptions.cjs +0 -63
  173. package/dist/rules/noBlankBlockDescriptions.cjs.map +0 -1
  174. package/dist/rules/noBlankBlocks.cjs +0 -54
  175. package/dist/rules/noBlankBlocks.cjs.map +0 -1
  176. package/dist/rules/noDefaults.cjs +0 -102
  177. package/dist/rules/noDefaults.cjs.map +0 -1
  178. package/dist/rules/noMissingSyntax.cjs +0 -196
  179. package/dist/rules/noMissingSyntax.cjs.map +0 -1
  180. package/dist/rules/noMultiAsterisks.cjs +0 -126
  181. package/dist/rules/noMultiAsterisks.cjs.map +0 -1
  182. package/dist/rules/noRestrictedSyntax.cjs +0 -68
  183. package/dist/rules/noRestrictedSyntax.cjs.map +0 -1
  184. package/dist/rules/noTypes.cjs +0 -101
  185. package/dist/rules/noTypes.cjs.map +0 -1
  186. package/dist/rules/noUndefinedTypes.cjs +0 -616
  187. package/dist/rules/noUndefinedTypes.cjs.map +0 -1
  188. package/dist/rules/normalizeSeeLinks.cjs +0 -271
  189. package/dist/rules/normalizeSeeLinks.cjs.map +0 -1
  190. package/dist/rules/preferImportTag.cjs +0 -362
  191. package/dist/rules/preferImportTag.cjs.map +0 -1
  192. package/dist/rules/requireAsteriskPrefix.cjs +0 -190
  193. package/dist/rules/requireAsteriskPrefix.cjs.map +0 -1
  194. package/dist/rules/requireDescription.cjs +0 -164
  195. package/dist/rules/requireDescription.cjs.map +0 -1
  196. package/dist/rules/requireDescriptionCompleteSentence.cjs +0 -321
  197. package/dist/rules/requireDescriptionCompleteSentence.cjs.map +0 -1
  198. package/dist/rules/requireExample.cjs +0 -136
  199. package/dist/rules/requireExample.cjs.map +0 -1
  200. package/dist/rules/requireFileOverview.cjs +0 -194
  201. package/dist/rules/requireFileOverview.cjs.map +0 -1
  202. package/dist/rules/requireHyphenBeforeParamDescription.cjs +0 -166
  203. package/dist/rules/requireHyphenBeforeParamDescription.cjs.map +0 -1
  204. package/dist/rules/requireJsdoc.cjs +0 -721
  205. package/dist/rules/requireJsdoc.cjs.map +0 -1
  206. package/dist/rules/requireParam.cjs +0 -772
  207. package/dist/rules/requireParam.cjs.map +0 -1
  208. package/dist/rules/requireParamDescription.cjs +0 -105
  209. package/dist/rules/requireParamDescription.cjs.map +0 -1
  210. package/dist/rules/requireParamName.cjs +0 -68
  211. package/dist/rules/requireParamName.cjs.map +0 -1
  212. package/dist/rules/requireParamType.cjs +0 -104
  213. package/dist/rules/requireParamType.cjs.map +0 -1
  214. package/dist/rules/requireProperty.cjs +0 -63
  215. package/dist/rules/requireProperty.cjs.map +0 -1
  216. package/dist/rules/requirePropertyDescription.cjs +0 -29
  217. package/dist/rules/requirePropertyDescription.cjs.map +0 -1
  218. package/dist/rules/requirePropertyName.cjs +0 -29
  219. package/dist/rules/requirePropertyName.cjs.map +0 -1
  220. package/dist/rules/requirePropertyType.cjs +0 -29
  221. package/dist/rules/requirePropertyType.cjs.map +0 -1
  222. package/dist/rules/requireRejects.cjs +0 -226
  223. package/dist/rules/requireRejects.cjs.map +0 -1
  224. package/dist/rules/requireReturns.cjs +0 -262
  225. package/dist/rules/requireReturns.cjs.map +0 -1
  226. package/dist/rules/requireReturnsCheck.cjs +0 -225
  227. package/dist/rules/requireReturnsCheck.cjs.map +0 -1
  228. package/dist/rules/requireReturnsDescription.cjs +0 -72
  229. package/dist/rules/requireReturnsDescription.cjs.map +0 -1
  230. package/dist/rules/requireReturnsType.cjs +0 -68
  231. package/dist/rules/requireReturnsType.cjs.map +0 -1
  232. package/dist/rules/requireTags.cjs +0 -74
  233. package/dist/rules/requireTags.cjs.map +0 -1
  234. package/dist/rules/requireTemplate.cjs +0 -220
  235. package/dist/rules/requireTemplate.cjs.map +0 -1
  236. package/dist/rules/requireThrows.cjs +0 -118
  237. package/dist/rules/requireThrows.cjs.map +0 -1
  238. package/dist/rules/requireYields.cjs +0 -224
  239. package/dist/rules/requireYields.cjs.map +0 -1
  240. package/dist/rules/requireYieldsCheck.cjs +0 -179
  241. package/dist/rules/requireYieldsCheck.cjs.map +0 -1
  242. package/dist/rules/sortTags.cjs +0 -656
  243. package/dist/rules/sortTags.cjs.map +0 -1
  244. package/dist/rules/tagLines.cjs +0 -374
  245. package/dist/rules/tagLines.cjs.map +0 -1
  246. package/dist/rules/textEscaping.cjs +0 -141
  247. package/dist/rules/textEscaping.cjs.map +0 -1
  248. package/dist/rules/tsMethodSignatureStyle.cjs +0 -240
  249. package/dist/rules/tsMethodSignatureStyle.cjs.map +0 -1
  250. package/dist/rules/tsNoEmptyObjectType.cjs +0 -62
  251. package/dist/rules/tsNoEmptyObjectType.cjs.map +0 -1
  252. package/dist/rules/tsNoUnnecessaryTemplateExpression.cjs +0 -104
  253. package/dist/rules/tsNoUnnecessaryTemplateExpression.cjs.map +0 -1
  254. package/dist/rules/tsPreferFunctionType.cjs +0 -110
  255. package/dist/rules/tsPreferFunctionType.cjs.map +0 -1
  256. package/dist/rules/typeFormatting.cjs +0 -607
  257. package/dist/rules/typeFormatting.cjs.map +0 -1
  258. package/dist/rules/validTypes.cjs +0 -324
  259. package/dist/rules/validTypes.cjs.map +0 -1
  260. package/dist/tagNames.cjs +0 -244
  261. package/dist/tagNames.cjs.map +0 -1
  262. package/dist/to-valid-identifier.cjs +0 -263
  263. package/dist/utils/hasReturnValue.cjs +0 -495
  264. package/dist/utils/hasReturnValue.cjs.map +0 -1
  265. package/rollup.config.js +0 -16
  266. package/src/getJsdocProcessorPlugin.cts +0 -5
  267. package/src/index-cjs.js +0 -758
  268. package/src/index-esm.js +0 -196
  269. package/src/index.cjs.cts +0 -3
  270. package/src/iterateJsdoc.cts +0 -7
@@ -1,225 +0,0 @@
1
- "use strict";
2
-
3
- Object.defineProperty(exports, "__esModule", {
4
- value: true
5
- });
6
- exports.default = void 0;
7
- var _iterateJsdoc = _interopRequireDefault(require("../iterateJsdoc.cjs"));
8
- var _jsdocUtils = require("../jsdocUtils.cjs");
9
- var _jsdoccomment = require("@es-joy/jsdoccomment");
10
- function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
11
- /**
12
- * @type {Partial<Record<import('../jsdocUtils.js').ParserMode, import('jsdoc-type-pratt-parser').ParseMode[]>>}
13
- */
14
- const parseTypeModes = {
15
- closure: ['closure'],
16
- jsdoc: ['jsdoc'],
17
- typescript: ['typescript']
18
- };
19
-
20
- /**
21
- * @param {import('../iterateJsdoc.js').Utils} utils
22
- * @param {import('../iterateJsdoc.js').Settings} settings
23
- * @returns {boolean}
24
- */
25
- const canSkip = (utils, settings) => {
26
- const voidingTags = [
27
- // An abstract function is by definition incomplete
28
- // so it is perfectly fine if a return is documented but
29
- // not present within the function.
30
- // A subclass may inherit the doc and implement the
31
- // missing return.
32
- 'abstract', 'virtual',
33
- // A constructor function returns `this` by default, so may be `@returns`
34
- // tag indicating this but no explicit return
35
- 'class', 'constructor', 'interface'];
36
- if (settings.mode === 'closure') {
37
- // Structural Interface in GCC terms, equivalent to @interface tag as far as this rule is concerned
38
- voidingTags.push('record');
39
- }
40
- return utils.hasATag(voidingTags) || utils.isConstructor() || utils.classHasTag('interface') || settings.mode === 'closure' && utils.classHasTag('record');
41
- };
42
-
43
- /**
44
- * @param {import('jsdoc-type-pratt-parser').RootResult} parsedType
45
- * @returns {import('jsdoc-type-pratt-parser').RootResult}
46
- */
47
- const getReturnTypeLevelNode = parsedType => {
48
- return parsedType.type === 'JsdocTypeParenthesis' ? parsedType.element : parsedType;
49
- };
50
-
51
- /**
52
- * @param {import('eslint').Rule.RuleContext} context
53
- * @param {import('../jsdocUtils.js').ParserMode} mode
54
- * @returns {import('../jsdocUtils.js').ParserMode}
55
- */
56
- const getParseMode = (context, mode) => {
57
- const {
58
- jsdoc
59
- } = /** @type {{jsdoc?: {mode?: import('../jsdocUtils.js').ParserMode}}} */context.settings;
60
- return jsdoc?.mode ?? mode;
61
- };
62
- var _default = exports.default = (0, _iterateJsdoc.default)(({
63
- context,
64
- node,
65
- report,
66
- settings,
67
- sourceCode,
68
- utils
69
- }) => {
70
- const {
71
- exemptAsync = true,
72
- exemptGenerators = settings.mode === 'typescript',
73
- noNativeTypes = true,
74
- reportMissingReturnForUndefinedTypes = false
75
- } = context.options[0] || {};
76
- const {
77
- mode
78
- } = settings;
79
- const parseMode = getParseMode(context, mode);
80
- if (canSkip(utils, settings)) {
81
- return;
82
- }
83
- const isAsync = utils.isAsync();
84
- if (exemptAsync && isAsync) {
85
- return;
86
- }
87
- const tagName = /** @type {string} */utils.getPreferredTagName({
88
- tagName: 'returns'
89
- });
90
- if (!tagName) {
91
- return;
92
- }
93
- const tags = utils.getTags(tagName);
94
- if (tags.length === 0) {
95
- return;
96
- }
97
- if (tags.length > 1) {
98
- report(`Found more than one @${tagName} declaration.`);
99
- return;
100
- }
101
- const [tag] = tags;
102
- const type = tag.type.trim();
103
-
104
- // https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-7.html#assertion-functions
105
- if (/asserts\s/v.test(type)) {
106
- return;
107
- }
108
- const returnNever = type === 'never';
109
- const typedefs = (0, _jsdocUtils.getDocumentNamepathDefiningTags)(sourceCode);
110
-
111
- /**
112
- * @param {import('comment-parser').Spec} returnTag
113
- * @returns {boolean}
114
- */
115
- const mayReturnUndefined = returnTag => {
116
- if (utils.mayBeUndefinedTypeTag(returnTag)) {
117
- return true;
118
- }
119
- const returnType = returnTag.type.trim();
120
- let parsedType;
121
- try {
122
- parsedType = (0, _jsdoccomment.tryParse)(returnType, parseTypeModes[parseMode]);
123
- } catch {
124
- return false;
125
- }
126
- const returnTypeLevelNode = getReturnTypeLevelNode(parsedType);
127
- let returnIsUndefined = false;
128
- (0, _jsdoccomment.traverse)(returnTypeLevelNode, (nde, parentNode) => {
129
- const isReturnLevelNode = !parentNode || returnTypeLevelNode.type === 'JsdocTypeUnion' && parentNode === returnTypeLevelNode;
130
- if (!isReturnLevelNode) {
131
- return;
132
- }
133
- const {
134
- type: nodeType
135
- } = /** @type {import('jsdoc-type-pratt-parser').RootResult} */nde;
136
- if (nodeType === 'JsdocTypeUndefined') {
137
- returnIsUndefined = true;
138
- return;
139
- }
140
- if (nodeType !== 'JsdocTypeName') {
141
- return;
142
- }
143
- const {
144
- value
145
- } = /** @type {import('jsdoc-type-pratt-parser').NameResult} */nde;
146
- if (value === 'void') {
147
- returnIsUndefined = true;
148
- return;
149
- }
150
- const referencedTypedef = typedefs.find(typedefTag => {
151
- return typedefTag.name === value;
152
- });
153
- if (referencedTypedef && utils.mayBeUndefinedTypeTag(referencedTypedef)) {
154
- returnIsUndefined = true;
155
- }
156
- });
157
- return returnIsUndefined;
158
- };
159
- if (returnNever && utils.hasValueOrExecutorHasNonEmptyResolveValue(false)) {
160
- report(`JSDoc @${tagName} declaration set with "never" but return expression is present in function.`);
161
- return;
162
- }
163
- if (noNativeTypes && isAsync && _jsdocUtils.strictNativeTypes.includes(type)) {
164
- report('Function is async or otherwise returns a Promise but the return type is a native type.');
165
- return;
166
- }
167
-
168
- // In case a return value is declared in JSDoc, we also expect one in the code.
169
- if (!returnNever && (reportMissingReturnForUndefinedTypes || !mayReturnUndefined(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)) {
170
- report(`JSDoc @${tagName} declaration present but return expression not available in function.`);
171
- }
172
- }, {
173
- meta: {
174
- docs: {
175
- description: 'Requires a return statement in function body if a `@returns` tag is specified in JSDoc comment(and reports if multiple `@returns` tags are present).',
176
- url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-returns-check.md#repos-sticky-header'
177
- },
178
- schema: [{
179
- additionalProperties: false,
180
- properties: {
181
- exemptAsync: {
182
- default: true,
183
- description: `By default, functions which return a \`Promise\` that are not
184
- detected as resolving with a non-\`undefined\` value and \`async\` functions
185
- (even ones that do not explicitly return a value, as these are returning a
186
- \`Promise\` implicitly) will be exempted from reporting by this rule.
187
- If you wish to insist that only \`Promise\`'s which resolve to
188
- non-\`undefined\` values or \`async\` functions with explicit \`return\`'s will
189
- be exempted from reporting (i.e., that \`async\` functions can be reported
190
- if they lack an explicit (non-\`undefined\`) \`return\` when a \`@returns\` is
191
- present), you can set \`exemptAsync\` to \`false\` on the options object.`,
192
- type: 'boolean'
193
- },
194
- exemptGenerators: {
195
- description: `Because a generator might be labeled as having a
196
- \`IterableIterator\` \`@returns\` value (along with an iterator type
197
- corresponding to the type of any \`yield\` statements), projects might wish to
198
- leverage \`@returns\` in generators even without a \`return\` statement. This
199
- option is therefore \`true\` by default in \`typescript\` mode (in "jsdoc" mode,
200
- one might be more likely to take advantage of \`@yields\`). Set it to \`false\`
201
- if you wish for a missing \`return\` to be flagged regardless.`,
202
- type: 'boolean'
203
- },
204
- noNativeTypes: {
205
- description: `Whether to check that async functions do not
206
- indicate they return non-native types. Defaults to \`true\`.`,
207
- type: 'boolean'
208
- },
209
- reportMissingReturnForUndefinedTypes: {
210
- default: false,
211
- description: `If \`true\` and no return or
212
- resolve value is found, this setting will even insist that reporting occur
213
- with \`void\` or \`undefined\` (including as an indicated \`Promise\` type).
214
- Unlike \`require-returns\`, with this option in the rule, one can
215
- *discourage* the labeling of \`undefined\` types. Defaults to \`false\`.`,
216
- type: 'boolean'
217
- }
218
- },
219
- type: 'object'
220
- }],
221
- type: 'suggestion'
222
- }
223
- });
224
- module.exports = exports.default;
225
- //# sourceMappingURL=requireReturnsCheck.cjs.map
@@ -1 +0,0 @@
1
- {"version":3,"file":"requireReturnsCheck.cjs","names":["iterateJsdoc","getDocumentNamepathDefiningTags","tryParseType","traverse","strictNativeTypes"],"sources":["../../src/rules/requireReturnsCheck.js"],"sourcesContent":["import iterateJsdoc from '../iterateJsdoc.js';\nimport {\n getDocumentNamepathDefiningTags,\n strictNativeTypes,\n} from '../jsdocUtils.js';\nimport {\n traverse,\n tryParse as tryParseType,\n} from '@es-joy/jsdoccomment';\n\n/**\n * @type {Partial<Record<import('../jsdocUtils.js').ParserMode, import('jsdoc-type-pratt-parser').ParseMode[]>>}\n */\nconst parseTypeModes = {\n closure: [\n 'closure',\n ],\n jsdoc: [\n 'jsdoc',\n ],\n typescript: [\n 'typescript',\n ],\n};\n\n/**\n * @param {import('../iterateJsdoc.js').Utils} utils\n * @param {import('../iterateJsdoc.js').Settings} settings\n * @returns {boolean}\n */\nconst canSkip = (utils, settings) => {\n const voidingTags = [\n // An abstract function is by definition incomplete\n // so it is perfectly fine if a return is documented but\n // not present within the function.\n // A subclass may inherit the doc and implement the\n // missing return.\n 'abstract',\n 'virtual',\n\n // A constructor function returns `this` by default, so may be `@returns`\n // tag indicating this but no explicit return\n 'class',\n 'constructor',\n 'interface',\n ];\n\n if (settings.mode === 'closure') {\n // Structural Interface in GCC terms, equivalent to @interface tag as far as this rule is concerned\n voidingTags.push('record');\n }\n\n return utils.hasATag(voidingTags) ||\n utils.isConstructor() ||\n utils.classHasTag('interface') ||\n settings.mode === 'closure' && utils.classHasTag('record');\n};\n\n/**\n * @param {import('jsdoc-type-pratt-parser').RootResult} parsedType\n * @returns {import('jsdoc-type-pratt-parser').RootResult}\n */\nconst getReturnTypeLevelNode = (parsedType) => {\n return parsedType.type === 'JsdocTypeParenthesis' ?\n parsedType.element :\n parsedType;\n};\n\n/**\n * @param {import('eslint').Rule.RuleContext} context\n * @param {import('../jsdocUtils.js').ParserMode} mode\n * @returns {import('../jsdocUtils.js').ParserMode}\n */\nconst getParseMode = (context, mode) => {\n const {\n jsdoc,\n } = /** @type {{jsdoc?: {mode?: import('../jsdocUtils.js').ParserMode}}} */ (context.settings);\n\n return jsdoc?.mode ?? mode;\n};\n\nexport default iterateJsdoc(({\n context,\n node,\n report,\n settings,\n sourceCode,\n utils,\n}) => {\n const {\n exemptAsync = true,\n exemptGenerators = settings.mode === 'typescript',\n noNativeTypes = true,\n reportMissingReturnForUndefinedTypes = false,\n } = context.options[0] || {};\n const {\n mode,\n } = settings;\n const parseMode = getParseMode(context, mode);\n\n if (canSkip(utils, settings)) {\n return;\n }\n\n const isAsync = utils.isAsync();\n if (exemptAsync && isAsync) {\n return;\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 === 0) {\n return;\n }\n\n if (tags.length > 1) {\n report(`Found more than one @${tagName} declaration.`);\n\n return;\n }\n\n const [\n tag,\n ] = tags;\n\n const type = tag.type.trim();\n\n // https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-7.html#assertion-functions\n if (/asserts\\s/v.test(type)) {\n return;\n }\n\n const returnNever = type === 'never';\n const typedefs = getDocumentNamepathDefiningTags(sourceCode);\n\n /**\n * @param {import('comment-parser').Spec} returnTag\n * @returns {boolean}\n */\n const mayReturnUndefined = (returnTag) => {\n if (utils.mayBeUndefinedTypeTag(returnTag)) {\n return true;\n }\n\n const returnType = returnTag.type.trim();\n let parsedType;\n try {\n parsedType = tryParseType(returnType, parseTypeModes[parseMode]);\n } catch {\n return false;\n }\n\n const returnTypeLevelNode = getReturnTypeLevelNode(parsedType);\n let returnIsUndefined = false;\n traverse(returnTypeLevelNode, (nde, parentNode) => {\n const isReturnLevelNode = !parentNode ||\n returnTypeLevelNode.type === 'JsdocTypeUnion' && parentNode === returnTypeLevelNode;\n if (!isReturnLevelNode) {\n return;\n }\n\n const {\n type: nodeType,\n } = /** @type {import('jsdoc-type-pratt-parser').RootResult} */ (nde);\n\n if (nodeType === 'JsdocTypeUndefined') {\n returnIsUndefined = true;\n return;\n }\n\n if (nodeType !== 'JsdocTypeName') {\n return;\n }\n\n const {\n value,\n } = /** @type {import('jsdoc-type-pratt-parser').NameResult} */ (nde);\n\n if (value === 'void') {\n returnIsUndefined = true;\n return;\n }\n\n const referencedTypedef = typedefs.find((typedefTag) => {\n return typedefTag.name === value;\n });\n\n if (referencedTypedef && utils.mayBeUndefinedTypeTag(referencedTypedef)) {\n returnIsUndefined = true;\n }\n });\n\n return returnIsUndefined;\n };\n\n if (returnNever && utils.hasValueOrExecutorHasNonEmptyResolveValue(false)) {\n report(`JSDoc @${tagName} declaration set with \"never\" but return expression is present in function.`);\n\n return;\n }\n\n if (noNativeTypes && isAsync && strictNativeTypes.includes(type)) {\n report('Function is async or otherwise returns a Promise but the return type is a native type.');\n return;\n }\n\n // In case a return value is declared in JSDoc, we also expect one in the code.\n if (\n !returnNever &&\n (\n reportMissingReturnForUndefinedTypes ||\n !mayReturnUndefined(tag)\n ) &&\n (tag.type === '' && !utils.hasValueOrExecutorHasNonEmptyResolveValue(\n exemptAsync,\n ) ||\n tag.type !== '' && !utils.hasValueOrExecutorHasNonEmptyResolveValue(\n exemptAsync,\n true,\n )) &&\n Boolean(\n !exemptGenerators || !node ||\n !('generator' in /** @type {import('../iterateJsdoc.js').Node} */ (node)) ||\n !(/** @type {import('@typescript-eslint/types').TSESTree.FunctionDeclaration} */ (node)).generator,\n )\n ) {\n report(`JSDoc @${tagName} declaration present but return expression not available in function.`);\n }\n}, {\n meta: {\n docs: {\n description: 'Requires a return statement in function body if a `@returns` tag is specified in JSDoc comment(and reports if multiple `@returns` tags are present).',\n url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-returns-check.md#repos-sticky-header',\n },\n schema: [\n {\n additionalProperties: false,\n properties: {\n exemptAsync: {\n default: true,\n description: `By default, functions which return a \\`Promise\\` that are not\ndetected as resolving with a non-\\`undefined\\` value and \\`async\\` functions\n(even ones that do not explicitly return a value, as these are returning a\n\\`Promise\\` implicitly) will be exempted from reporting by this rule.\nIf you wish to insist that only \\`Promise\\`'s which resolve to\nnon-\\`undefined\\` values or \\`async\\` functions with explicit \\`return\\`'s will\nbe exempted from reporting (i.e., that \\`async\\` functions can be reported\nif they lack an explicit (non-\\`undefined\\`) \\`return\\` when a \\`@returns\\` is\npresent), you can set \\`exemptAsync\\` to \\`false\\` on the options object.`,\n type: 'boolean',\n },\n exemptGenerators: {\n description: `Because a generator might be labeled as having a\n\\`IterableIterator\\` \\`@returns\\` value (along with an iterator type\ncorresponding to the type of any \\`yield\\` statements), projects might wish to\nleverage \\`@returns\\` in generators even without a \\`return\\` statement. This\noption is therefore \\`true\\` by default in \\`typescript\\` mode (in \"jsdoc\" mode,\none might be more likely to take advantage of \\`@yields\\`). Set it to \\`false\\`\nif you wish for a missing \\`return\\` to be flagged regardless.`,\n type: 'boolean',\n },\n noNativeTypes: {\n description: `Whether to check that async functions do not\nindicate they return non-native types. Defaults to \\`true\\`.`,\n type: 'boolean',\n },\n reportMissingReturnForUndefinedTypes: {\n default: false,\n description: `If \\`true\\` and no return or\nresolve value is found, this setting will even insist that reporting occur\nwith \\`void\\` or \\`undefined\\` (including as an indicated \\`Promise\\` type).\nUnlike \\`require-returns\\`, with this option in the rule, one can\n*discourage* the labeling of \\`undefined\\` types. Defaults to \\`false\\`.`,\n type: 'boolean',\n },\n },\n type: 'object',\n },\n ],\n type: 'suggestion',\n },\n});\n"],"mappings":"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","ignoreList":[]}
@@ -1,72 +0,0 @@
1
- "use strict";
2
-
3
- Object.defineProperty(exports, "__esModule", {
4
- value: true
5
- });
6
- exports.default = void 0;
7
- var _iterateJsdoc = _interopRequireDefault(require("../iterateJsdoc.cjs"));
8
- function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
9
- var _default = exports.default = (0, _iterateJsdoc.default)(({
10
- report,
11
- utils
12
- }) => {
13
- utils.forEachPreferredTag('returns', (jsdocTag, targetTagName) => {
14
- const type = jsdocTag.type && jsdocTag.type.trim();
15
- if (['Promise<undefined>', 'Promise<void>', 'undefined', 'void'].includes(type)) {
16
- return;
17
- }
18
- if (!jsdocTag.description.trim()) {
19
- report(`Missing JSDoc @${targetTagName} description.`, null, jsdocTag);
20
- }
21
- });
22
- }, {
23
- contextDefaults: true,
24
- meta: {
25
- docs: {
26
- description: 'Requires that the `@returns` tag has a `description` value (not including `void`/`undefined` type returns).',
27
- url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-returns-description.md#repos-sticky-header'
28
- },
29
- schema: [{
30
- additionalProperties: false,
31
- properties: {
32
- contexts: {
33
- description: `Set this to an array of strings representing the AST context (or an object with
34
- optional \`context\` and \`comment\` properties) where you wish the rule to be applied.
35
-
36
- \`context\` defaults to \`any\` and \`comment\` defaults to no specific comment context.
37
-
38
- Overrides the default contexts (\`ArrowFunctionExpression\`, \`FunctionDeclaration\`,
39
- \`FunctionExpression\`). Set to \`"any"\` if you want
40
- the rule to apply to any JSDoc block throughout your files (as is necessary
41
- for finding function blocks not attached to a function declaration or
42
- expression, i.e., \`@callback\` or \`@function\` (or its aliases \`@func\` or
43
- \`@method\`) (including those associated with an \`@interface\`).
44
-
45
- See the ["AST and Selectors"](../advanced.md#ast-and-selectors)
46
- section of our Advanced docs for more on the expected format.`,
47
- items: {
48
- anyOf: [{
49
- type: 'string'
50
- }, {
51
- additionalProperties: false,
52
- properties: {
53
- comment: {
54
- type: 'string'
55
- },
56
- context: {
57
- type: 'string'
58
- }
59
- },
60
- type: 'object'
61
- }]
62
- },
63
- type: 'array'
64
- }
65
- },
66
- type: 'object'
67
- }],
68
- type: 'suggestion'
69
- }
70
- });
71
- module.exports = exports.default;
72
- //# sourceMappingURL=requireReturnsDescription.cjs.map
@@ -1 +0,0 @@
1
- {"version":3,"file":"requireReturnsDescription.cjs","names":["iterateJsdoc"],"sources":["../../src/rules/requireReturnsDescription.js"],"sourcesContent":["import iterateJsdoc from '../iterateJsdoc.js';\n\nexport default iterateJsdoc(({\n report,\n utils,\n}) => {\n utils.forEachPreferredTag('returns', (jsdocTag, targetTagName) => {\n const type = jsdocTag.type && jsdocTag.type.trim();\n\n if ([\n 'Promise<undefined>', 'Promise<void>', 'undefined', 'void',\n ].includes(type)) {\n return;\n }\n\n if (!jsdocTag.description.trim()) {\n report(`Missing JSDoc @${targetTagName} description.`, null, jsdocTag);\n }\n });\n}, {\n contextDefaults: true,\n meta: {\n docs: {\n description: 'Requires that the `@returns` tag has a `description` value (not including `void`/`undefined` type returns).',\n url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-returns-description.md#repos-sticky-header',\n },\n schema: [\n {\n additionalProperties: false,\n properties: {\n contexts: {\n description: `Set this to an array of strings representing the AST context (or an object with\noptional \\`context\\` and \\`comment\\` properties) where you wish the rule to be applied.\n\n\\`context\\` defaults to \\`any\\` and \\`comment\\` defaults to no specific comment context.\n\nOverrides the default contexts (\\`ArrowFunctionExpression\\`, \\`FunctionDeclaration\\`,\n\\`FunctionExpression\\`). Set to \\`\"any\"\\` if you want\nthe rule to apply to any JSDoc block throughout your files (as is necessary\nfor finding function blocks not attached to a function declaration or\nexpression, i.e., \\`@callback\\` or \\`@function\\` (or its aliases \\`@func\\` or\n\\`@method\\`) (including those associated with an \\`@interface\\`).\n\nSee the [\"AST and Selectors\"](../advanced.md#ast-and-selectors)\nsection of our Advanced docs for more on the expected format.`,\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 },\n type: 'object',\n },\n ],\n },\n type: 'array',\n },\n },\n type: 'object',\n },\n ],\n type: 'suggestion',\n },\n});\n"],"mappings":";;;;;;AAAA;AAA8C;AAAA,iCAE/B,IAAAA,qBAAY,EAAC,CAAC;EAC3B,MAAM;EACN;AACF,CAAC,KAAK;EACJ,KAAK,CAAC,mBAAmB,CAAC,SAAS,EAAE,CAAC,QAAQ,EAAE,aAAa,KAAK;IAChE,MAAM,IAAI,GAAG,QAAQ,CAAC,IAAI,IAAI,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAElD,IAAI,CACF,oBAAoB,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,CAC3D,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE;MAChB;IACF;IAEA,IAAI,CAAC,QAAQ,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,EAAE;MAChC,MAAM,CAAC,kBAAkB,aAAa,eAAe,EAAE,IAAI,EAAE,QAAQ,CAAC;IACxE;EACF,CAAC,CAAC;AACJ,CAAC,EAAE;EACD,eAAe,EAAE,IAAI;EACrB,IAAI,EAAE;IACJ,IAAI,EAAE;MACJ,WAAW,EAAE,6GAA6G;MAC1H,GAAG,EAAE;IACP,CAAC;IACD,MAAM,EAAE,CACN;MACE,oBAAoB,EAAE,KAAK;MAC3B,UAAU,EAAE;QACV,QAAQ,EAAE;UACR,WAAW,EAAE;AACzB;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,8DAA8D;UAClD,KAAK,EAAE;YACL,KAAK,EAAE,CACL;cACE,IAAI,EAAE;YACR,CAAC,EACD;cACE,oBAAoB,EAAE,KAAK;cAC3B,UAAU,EAAE;gBACV,OAAO,EAAE;kBACP,IAAI,EAAE;gBACR,CAAC;gBACD,OAAO,EAAE;kBACP,IAAI,EAAE;gBACR;cACF,CAAC;cACD,IAAI,EAAE;YACR,CAAC;UAEL,CAAC;UACD,IAAI,EAAE;QACR;MACF,CAAC;MACD,IAAI,EAAE;IACR,CAAC,CACF;IACD,IAAI,EAAE;EACR;AACF,CAAC,CAAC;AAAA","ignoreList":[]}
@@ -1,68 +0,0 @@
1
- "use strict";
2
-
3
- Object.defineProperty(exports, "__esModule", {
4
- value: true
5
- });
6
- exports.default = void 0;
7
- var _iterateJsdoc = _interopRequireDefault(require("../iterateJsdoc.cjs"));
8
- function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
9
- var _default = exports.default = (0, _iterateJsdoc.default)(({
10
- report,
11
- utils
12
- }) => {
13
- utils.forEachPreferredTag('returns', (jsdocTag, targetTagName) => {
14
- if (!jsdocTag.type) {
15
- report(`Missing JSDoc @${targetTagName} type.`, null, jsdocTag);
16
- }
17
- });
18
- }, {
19
- contextDefaults: true,
20
- meta: {
21
- docs: {
22
- description: 'Requires that `@returns` tag has type value (in curly brackets).',
23
- url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-returns-type.md#repos-sticky-header'
24
- },
25
- schema: [{
26
- additionalProperties: false,
27
- properties: {
28
- contexts: {
29
- description: `Set this to an array of strings representing the AST context (or an object with
30
- optional \`context\` and \`comment\` properties) where you wish the rule to be applied.
31
-
32
- \`context\` defaults to \`any\` and \`comment\` defaults to no specific comment context.
33
-
34
- Overrides the default contexts (\`ArrowFunctionExpression\`, \`FunctionDeclaration\`,
35
- \`FunctionExpression\`). Set to \`"any"\` if you want
36
- the rule to apply to any JSDoc block throughout your files (as is necessary
37
- for finding function blocks not attached to a function declaration or
38
- expression, i.e., \`@callback\` or \`@function\` (or its aliases \`@func\` or
39
- \`@method\`) (including those associated with an \`@interface\`).
40
-
41
- See the ["AST and Selectors"](../advanced.md#ast-and-selectors)
42
- section of our Advanced docs for more on the expected format.`,
43
- items: {
44
- anyOf: [{
45
- type: 'string'
46
- }, {
47
- additionalProperties: false,
48
- properties: {
49
- comment: {
50
- type: 'string'
51
- },
52
- context: {
53
- type: 'string'
54
- }
55
- },
56
- type: 'object'
57
- }]
58
- },
59
- type: 'array'
60
- }
61
- },
62
- type: 'object'
63
- }],
64
- type: 'suggestion'
65
- }
66
- });
67
- module.exports = exports.default;
68
- //# sourceMappingURL=requireReturnsType.cjs.map
@@ -1 +0,0 @@
1
- {"version":3,"file":"requireReturnsType.cjs","names":["iterateJsdoc"],"sources":["../../src/rules/requireReturnsType.js"],"sourcesContent":["import iterateJsdoc from '../iterateJsdoc.js';\n\nexport default iterateJsdoc(({\n report,\n utils,\n}) => {\n utils.forEachPreferredTag('returns', (jsdocTag, targetTagName) => {\n if (!jsdocTag.type) {\n report(`Missing JSDoc @${targetTagName} type.`, null, jsdocTag);\n }\n });\n}, {\n contextDefaults: true,\n meta: {\n docs: {\n description: 'Requires that `@returns` tag has type value (in curly brackets).',\n url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-returns-type.md#repos-sticky-header',\n },\n schema: [\n {\n additionalProperties: false,\n properties: {\n contexts: {\n description: `Set this to an array of strings representing the AST context (or an object with\noptional \\`context\\` and \\`comment\\` properties) where you wish the rule to be applied.\n\n\\`context\\` defaults to \\`any\\` and \\`comment\\` defaults to no specific comment context.\n\nOverrides the default contexts (\\`ArrowFunctionExpression\\`, \\`FunctionDeclaration\\`,\n\\`FunctionExpression\\`). Set to \\`\"any\"\\` if you want\nthe rule to apply to any JSDoc block throughout your files (as is necessary\nfor finding function blocks not attached to a function declaration or\nexpression, i.e., \\`@callback\\` or \\`@function\\` (or its aliases \\`@func\\` or\n\\`@method\\`) (including those associated with an \\`@interface\\`).\n\nSee the [\"AST and Selectors\"](../advanced.md#ast-and-selectors)\nsection of our Advanced docs for more on the expected format.`,\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 },\n type: 'object',\n },\n ],\n },\n type: 'array',\n },\n },\n type: 'object',\n },\n ],\n type: 'suggestion',\n },\n});\n"],"mappings":";;;;;;AAAA;AAA8C;AAAA,iCAE/B,IAAAA,qBAAY,EAAC,CAAC;EAC3B,MAAM;EACN;AACF,CAAC,KAAK;EACJ,KAAK,CAAC,mBAAmB,CAAC,SAAS,EAAE,CAAC,QAAQ,EAAE,aAAa,KAAK;IAChE,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE;MAClB,MAAM,CAAC,kBAAkB,aAAa,QAAQ,EAAE,IAAI,EAAE,QAAQ,CAAC;IACjE;EACF,CAAC,CAAC;AACJ,CAAC,EAAE;EACD,eAAe,EAAE,IAAI;EACrB,IAAI,EAAE;IACJ,IAAI,EAAE;MACJ,WAAW,EAAE,kEAAkE;MAC/E,GAAG,EAAE;IACP,CAAC;IACD,MAAM,EAAE,CACN;MACE,oBAAoB,EAAE,KAAK;MAC3B,UAAU,EAAE;QACV,QAAQ,EAAE;UACR,WAAW,EAAE;AACzB;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,8DAA8D;UAClD,KAAK,EAAE;YACL,KAAK,EAAE,CACL;cACE,IAAI,EAAE;YACR,CAAC,EACD;cACE,oBAAoB,EAAE,KAAK;cAC3B,UAAU,EAAE;gBACV,OAAO,EAAE;kBACP,IAAI,EAAE;gBACR,CAAC;gBACD,OAAO,EAAE;kBACP,IAAI,EAAE;gBACR;cACF,CAAC;cACD,IAAI,EAAE;YACR,CAAC;UAEL,CAAC;UACD,IAAI,EAAE;QACR;MACF,CAAC;MACD,IAAI,EAAE;IACR,CAAC,CACF;IACD,IAAI,EAAE;EACR;AACF,CAAC,CAAC;AAAA","ignoreList":[]}
@@ -1,74 +0,0 @@
1
- "use strict";
2
-
3
- Object.defineProperty(exports, "__esModule", {
4
- value: true
5
- });
6
- exports.default = void 0;
7
- var _buildForbidRuleDefinition = require("../buildForbidRuleDefinition.cjs");
8
- var _default = exports.default = (0, _buildForbidRuleDefinition.buildForbidRuleDefinition)({
9
- description: 'Requires tags be present, optionally for specific contexts',
10
- getContexts(context, report) {
11
- // Transformed options to this option in `modifyContext`:
12
- if (!context.options[0].contexts) {
13
- report('Rule `require-tags` is missing a `tags` option.');
14
- return false;
15
- }
16
- const {
17
- contexts
18
- } = context.options[0];
19
- return contexts;
20
- },
21
- modifyContext(context) {
22
- const tags = /** @type {(string|{tag: string, context: string})[]} */
23
- context.options?.[0]?.tags;
24
- const cntxts = tags?.map(tag => {
25
- const tagName = typeof tag === 'string' ? tag : tag.tag;
26
- return {
27
- comment: `JsdocBlock:not(*:has(JsdocTag[tag=${tagName}]))`,
28
- context: typeof tag === 'string' ? 'any' : tag.context,
29
- message: `Missing required tag "${tagName}"`
30
- };
31
- });
32
-
33
- // Reproduce context object with our own `contexts`
34
- const propertyDescriptors = Object.getOwnPropertyDescriptors(context);
35
- return Object.create(Object.getPrototypeOf(context), {
36
- ...propertyDescriptors,
37
- options: {
38
- ...propertyDescriptors.options,
39
- value: [{
40
- contexts: cntxts
41
- }]
42
- }
43
- });
44
- },
45
- schema: [{
46
- additionalProperties: false,
47
- properties: {
48
- tags: {
49
- description: `May be an array of either strings or objects with
50
- a string \`tag\` property and \`context\` string property.`,
51
- items: {
52
- anyOf: [{
53
- type: 'string'
54
- }, {
55
- properties: {
56
- context: {
57
- type: 'string'
58
- },
59
- tag: {
60
- type: 'string'
61
- }
62
- },
63
- type: 'object'
64
- }]
65
- },
66
- type: 'array'
67
- }
68
- },
69
- type: 'object'
70
- }],
71
- url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-tags.md#repos-sticky-header'
72
- });
73
- module.exports = exports.default;
74
- //# sourceMappingURL=requireTags.cjs.map
@@ -1 +0,0 @@
1
- {"version":3,"file":"requireTags.cjs","names":["buildForbidRuleDefinition"],"sources":["../../src/rules/requireTags.js"],"sourcesContent":["import {\n buildForbidRuleDefinition,\n} from '../buildForbidRuleDefinition.js';\n\nexport default buildForbidRuleDefinition({\n description: 'Requires tags be present, optionally for specific contexts',\n getContexts (context, report) {\n // Transformed options to this option in `modifyContext`:\n if (!context.options[0].contexts) {\n report('Rule `require-tags` is missing a `tags` option.');\n return false;\n }\n\n const {\n contexts,\n } = context.options[0];\n\n return contexts;\n },\n modifyContext (context) {\n const tags = /** @type {(string|{tag: string, context: string})[]} */ (\n context.options?.[0]?.tags\n );\n\n const cntxts = tags?.map((tag) => {\n const tagName = typeof tag === 'string' ? tag : tag.tag;\n return {\n comment: `JsdocBlock:not(*:has(JsdocTag[tag=${\n tagName\n }]))`,\n context: typeof tag === 'string' ? 'any' : tag.context,\n message: `Missing required tag \"${tagName}\"`,\n };\n });\n\n // Reproduce context object with our own `contexts`\n const propertyDescriptors = Object.getOwnPropertyDescriptors(context);\n return Object.create(\n Object.getPrototypeOf(context),\n {\n ...propertyDescriptors,\n options: {\n ...propertyDescriptors.options,\n value: [\n {\n contexts: cntxts,\n },\n ],\n },\n },\n );\n },\n schema: [\n {\n additionalProperties: false,\n properties: {\n tags: {\n description: `May be an array of either strings or objects with\na string \\`tag\\` property and \\`context\\` string property.`,\n items: {\n anyOf: [\n {\n type: 'string',\n },\n {\n properties: {\n context: {\n type: 'string',\n },\n tag: {\n type: 'string',\n },\n },\n type: 'object',\n },\n ],\n },\n type: 'array',\n },\n },\n type: 'object',\n },\n ],\n url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-tags.md#repos-sticky-header',\n});\n"],"mappings":";;;;;;AAAA;AAEyC,iCAE1B,IAAAA,2BAAA,yBAAyB,EAAC;EACvC,WAAW,EAAE,4DAA4D;EACzE,WAAW,CAAE,OAAO,EAAE,MAAM,EAAE;IAC5B;IACA,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;MAChC,MAAM,CAAC,iDAAiD,CAAC;MACzD,OAAO,KAAK;IACd;IAEA,MAAM;MACJ;IACF,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC;IAEtB,OAAO,QAAQ;EACjB,CAAC;EACD,aAAa,CAAE,OAAO,EAAE;IACtB,MAAM,IAAI,GAAG;IACX,OAAO,CAAC,OAAO,GAAG,CAAC,CAAC,EAAE,IACvB;IAED,MAAM,MAAM,GAAG,IAAI,EAAE,GAAG,CAAE,GAAG,IAAK;MAChC,MAAM,OAAO,GAAG,OAAO,GAAG,KAAK,QAAQ,GAAG,GAAG,GAAG,GAAG,CAAC,GAAG;MACvD,OAAO;QACL,OAAO,EAAE,qCACP,OAAO,KACJ;QACL,OAAO,EAAE,OAAO,GAAG,KAAK,QAAQ,GAAG,KAAK,GAAG,GAAG,CAAC,OAAO;QACtD,OAAO,EAAE,yBAAyB,OAAO;MAC3C,CAAC;IACH,CAAC,CAAC;;IAEF;IACA,MAAM,mBAAmB,GAAG,MAAM,CAAC,yBAAyB,CAAC,OAAO,CAAC;IACrE,OAAO,MAAM,CAAC,MAAM,CAClB,MAAM,CAAC,cAAc,CAAC,OAAO,CAAC,EAC9B;MACE,GAAG,mBAAmB;MACtB,OAAO,EAAE;QACP,GAAG,mBAAmB,CAAC,OAAO;QAC9B,KAAK,EAAE,CACL;UACE,QAAQ,EAAE;QACZ,CAAC;MAEL;IACF,CACF,CAAC;EACH,CAAC;EACD,MAAM,EAAE,CACN;IACE,oBAAoB,EAAE,KAAK;IAC3B,UAAU,EAAE;MACV,IAAI,EAAE;QACJ,WAAW,EAAE;AACvB,2DAA2D;QACjD,KAAK,EAAE;UACL,KAAK,EAAE,CACL;YACE,IAAI,EAAE;UACR,CAAC,EACD;YACE,UAAU,EAAE;cACV,OAAO,EAAE;gBACP,IAAI,EAAE;cACR,CAAC;cACD,GAAG,EAAE;gBACH,IAAI,EAAE;cACR;YACF,CAAC;YACD,IAAI,EAAE;UACR,CAAC;QAEL,CAAC;QACD,IAAI,EAAE;MACR;IACF,CAAC;IACD,IAAI,EAAE;EACR,CAAC,CACF;EACD,GAAG,EAAE;AACP,CAAC,CAAC;AAAA","ignoreList":[]}