eslint-plugin-jsdoc 63.3.3 → 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 (269) hide show
  1. package/package.json +23 -48
  2. package/src/index.js +3 -6
  3. package/dist/WarnSettings.cjs +0 -38
  4. package/dist/WarnSettings.cjs.map +0 -1
  5. package/dist/alignTransform.cjs +0 -402
  6. package/dist/alignTransform.cjs.map +0 -1
  7. package/dist/buildForbidRuleDefinition.cjs +0 -101
  8. package/dist/buildForbidRuleDefinition.cjs.map +0 -1
  9. package/dist/buildRejectOrPreferRuleDefinition.cjs +0 -352
  10. package/dist/buildRejectOrPreferRuleDefinition.cjs.map +0 -1
  11. package/dist/cjs/WarnSettings.d.ts +0 -16
  12. package/dist/cjs/alignTransform.d.ts +0 -33
  13. package/dist/cjs/buildForbidRuleDefinition.d.ts +0 -14
  14. package/dist/cjs/buildRejectOrPreferRuleDefinition.d.ts +0 -8
  15. package/dist/cjs/defaultTagOrder.d.ts +0 -4
  16. package/dist/cjs/exportParser.d.ts +0 -40
  17. package/dist/cjs/getDefaultTagStructureForMode.d.ts +0 -10
  18. package/dist/cjs/getJsdocProcessorPlugin.d.cts +0 -5
  19. package/dist/cjs/getJsdocProcessorPlugin.d.ts +0 -66
  20. package/dist/cjs/index-cjs.d.ts +0 -26
  21. package/dist/cjs/index.cjs.d.cts +0 -2
  22. package/dist/cjs/iterateJsdoc.d.cts +0 -7
  23. package/dist/cjs/iterateJsdoc.d.ts +0 -495
  24. package/dist/cjs/jsdocUtils.d.ts +0 -500
  25. package/dist/cjs/rules/checkAccess.d.ts +0 -2
  26. package/dist/cjs/rules/checkAlignment.d.ts +0 -2
  27. package/dist/cjs/rules/checkExamples.d.ts +0 -3
  28. package/dist/cjs/rules/checkIndentation.d.ts +0 -2
  29. package/dist/cjs/rules/checkLineAlignment.d.ts +0 -9
  30. package/dist/cjs/rules/checkParamNames.d.ts +0 -2
  31. package/dist/cjs/rules/checkPropertyNames.d.ts +0 -2
  32. package/dist/cjs/rules/checkSyntax.d.ts +0 -2
  33. package/dist/cjs/rules/checkTagNames.d.ts +0 -2
  34. package/dist/cjs/rules/checkTemplateNames.d.ts +0 -2
  35. package/dist/cjs/rules/checkTypes.d.ts +0 -7
  36. package/dist/cjs/rules/checkValues.d.ts +0 -2
  37. package/dist/cjs/rules/convertToJsdocComments.d.ts +0 -266
  38. package/dist/cjs/rules/emptyTags.d.ts +0 -2
  39. package/dist/cjs/rules/escapeInlineTags.d.ts +0 -2
  40. package/dist/cjs/rules/implementsOnClasses.d.ts +0 -2
  41. package/dist/cjs/rules/importsAsDependencies.d.ts +0 -2
  42. package/dist/cjs/rules/informativeDocs.d.ts +0 -2
  43. package/dist/cjs/rules/linesBeforeBlock.d.ts +0 -2
  44. package/dist/cjs/rules/matchDescription.d.ts +0 -2
  45. package/dist/cjs/rules/matchName.d.ts +0 -2
  46. package/dist/cjs/rules/multilineBlocks.d.ts +0 -2
  47. package/dist/cjs/rules/noBadBlocks.d.ts +0 -2
  48. package/dist/cjs/rules/noBlankBlockDescriptions.d.ts +0 -2
  49. package/dist/cjs/rules/noBlankBlocks.d.ts +0 -2
  50. package/dist/cjs/rules/noDefaults.d.ts +0 -2
  51. package/dist/cjs/rules/noMissingSyntax.d.ts +0 -9
  52. package/dist/cjs/rules/noMultiAsterisks.d.ts +0 -2
  53. package/dist/cjs/rules/noRestrictedSyntax.d.ts +0 -2
  54. package/dist/cjs/rules/noTypes.d.ts +0 -2
  55. package/dist/cjs/rules/noUndefinedTypes.d.ts +0 -2
  56. package/dist/cjs/rules/normalizeSeeLinks.d.ts +0 -2
  57. package/dist/cjs/rules/preferImportTag.d.ts +0 -2
  58. package/dist/cjs/rules/requireAsteriskPrefix.d.ts +0 -2
  59. package/dist/cjs/rules/requireDescription.d.ts +0 -2
  60. package/dist/cjs/rules/requireDescriptionCompleteSentence.d.ts +0 -2
  61. package/dist/cjs/rules/requireExample.d.ts +0 -2
  62. package/dist/cjs/rules/requireFileOverview.d.ts +0 -2
  63. package/dist/cjs/rules/requireHyphenBeforeParamDescription.d.ts +0 -2
  64. package/dist/cjs/rules/requireJsdoc.d.ts +0 -24
  65. package/dist/cjs/rules/requireParam.d.ts +0 -3
  66. package/dist/cjs/rules/requireParamDescription.d.ts +0 -2
  67. package/dist/cjs/rules/requireParamName.d.ts +0 -2
  68. package/dist/cjs/rules/requireParamType.d.ts +0 -2
  69. package/dist/cjs/rules/requireProperty.d.ts +0 -2
  70. package/dist/cjs/rules/requirePropertyDescription.d.ts +0 -2
  71. package/dist/cjs/rules/requirePropertyName.d.ts +0 -2
  72. package/dist/cjs/rules/requirePropertyType.d.ts +0 -2
  73. package/dist/cjs/rules/requireRejects.d.ts +0 -2
  74. package/dist/cjs/rules/requireReturns.d.ts +0 -2
  75. package/dist/cjs/rules/requireReturnsCheck.d.ts +0 -2
  76. package/dist/cjs/rules/requireReturnsDescription.d.ts +0 -2
  77. package/dist/cjs/rules/requireReturnsType.d.ts +0 -2
  78. package/dist/cjs/rules/requireTags.d.ts +0 -2
  79. package/dist/cjs/rules/requireTemplate.d.ts +0 -2
  80. package/dist/cjs/rules/requireThrows.d.ts +0 -2
  81. package/dist/cjs/rules/requireYields.d.ts +0 -2
  82. package/dist/cjs/rules/requireYieldsCheck.d.ts +0 -2
  83. package/dist/cjs/rules/sortTags.d.ts +0 -2
  84. package/dist/cjs/rules/tagLines.d.ts +0 -2
  85. package/dist/cjs/rules/textEscaping.d.ts +0 -2
  86. package/dist/cjs/rules/tsMethodSignatureStyle.d.ts +0 -2
  87. package/dist/cjs/rules/tsNoEmptyObjectType.d.ts +0 -2
  88. package/dist/cjs/rules/tsNoUnnecessaryTemplateExpression.d.ts +0 -2
  89. package/dist/cjs/rules/tsPreferFunctionType.d.ts +0 -2
  90. package/dist/cjs/rules/typeFormatting.d.ts +0 -2
  91. package/dist/cjs/rules/validTypes.d.ts +0 -2
  92. package/dist/cjs/tagNames.d.ts +0 -15
  93. package/dist/cjs/utils/hasReturnValue.d.ts +0 -19
  94. package/dist/defaultTagOrder.cjs +0 -46
  95. package/dist/defaultTagOrder.cjs.map +0 -1
  96. package/dist/exportParser.cjs +0 -732
  97. package/dist/exportParser.cjs.map +0 -1
  98. package/dist/generateDocs.cjs +0 -342
  99. package/dist/generateDocs.cjs.map +0 -1
  100. package/dist/generateOptions.cjs +0 -62
  101. package/dist/generateOptions.cjs.map +0 -1
  102. package/dist/generateRule.cjs +0 -248
  103. package/dist/generateRule.cjs.map +0 -1
  104. package/dist/generateRuleTypes.cjs +0 -24
  105. package/dist/generateRuleTypes.cjs.map +0 -1
  106. package/dist/getDefaultTagStructureForMode.cjs +0 -289
  107. package/dist/getDefaultTagStructureForMode.cjs.map +0 -1
  108. package/dist/getJsdocProcessorPlugin.cjs +0 -587
  109. package/dist/getJsdocProcessorPlugin.cjs.map +0 -1
  110. package/dist/getJsdocProcessorPlugin.cts +0 -5
  111. package/dist/index-cjs.cjs +0 -600
  112. package/dist/index-cjs.cjs.map +0 -1
  113. package/dist/index-cjs.d.ts +0 -27
  114. package/dist/index-esm.cjs +0 -162
  115. package/dist/index-esm.cjs.map +0 -1
  116. package/dist/index-esm.d.ts +0 -72
  117. package/dist/index.cjs +0 -748
  118. package/dist/index.cjs.cts +0 -3
  119. package/dist/index.cjs.map +0 -1
  120. package/dist/iterateJsdoc.cjs +0 -2150
  121. package/dist/iterateJsdoc.cjs.map +0 -1
  122. package/dist/iterateJsdoc.cts +0 -7
  123. package/dist/jsdocUtils.cjs +0 -1786
  124. package/dist/jsdocUtils.cjs.map +0 -1
  125. package/dist/rules/checkAccess.cjs +0 -40
  126. package/dist/rules/checkAccess.cjs.map +0 -1
  127. package/dist/rules/checkAlignment.cjs +0 -78
  128. package/dist/rules/checkAlignment.cjs.map +0 -1
  129. package/dist/rules/checkExamples.cjs +0 -521
  130. package/dist/rules/checkExamples.cjs.map +0 -1
  131. package/dist/rules/checkIndentation.cjs +0 -170
  132. package/dist/rules/checkIndentation.cjs.map +0 -1
  133. package/dist/rules/checkLineAlignment.cjs +0 -398
  134. package/dist/rules/checkLineAlignment.cjs.map +0 -1
  135. package/dist/rules/checkParamNames.cjs +0 -407
  136. package/dist/rules/checkParamNames.cjs.map +0 -1
  137. package/dist/rules/checkPropertyNames.cjs +0 -135
  138. package/dist/rules/checkPropertyNames.cjs.map +0 -1
  139. package/dist/rules/checkSyntax.cjs +0 -38
  140. package/dist/rules/checkSyntax.cjs.map +0 -1
  141. package/dist/rules/checkTagNames.cjs +0 -312
  142. package/dist/rules/checkTagNames.cjs.map +0 -1
  143. package/dist/rules/checkTemplateNames.cjs +0 -192
  144. package/dist/rules/checkTemplateNames.cjs.map +0 -1
  145. package/dist/rules/checkTypes.cjs +0 -111
  146. package/dist/rules/checkTypes.cjs.map +0 -1
  147. package/dist/rules/checkValues.cjs +0 -166
  148. package/dist/rules/checkValues.cjs.map +0 -1
  149. package/dist/rules/convertToJsdocComments.cjs +0 -356
  150. package/dist/rules/convertToJsdocComments.cjs.map +0 -1
  151. package/dist/rules/emptyTags.cjs +0 -98
  152. package/dist/rules/emptyTags.cjs.map +0 -1
  153. package/dist/rules/escapeInlineTags.cjs +0 -234
  154. package/dist/rules/escapeInlineTags.cjs.map +0 -1
  155. package/dist/rules/implementsOnClasses.cjs +0 -74
  156. package/dist/rules/implementsOnClasses.cjs.map +0 -1
  157. package/dist/rules/importsAsDependencies.cjs +0 -104
  158. package/dist/rules/importsAsDependencies.cjs.map +0 -1
  159. package/dist/rules/informativeDocs.cjs +0 -187
  160. package/dist/rules/informativeDocs.cjs.map +0 -1
  161. package/dist/rules/linesBeforeBlock.cjs +0 -120
  162. package/dist/rules/linesBeforeBlock.cjs.map +0 -1
  163. package/dist/rules/matchDescription.cjs +0 -356
  164. package/dist/rules/matchDescription.cjs.map +0 -1
  165. package/dist/rules/matchName.cjs +0 -160
  166. package/dist/rules/matchName.cjs.map +0 -1
  167. package/dist/rules/multilineBlocks.cjs +0 -431
  168. package/dist/rules/multilineBlocks.cjs.map +0 -1
  169. package/dist/rules/noBadBlocks.cjs +0 -100
  170. package/dist/rules/noBadBlocks.cjs.map +0 -1
  171. package/dist/rules/noBlankBlockDescriptions.cjs +0 -63
  172. package/dist/rules/noBlankBlockDescriptions.cjs.map +0 -1
  173. package/dist/rules/noBlankBlocks.cjs +0 -54
  174. package/dist/rules/noBlankBlocks.cjs.map +0 -1
  175. package/dist/rules/noDefaults.cjs +0 -102
  176. package/dist/rules/noDefaults.cjs.map +0 -1
  177. package/dist/rules/noMissingSyntax.cjs +0 -196
  178. package/dist/rules/noMissingSyntax.cjs.map +0 -1
  179. package/dist/rules/noMultiAsterisks.cjs +0 -126
  180. package/dist/rules/noMultiAsterisks.cjs.map +0 -1
  181. package/dist/rules/noRestrictedSyntax.cjs +0 -68
  182. package/dist/rules/noRestrictedSyntax.cjs.map +0 -1
  183. package/dist/rules/noTypes.cjs +0 -101
  184. package/dist/rules/noTypes.cjs.map +0 -1
  185. package/dist/rules/noUndefinedTypes.cjs +0 -616
  186. package/dist/rules/noUndefinedTypes.cjs.map +0 -1
  187. package/dist/rules/normalizeSeeLinks.cjs +0 -271
  188. package/dist/rules/normalizeSeeLinks.cjs.map +0 -1
  189. package/dist/rules/preferImportTag.cjs +0 -362
  190. package/dist/rules/preferImportTag.cjs.map +0 -1
  191. package/dist/rules/requireAsteriskPrefix.cjs +0 -190
  192. package/dist/rules/requireAsteriskPrefix.cjs.map +0 -1
  193. package/dist/rules/requireDescription.cjs +0 -164
  194. package/dist/rules/requireDescription.cjs.map +0 -1
  195. package/dist/rules/requireDescriptionCompleteSentence.cjs +0 -321
  196. package/dist/rules/requireDescriptionCompleteSentence.cjs.map +0 -1
  197. package/dist/rules/requireExample.cjs +0 -136
  198. package/dist/rules/requireExample.cjs.map +0 -1
  199. package/dist/rules/requireFileOverview.cjs +0 -194
  200. package/dist/rules/requireFileOverview.cjs.map +0 -1
  201. package/dist/rules/requireHyphenBeforeParamDescription.cjs +0 -166
  202. package/dist/rules/requireHyphenBeforeParamDescription.cjs.map +0 -1
  203. package/dist/rules/requireJsdoc.cjs +0 -721
  204. package/dist/rules/requireJsdoc.cjs.map +0 -1
  205. package/dist/rules/requireParam.cjs +0 -772
  206. package/dist/rules/requireParam.cjs.map +0 -1
  207. package/dist/rules/requireParamDescription.cjs +0 -105
  208. package/dist/rules/requireParamDescription.cjs.map +0 -1
  209. package/dist/rules/requireParamName.cjs +0 -68
  210. package/dist/rules/requireParamName.cjs.map +0 -1
  211. package/dist/rules/requireParamType.cjs +0 -104
  212. package/dist/rules/requireParamType.cjs.map +0 -1
  213. package/dist/rules/requireProperty.cjs +0 -63
  214. package/dist/rules/requireProperty.cjs.map +0 -1
  215. package/dist/rules/requirePropertyDescription.cjs +0 -29
  216. package/dist/rules/requirePropertyDescription.cjs.map +0 -1
  217. package/dist/rules/requirePropertyName.cjs +0 -29
  218. package/dist/rules/requirePropertyName.cjs.map +0 -1
  219. package/dist/rules/requirePropertyType.cjs +0 -29
  220. package/dist/rules/requirePropertyType.cjs.map +0 -1
  221. package/dist/rules/requireRejects.cjs +0 -226
  222. package/dist/rules/requireRejects.cjs.map +0 -1
  223. package/dist/rules/requireReturns.cjs +0 -262
  224. package/dist/rules/requireReturns.cjs.map +0 -1
  225. package/dist/rules/requireReturnsCheck.cjs +0 -225
  226. package/dist/rules/requireReturnsCheck.cjs.map +0 -1
  227. package/dist/rules/requireReturnsDescription.cjs +0 -72
  228. package/dist/rules/requireReturnsDescription.cjs.map +0 -1
  229. package/dist/rules/requireReturnsType.cjs +0 -68
  230. package/dist/rules/requireReturnsType.cjs.map +0 -1
  231. package/dist/rules/requireTags.cjs +0 -74
  232. package/dist/rules/requireTags.cjs.map +0 -1
  233. package/dist/rules/requireTemplate.cjs +0 -220
  234. package/dist/rules/requireTemplate.cjs.map +0 -1
  235. package/dist/rules/requireThrows.cjs +0 -118
  236. package/dist/rules/requireThrows.cjs.map +0 -1
  237. package/dist/rules/requireYields.cjs +0 -224
  238. package/dist/rules/requireYields.cjs.map +0 -1
  239. package/dist/rules/requireYieldsCheck.cjs +0 -179
  240. package/dist/rules/requireYieldsCheck.cjs.map +0 -1
  241. package/dist/rules/sortTags.cjs +0 -656
  242. package/dist/rules/sortTags.cjs.map +0 -1
  243. package/dist/rules/tagLines.cjs +0 -374
  244. package/dist/rules/tagLines.cjs.map +0 -1
  245. package/dist/rules/textEscaping.cjs +0 -141
  246. package/dist/rules/textEscaping.cjs.map +0 -1
  247. package/dist/rules/tsMethodSignatureStyle.cjs +0 -240
  248. package/dist/rules/tsMethodSignatureStyle.cjs.map +0 -1
  249. package/dist/rules/tsNoEmptyObjectType.cjs +0 -62
  250. package/dist/rules/tsNoEmptyObjectType.cjs.map +0 -1
  251. package/dist/rules/tsNoUnnecessaryTemplateExpression.cjs +0 -104
  252. package/dist/rules/tsNoUnnecessaryTemplateExpression.cjs.map +0 -1
  253. package/dist/rules/tsPreferFunctionType.cjs +0 -110
  254. package/dist/rules/tsPreferFunctionType.cjs.map +0 -1
  255. package/dist/rules/typeFormatting.cjs +0 -607
  256. package/dist/rules/typeFormatting.cjs.map +0 -1
  257. package/dist/rules/validTypes.cjs +0 -324
  258. package/dist/rules/validTypes.cjs.map +0 -1
  259. package/dist/tagNames.cjs +0 -244
  260. package/dist/tagNames.cjs.map +0 -1
  261. package/dist/to-valid-identifier.cjs +0 -263
  262. package/dist/utils/hasReturnValue.cjs +0 -495
  263. package/dist/utils/hasReturnValue.cjs.map +0 -1
  264. package/rollup.config.js +0 -16
  265. package/src/getJsdocProcessorPlugin.cts +0 -5
  266. package/src/index-cjs.js +0 -760
  267. package/src/index-esm.js +0 -196
  268. package/src/index.cjs.cts +0 -3
  269. package/src/iterateJsdoc.cts +0 -7
@@ -1,136 +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
- context,
11
- jsdoc,
12
- report,
13
- utils
14
- }) => {
15
- if (utils.avoidDocs()) {
16
- return;
17
- }
18
- const {
19
- enableFixer = true,
20
- exemptNoArguments = false
21
- } = context.options[0] || {};
22
- const targetTagName = 'example';
23
- const functionExamples = jsdoc.tags.filter(({
24
- tag
25
- }) => {
26
- return tag === targetTagName;
27
- });
28
- if (!functionExamples.length) {
29
- if (exemptNoArguments && utils.isIteratingFunctionOrVariable() && !utils.hasParams()) {
30
- return;
31
- }
32
- utils.reportJSDoc(`Missing JSDoc @${targetTagName} declaration.`, null, () => {
33
- if (enableFixer) {
34
- if (jsdoc.source.length === 1) {
35
- utils.makeMultiline();
36
- }
37
- utils.addTag(targetTagName);
38
- }
39
- });
40
- return;
41
- }
42
- for (const example of functionExamples) {
43
- const exampleContent = `${example.name} ${utils.getTagDescription(example)}`.trim().split('\n').filter(Boolean);
44
- if (!exampleContent.length) {
45
- report(`Missing JSDoc @${targetTagName} description.`, null, example);
46
- }
47
- }
48
- }, {
49
- contextDefaults: true,
50
- meta: {
51
- docs: {
52
- description: 'Requires that all functions (and potentially other contexts) have examples.',
53
- url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-example.md#repos-sticky-header'
54
- },
55
- fixable: 'code',
56
- schema: [{
57
- additionalProperties: false,
58
- properties: {
59
- checkConstructors: {
60
- default: true,
61
- description: `A value indicating whether \`constructor\`s should be checked.
62
- Defaults to \`true\`.`,
63
- type: 'boolean'
64
- },
65
- checkGetters: {
66
- default: false,
67
- description: 'A value indicating whether getters should be checked. Defaults to `false`.',
68
- type: 'boolean'
69
- },
70
- checkSetters: {
71
- default: false,
72
- description: 'A value indicating whether setters should be checked. Defaults to `false`.',
73
- type: 'boolean'
74
- },
75
- contexts: {
76
- description: `Set this to an array of strings representing the AST context (or an object with
77
- optional \`context\` and \`comment\` properties) where you wish the rule to be applied.
78
- (e.g., \`ClassDeclaration\` for ES6 classes).
79
-
80
- \`context\` defaults to \`any\` and \`comment\` defaults to no specific comment context.
81
-
82
- Overrides the default contexts (\`ArrowFunctionExpression\`, \`FunctionDeclaration\`,
83
- \`FunctionExpression\`). Set to \`"any"\` if you want the rule to apply to any
84
- JSDoc block throughout your files.
85
-
86
- See the ["AST and Selectors"](../advanced.md#ast-and-selectors)
87
- section of our Advanced docs for more on the expected format.`,
88
- items: {
89
- anyOf: [{
90
- type: 'string'
91
- }, {
92
- additionalProperties: false,
93
- properties: {
94
- comment: {
95
- type: 'string'
96
- },
97
- context: {
98
- type: 'string'
99
- }
100
- },
101
- type: 'object'
102
- }]
103
- },
104
- type: 'array'
105
- },
106
- enableFixer: {
107
- default: true,
108
- description: `A boolean on whether to enable the fixer (which adds an empty \`@example\` block).
109
- Defaults to \`true\`.`,
110
- type: 'boolean'
111
- },
112
- exemptedBy: {
113
- description: `Array of tags (e.g., \`['type']\`) whose presence on the document
114
- block avoids the need for an \`@example\`. Defaults to an array with
115
- \`inheritdoc\`. If you set this array, it will overwrite the default,
116
- so be sure to add back \`inheritdoc\` if you wish its presence to cause
117
- exemption of the rule.`,
118
- items: {
119
- type: 'string'
120
- },
121
- type: 'array'
122
- },
123
- exemptNoArguments: {
124
- default: false,
125
- description: `Boolean to indicate that no-argument functions should not be reported for
126
- missing \`@example\` declarations.`,
127
- type: 'boolean'
128
- }
129
- },
130
- type: 'object'
131
- }],
132
- type: 'suggestion'
133
- }
134
- });
135
- module.exports = exports.default;
136
- //# sourceMappingURL=requireExample.cjs.map
@@ -1 +0,0 @@
1
- {"version":3,"file":"requireExample.cjs","names":["iterateJsdoc"],"sources":["../../src/rules/requireExample.js"],"sourcesContent":["import iterateJsdoc from '../iterateJsdoc.js';\n\nexport default iterateJsdoc(({\n context,\n jsdoc,\n report,\n utils,\n}) => {\n if (utils.avoidDocs()) {\n return;\n }\n\n const {\n enableFixer = true,\n exemptNoArguments = false,\n } = context.options[0] || {};\n\n const targetTagName = 'example';\n\n const functionExamples = jsdoc.tags.filter(({\n tag,\n }) => {\n return tag === targetTagName;\n });\n\n if (!functionExamples.length) {\n if (exemptNoArguments && utils.isIteratingFunctionOrVariable() &&\n !utils.hasParams()\n ) {\n return;\n }\n\n utils.reportJSDoc(`Missing JSDoc @${targetTagName} declaration.`, null, () => {\n if (enableFixer) {\n if (jsdoc.source.length === 1) {\n utils.makeMultiline();\n }\n\n utils.addTag(targetTagName);\n }\n });\n\n return;\n }\n\n for (const example of functionExamples) {\n const exampleContent = `${example.name} ${utils.getTagDescription(example)}`\n .trim()\n .split('\\n')\n .filter(Boolean);\n\n if (!exampleContent.length) {\n report(`Missing JSDoc @${targetTagName} description.`, null, example);\n }\n }\n}, {\n contextDefaults: true,\n meta: {\n docs: {\n description: 'Requires that all functions (and potentially other contexts) have examples.',\n url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-example.md#repos-sticky-header',\n },\n fixable: 'code',\n schema: [\n {\n additionalProperties: false,\n properties: {\n checkConstructors: {\n default: true,\n description: `A value indicating whether \\`constructor\\`s should be checked.\nDefaults to \\`true\\`.`,\n type: 'boolean',\n },\n checkGetters: {\n default: false,\n description: 'A value indicating whether getters should be checked. Defaults to `false`.',\n type: 'boolean',\n },\n checkSetters: {\n default: false,\n description: 'A value indicating whether setters should be checked. Defaults to `false`.',\n type: 'boolean',\n },\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(e.g., \\`ClassDeclaration\\` for ES6 classes).\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 the rule to apply to any\nJSDoc block throughout your files.\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 enableFixer: {\n default: true,\n description: `A boolean on whether to enable the fixer (which adds an empty \\`@example\\` block).\nDefaults to \\`true\\`.`,\n type: 'boolean',\n },\n exemptedBy: {\n description: `Array of tags (e.g., \\`['type']\\`) whose presence on the document\nblock avoids the need for an \\`@example\\`. Defaults to an array with\n\\`inheritdoc\\`. If you set this array, it will overwrite the default,\nso be sure to add back \\`inheritdoc\\` if you wish its presence to cause\nexemption of the rule.`,\n items: {\n type: 'string',\n },\n type: 'array',\n },\n exemptNoArguments: {\n default: false,\n description: `Boolean to indicate that no-argument functions should not be reported for\nmissing \\`@example\\` declarations.`,\n type: 'boolean',\n },\n },\n type: 'object',\n },\n ],\n type: 'suggestion',\n },\n});\n"],"mappings":"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","ignoreList":[]}
@@ -1,194 +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
- const defaultTags = {
10
- file: {
11
- initialCommentsOnly: true,
12
- mustExist: true,
13
- preventDuplicates: true
14
- }
15
- };
16
-
17
- /**
18
- * @param {import('../iterateJsdoc.js').StateObject} state
19
- * @returns {void}
20
- */
21
- const setDefaults = state => {
22
- // First iteration
23
- if (!state.globalTags) {
24
- state.globalTags = true;
25
- state.hasDuplicates = {};
26
- state.hasTag = {};
27
- state.hasNonCommentBeforeTag = {};
28
- }
29
- };
30
- var _default = exports.default = (0, _iterateJsdoc.default)(({
31
- context,
32
- jsdocNode,
33
- state,
34
- utils
35
- }) => {
36
- const {
37
- tags = defaultTags
38
- } = context.options[0] || {};
39
- setDefaults(state);
40
- for (const tagName of Object.keys(tags)) {
41
- const targetTagName = /** @type {string} */utils.getPreferredTagName({
42
- tagName
43
- });
44
- const hasTag = Boolean(targetTagName && utils.hasTag(targetTagName));
45
- state.hasTag[tagName] = hasTag || state.hasTag[tagName];
46
- const hasDuplicate = state.hasDuplicates[tagName];
47
- if (hasDuplicate === false) {
48
- // Was marked before, so if a tag now, is a dupe
49
- state.hasDuplicates[tagName] = hasTag;
50
- } else if (!hasDuplicate && hasTag) {
51
- // No dupes set before, but has first tag, so change state
52
- // from `undefined` to `false` so can detect next time
53
- state.hasDuplicates[tagName] = false;
54
- state.hasNonCommentBeforeTag[tagName] = state.hasNonComment && state.hasNonComment < jsdocNode.range[0];
55
- }
56
- }
57
- }, {
58
- exit({
59
- context,
60
- state,
61
- utils
62
- }) {
63
- setDefaults(state);
64
- const {
65
- tags = defaultTags
66
- } = context.options[0] || {};
67
- for (const [tagName, {
68
- initialCommentsOnly = false,
69
- mustExist = false,
70
- preventDuplicates = false
71
- }] of Object.entries(tags)) {
72
- const obj = utils.getPreferredTagNameObject({
73
- tagName
74
- });
75
- if (obj && typeof obj === 'object' && 'blocked' in obj) {
76
- utils.reportSettings(`\`settings.jsdoc.tagNamePreference\` cannot block @${obj.tagName} ` + 'for the `require-file-overview` rule');
77
- } else {
78
- const targetTagName = obj && typeof obj === 'object' && obj.replacement || obj;
79
- if (mustExist && !state.hasTag[tagName]) {
80
- utils.reportSettings(`Missing @${targetTagName}`);
81
- }
82
- if (preventDuplicates && state.hasDuplicates[tagName]) {
83
- utils.reportSettings(`Duplicate @${targetTagName}`);
84
- }
85
- if (initialCommentsOnly && state.hasNonCommentBeforeTag[tagName]) {
86
- utils.reportSettings(`@${targetTagName} should be at the beginning of the file`);
87
- }
88
- }
89
- }
90
- },
91
- iterateAllJsdocs: true,
92
- meta: {
93
- docs: {
94
- description: 'Checks that all files have one `@file`, `@fileoverview`, or `@overview` tag at the beginning of the file.',
95
- url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-file-overview.md#repos-sticky-header'
96
- },
97
- schema: [{
98
- additionalProperties: false,
99
- properties: {
100
- tags: {
101
- description: `The keys of this object are tag names, and the values are configuration
102
- objects indicating what will be checked for these whole-file tags.
103
-
104
- Each configuration object has 3 potential boolean keys (which default
105
- to \`false\` when this option is supplied).
106
-
107
- 1. \`mustExist\` - enforces that all files have a \`@file\`, \`@fileoverview\`, or \`@overview\` tag.
108
- 2. \`preventDuplicates\` - enforces that duplicate file overview tags within a given file will be reported
109
- 3. \`initialCommentsOnly\` - reports file overview tags which are not, as per
110
- [the docs](https://jsdoc.app/tags-file.html), "at the beginning of
111
- the file"–where beginning of the file is interpreted in this rule
112
- as being when the overview tag is not preceded by anything other than
113
- a comment.
114
-
115
- When no \`tags\` is present, the default is:
116
-
117
- \`\`\`json
118
- {
119
- "file": {
120
- "initialCommentsOnly": true,
121
- "mustExist": true,
122
- "preventDuplicates": true,
123
- }
124
- }
125
- \`\`\`
126
-
127
- You can add additional tag names and/or override \`file\` if you supply this
128
- option, e.g., in place of or in addition to \`file\`, giving other potential
129
- file global tags like \`@license\`, \`@copyright\`, \`@author\`, \`@module\` or
130
- \`@exports\`, optionally restricting them to a single use or preventing them
131
- from being preceded by anything besides comments.
132
-
133
- For example:
134
-
135
- \`\`\`js
136
- {
137
- "license": {
138
- "mustExist": true,
139
- "preventDuplicates": true,
140
- }
141
- }
142
- \`\`\`
143
-
144
- This would require one and only one \`@license\` in the file, though because
145
- \`initialCommentsOnly\` is absent and defaults to \`false\`, the \`@license\`
146
- can be anywhere.
147
-
148
- In the case of \`@license\`, you can use this rule along with the
149
- \`check-values\` rule (with its \`allowedLicenses\` or \`licensePattern\` options),
150
- to enforce a license whitelist be present on every JS file.
151
-
152
- Note that if you choose to use \`preventDuplicates\` with \`license\`, you still
153
- have a way to allow multiple licenses for the whole page by using the SPDX
154
- "AND" expression, e.g., \`@license (MIT AND GPL-3.0)\`.
155
-
156
- Note that the tag names are the main JSDoc tag name, so you should use \`file\`
157
- in this configuration object regardless of whether you have configured
158
- \`fileoverview\` instead of \`file\` on \`tagNamePreference\` (i.e., \`fileoverview\`
159
- will be checked, but you must use \`file\` on the configuration object).`,
160
- patternProperties: {
161
- '.*': {
162
- additionalProperties: false,
163
- properties: {
164
- initialCommentsOnly: {
165
- type: 'boolean'
166
- },
167
- mustExist: {
168
- type: 'boolean'
169
- },
170
- preventDuplicates: {
171
- type: 'boolean'
172
- }
173
- },
174
- type: 'object'
175
- }
176
- },
177
- type: 'object'
178
- }
179
- },
180
- type: 'object'
181
- }],
182
- type: 'suggestion'
183
- },
184
- nonComment({
185
- node,
186
- state
187
- }) {
188
- if (!state.hasNonComment) {
189
- state.hasNonComment = /** @type {[number, number]} */node.range?.[0];
190
- }
191
- }
192
- });
193
- module.exports = exports.default;
194
- //# sourceMappingURL=requireFileOverview.cjs.map
@@ -1 +0,0 @@
1
- {"version":3,"file":"requireFileOverview.cjs","names":["iterateJsdoc"],"sources":["../../src/rules/requireFileOverview.js"],"sourcesContent":["import iterateJsdoc from '../iterateJsdoc.js';\n\nconst defaultTags = {\n file: {\n initialCommentsOnly: true,\n mustExist: true,\n preventDuplicates: true,\n },\n};\n\n/**\n * @param {import('../iterateJsdoc.js').StateObject} state\n * @returns {void}\n */\nconst setDefaults = (state) => {\n // First iteration\n if (!state.globalTags) {\n state.globalTags = true;\n state.hasDuplicates = {};\n state.hasTag = {};\n state.hasNonCommentBeforeTag = {};\n }\n};\n\nexport default iterateJsdoc(({\n context,\n jsdocNode,\n state,\n utils,\n}) => {\n const {\n tags = defaultTags,\n } = context.options[0] || {};\n\n setDefaults(state);\n\n for (const tagName of Object.keys(tags)) {\n const targetTagName = /** @type {string} */ (utils.getPreferredTagName({\n tagName,\n }));\n\n const hasTag = Boolean(targetTagName && utils.hasTag(targetTagName));\n\n state.hasTag[tagName] = hasTag || state.hasTag[tagName];\n\n const hasDuplicate = state.hasDuplicates[tagName];\n\n if (hasDuplicate === false) {\n // Was marked before, so if a tag now, is a dupe\n state.hasDuplicates[tagName] = hasTag;\n } else if (!hasDuplicate && hasTag) {\n // No dupes set before, but has first tag, so change state\n // from `undefined` to `false` so can detect next time\n state.hasDuplicates[tagName] = false;\n state.hasNonCommentBeforeTag[tagName] = state.hasNonComment &&\n state.hasNonComment < jsdocNode.range[0];\n }\n }\n}, {\n exit ({\n context,\n state,\n utils,\n }) {\n setDefaults(state);\n const {\n tags = defaultTags,\n } = context.options[0] || {};\n\n for (const [\n tagName,\n {\n initialCommentsOnly = false,\n mustExist = false,\n preventDuplicates = false,\n },\n ] of Object.entries(tags)) {\n const obj = utils.getPreferredTagNameObject({\n tagName,\n });\n if (obj && typeof obj === 'object' && 'blocked' in obj) {\n utils.reportSettings(\n `\\`settings.jsdoc.tagNamePreference\\` cannot block @${obj.tagName} ` +\n 'for the `require-file-overview` rule',\n );\n } else {\n const targetTagName = (\n obj && typeof obj === 'object' && obj.replacement\n ) || obj;\n if (mustExist && !state.hasTag[tagName]) {\n utils.reportSettings(`Missing @${targetTagName}`);\n }\n\n if (preventDuplicates && state.hasDuplicates[tagName]) {\n utils.reportSettings(\n `Duplicate @${targetTagName}`,\n );\n }\n\n if (initialCommentsOnly &&\n state.hasNonCommentBeforeTag[tagName]\n ) {\n utils.reportSettings(\n `@${targetTagName} should be at the beginning of the file`,\n );\n }\n }\n }\n },\n iterateAllJsdocs: true,\n meta: {\n docs: {\n description: 'Checks that all files have one `@file`, `@fileoverview`, or `@overview` tag at the beginning of the file.',\n url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-file-overview.md#repos-sticky-header',\n },\n schema: [\n {\n additionalProperties: false,\n properties: {\n tags: {\n description: `The keys of this object are tag names, and the values are configuration\nobjects indicating what will be checked for these whole-file tags.\n\nEach configuration object has 3 potential boolean keys (which default\nto \\`false\\` when this option is supplied).\n\n1. \\`mustExist\\` - enforces that all files have a \\`@file\\`, \\`@fileoverview\\`, or \\`@overview\\` tag.\n2. \\`preventDuplicates\\` - enforces that duplicate file overview tags within a given file will be reported\n3. \\`initialCommentsOnly\\` - reports file overview tags which are not, as per\n [the docs](https://jsdoc.app/tags-file.html), \"at the beginning of\n the file\"–where beginning of the file is interpreted in this rule\n as being when the overview tag is not preceded by anything other than\n a comment.\n\nWhen no \\`tags\\` is present, the default is:\n\n\\`\\`\\`json\n{\n \"file\": {\n \"initialCommentsOnly\": true,\n \"mustExist\": true,\n \"preventDuplicates\": true,\n }\n}\n\\`\\`\\`\n\nYou can add additional tag names and/or override \\`file\\` if you supply this\noption, e.g., in place of or in addition to \\`file\\`, giving other potential\nfile global tags like \\`@license\\`, \\`@copyright\\`, \\`@author\\`, \\`@module\\` or\n\\`@exports\\`, optionally restricting them to a single use or preventing them\nfrom being preceded by anything besides comments.\n\nFor example:\n\n\\`\\`\\`js\n{\n \"license\": {\n \"mustExist\": true,\n \"preventDuplicates\": true,\n }\n}\n\\`\\`\\`\n\nThis would require one and only one \\`@license\\` in the file, though because\n\\`initialCommentsOnly\\` is absent and defaults to \\`false\\`, the \\`@license\\`\ncan be anywhere.\n\nIn the case of \\`@license\\`, you can use this rule along with the\n\\`check-values\\` rule (with its \\`allowedLicenses\\` or \\`licensePattern\\` options),\nto enforce a license whitelist be present on every JS file.\n\nNote that if you choose to use \\`preventDuplicates\\` with \\`license\\`, you still\nhave a way to allow multiple licenses for the whole page by using the SPDX\n\"AND\" expression, e.g., \\`@license (MIT AND GPL-3.0)\\`.\n\nNote that the tag names are the main JSDoc tag name, so you should use \\`file\\`\nin this configuration object regardless of whether you have configured\n\\`fileoverview\\` instead of \\`file\\` on \\`tagNamePreference\\` (i.e., \\`fileoverview\\`\nwill be checked, but you must use \\`file\\` on the configuration object).`,\n patternProperties: {\n '.*': {\n additionalProperties: false,\n properties: {\n initialCommentsOnly: {\n type: 'boolean',\n },\n mustExist: {\n type: 'boolean',\n },\n preventDuplicates: {\n type: 'boolean',\n },\n },\n type: 'object',\n },\n },\n type: 'object',\n },\n },\n type: 'object',\n },\n ],\n type: 'suggestion',\n },\n nonComment ({\n node,\n state,\n }) {\n if (!state.hasNonComment) {\n state.hasNonComment = /** @type {[number, number]} */ (node.range)?.[0];\n }\n },\n});\n"],"mappings":"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ACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,yEAAyE;UAC7D,iBAAiB,EAAE;YACjB,IAAI,EAAE;cACJ,oBAAoB,EAAE,KAAK;cAC3B,UAAU,EAAE;gBACV,mBAAmB,EAAE;kBACnB,IAAI,EAAE;gBACR,CAAC;gBACD,SAAS,EAAE;kBACT,IAAI,EAAE;gBACR,CAAC;gBACD,iBAAiB,EAAE;kBACjB,IAAI,EAAE;gBACR;cACF,CAAC;cACD,IAAI,EAAE;YACR;UACF,CAAC;UACD,IAAI,EAAE;QACR;MACF,CAAC;MACD,IAAI,EAAE;IACR,CAAC,CACF;IACD,IAAI,EAAE;EACR,CAAC;EACD,UAAU,CAAE;IACV,IAAI;IACJ;EACF,CAAC,EAAE;IACD,IAAI,CAAC,KAAK,CAAC,aAAa,EAAE;MACxB,KAAK,CAAC,aAAa,GAAG,+BAAiC,IAAI,CAAC,KAAK,GAAI,CAAC,CAAC;IACzE;EACF;AACF,CAAC,CAAC;AAAA","ignoreList":[]}
@@ -1,166 +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
- context,
11
- jsdoc,
12
- utils
13
- }) => {
14
- const [mainCircumstance, {
15
- tags = null
16
- } = {}] = context.options;
17
- const tgs =
18
- /**
19
- * @type {null|"any"|{[key: string]: "always"|"never"}}
20
- */
21
- tags;
22
-
23
- /**
24
- * @param {import('@es-joy/jsdoccomment').JsdocTagWithInline} jsdocTag
25
- * @param {string} targetTagName
26
- * @param {"always"|"never"} [circumstance]
27
- * @returns {void}
28
- */
29
- const checkHyphens = (jsdocTag, targetTagName, circumstance = mainCircumstance) => {
30
- const always = !circumstance || circumstance === 'always';
31
- const desc = /** @type {string} */utils.getTagDescription(jsdocTag);
32
- if (!desc.trim()) {
33
- return;
34
- }
35
- const startsWithHyphen = /^\s*-/v.test(desc);
36
- const hyphenNewline = /^\s*-\n/v.test(desc);
37
- let lines = 0;
38
- for (const {
39
- tokens
40
- } of jsdocTag.source) {
41
- if (tokens.description) {
42
- break;
43
- }
44
- lines++;
45
- }
46
- if (always && !hyphenNewline) {
47
- if (!startsWithHyphen) {
48
- let fixIt = true;
49
- for (const {
50
- tokens
51
- } of jsdocTag.source) {
52
- if (tokens.description) {
53
- tokens.description = tokens.description.replace(/^(\s*)/v, '$1- ');
54
- break;
55
- }
56
-
57
- // Linebreak after name since has no description
58
- if (tokens.name) {
59
- fixIt = false;
60
- break;
61
- }
62
- }
63
- if (fixIt) {
64
- utils.reportJSDoc(`There must be a hyphen before @${targetTagName} description.`, {
65
- line: jsdocTag.source[0].number + lines
66
- }, () => {});
67
- }
68
- }
69
- } else if (startsWithHyphen) {
70
- utils.reportJSDoc(always ? `There must be no hyphen followed by newline after the @${targetTagName} name.` : `There must be no hyphen before @${targetTagName} description.`, {
71
- line: jsdocTag.source[0].number + lines
72
- }, () => {
73
- for (const {
74
- tokens
75
- } of jsdocTag.source) {
76
- if (tokens.description) {
77
- tokens.description = tokens.description.replace(/^\s*-\s*/v, '');
78
- if (hyphenNewline) {
79
- tokens.postName = '';
80
- }
81
- break;
82
- }
83
- }
84
- }, true);
85
- }
86
- };
87
- utils.forEachPreferredTag('param', checkHyphens);
88
- if (tgs) {
89
- const tagEntries = Object.entries(tgs);
90
- for (const [tagName, circumstance] of tagEntries) {
91
- if (tagName === '*') {
92
- const preferredParamTag = utils.getPreferredTagName({
93
- tagName: 'param'
94
- });
95
- for (const {
96
- tag
97
- } of jsdoc.tags) {
98
- if (tag === preferredParamTag || tagEntries.some(([tagNme]) => {
99
- return tagNme !== '*' && tagNme === tag;
100
- })) {
101
- continue;
102
- }
103
- utils.forEachPreferredTag(tag, (jsdocTag, targetTagName) => {
104
- checkHyphens(jsdocTag, targetTagName, /** @type {"always"|"never"} */circumstance);
105
- });
106
- }
107
- continue;
108
- }
109
- utils.forEachPreferredTag(tagName, (jsdocTag, targetTagName) => {
110
- checkHyphens(jsdocTag, targetTagName, /** @type {"always"|"never"} */circumstance);
111
- });
112
- }
113
- }
114
- }, {
115
- iterateAllJsdocs: true,
116
- meta: {
117
- docs: {
118
- description: 'Requires a hyphen before the `@param` description (and optionally before `@property` descriptions).',
119
- url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-hyphen-before-param-description.md#repos-sticky-header'
120
- },
121
- fixable: 'code',
122
- schema: [{
123
- description: `If the string is \`"always"\` then a problem is raised when there is no hyphen
124
- before the description. If it is \`"never"\` then a problem is raised when there
125
- is a hyphen before the description. The default value is \`"always"\`.
126
-
127
- Even if hyphens are set to "always" appear after the tag name, they will
128
- actually be forbidden in the event that they are followed immediately by
129
- the end of a line (this will otherwise cause Visual Studio Code to display
130
- incorrectly).`,
131
- enum: ['always', 'never'],
132
- type: 'string'
133
- }, {
134
- additionalProperties: false,
135
- description: `The options object may have the following property to indicate behavior for
136
- other tags besides the \`@param\` tag (or the \`@arg\` tag if so set).`,
137
- properties: {
138
- tags: {
139
- anyOf: [{
140
- patternProperties: {
141
- '.*': {
142
- enum: ['always', 'never'],
143
- type: 'string'
144
- }
145
- },
146
- type: 'object'
147
- }, {
148
- enum: ['any'],
149
- type: 'string'
150
- }],
151
- description: `Object whose keys indicate different tags to check for the
152
- presence or absence of hyphens; the key value should be "always" or "never",
153
- indicating how hyphens are to be applied, e.g., \`{property: 'never'}\`
154
- to ensure \`@property\` never uses hyphens. A key can also be set as \`*\`, e.g.,
155
- \`'*': 'always'\` to apply hyphen checking to any tag (besides the preferred
156
- \`@param\` tag which follows the main string option setting and besides any
157
- other \`tags\` entries).`
158
- }
159
- },
160
- type: 'object'
161
- }],
162
- type: 'layout'
163
- }
164
- });
165
- module.exports = exports.default;
166
- //# sourceMappingURL=requireHyphenBeforeParamDescription.cjs.map
@@ -1 +0,0 @@
1
- {"version":3,"file":"requireHyphenBeforeParamDescription.cjs","names":["iterateJsdoc"],"sources":["../../src/rules/requireHyphenBeforeParamDescription.js"],"sourcesContent":["import iterateJsdoc from '../iterateJsdoc.js';\n\nexport default iterateJsdoc(({\n context,\n jsdoc,\n utils,\n}) => {\n const [\n mainCircumstance,\n {\n tags = null,\n } = {},\n ] = context.options;\n\n const tgs = /**\n * @type {null|\"any\"|{[key: string]: \"always\"|\"never\"}}\n */ (tags);\n\n /**\n * @param {import('@es-joy/jsdoccomment').JsdocTagWithInline} jsdocTag\n * @param {string} targetTagName\n * @param {\"always\"|\"never\"} [circumstance]\n * @returns {void}\n */\n const checkHyphens = (jsdocTag, targetTagName, circumstance = mainCircumstance) => {\n const always = !circumstance || circumstance === 'always';\n const desc = /** @type {string} */ (utils.getTagDescription(jsdocTag));\n if (!desc.trim()) {\n return;\n }\n\n const startsWithHyphen = (/^\\s*-/v).test(desc);\n const hyphenNewline = (/^\\s*-\\n/v).test(desc);\n\n let lines = 0;\n for (const {\n tokens,\n } of jsdocTag.source) {\n if (tokens.description) {\n break;\n }\n\n lines++;\n }\n\n if (always && !hyphenNewline) {\n if (!startsWithHyphen) {\n let fixIt = true;\n for (const {\n tokens,\n } of jsdocTag.source) {\n if (tokens.description) {\n tokens.description = tokens.description.replace(\n /^(\\s*)/v, '$1- ',\n );\n break;\n }\n\n // Linebreak after name since has no description\n if (tokens.name) {\n fixIt = false;\n break;\n }\n }\n\n if (fixIt) {\n utils.reportJSDoc(\n `There must be a hyphen before @${targetTagName} description.`,\n {\n line: jsdocTag.source[0].number + lines,\n },\n () => {},\n );\n }\n }\n } else if (startsWithHyphen) {\n utils.reportJSDoc(\n always ?\n `There must be no hyphen followed by newline after the @${targetTagName} name.` :\n `There must be no hyphen before @${targetTagName} description.`,\n {\n line: jsdocTag.source[0].number + lines,\n },\n () => {\n for (const {\n tokens,\n } of jsdocTag.source) {\n if (tokens.description) {\n tokens.description = tokens.description.replace(\n /^\\s*-\\s*/v, '',\n );\n if (hyphenNewline) {\n tokens.postName = '';\n }\n\n break;\n }\n }\n },\n true,\n );\n }\n };\n\n utils.forEachPreferredTag('param', checkHyphens);\n if (tgs) {\n const tagEntries = Object.entries(tgs);\n for (const [\n tagName,\n circumstance,\n ] of tagEntries) {\n if (tagName === '*') {\n const preferredParamTag = utils.getPreferredTagName({\n tagName: 'param',\n });\n for (const {\n tag,\n } of jsdoc.tags) {\n if (tag === preferredParamTag || tagEntries.some(([\n tagNme,\n ]) => {\n return tagNme !== '*' && tagNme === tag;\n })) {\n continue;\n }\n\n utils.forEachPreferredTag(tag, (jsdocTag, targetTagName) => {\n checkHyphens(\n jsdocTag,\n targetTagName,\n /** @type {\"always\"|\"never\"} */ (circumstance),\n );\n });\n }\n\n continue;\n }\n\n utils.forEachPreferredTag(tagName, (jsdocTag, targetTagName) => {\n checkHyphens(\n jsdocTag,\n targetTagName,\n /** @type {\"always\"|\"never\"} */ (circumstance),\n );\n });\n }\n }\n}, {\n iterateAllJsdocs: true,\n meta: {\n docs: {\n description: 'Requires a hyphen before the `@param` description (and optionally before `@property` descriptions).',\n url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-hyphen-before-param-description.md#repos-sticky-header',\n },\n fixable: 'code',\n schema: [\n {\n description: `If the string is \\`\"always\"\\` then a problem is raised when there is no hyphen\nbefore the description. If it is \\`\"never\"\\` then a problem is raised when there\nis a hyphen before the description. The default value is \\`\"always\"\\`.\n\nEven if hyphens are set to \"always\" appear after the tag name, they will\nactually be forbidden in the event that they are followed immediately by\nthe end of a line (this will otherwise cause Visual Studio Code to display\nincorrectly).`,\n enum: [\n 'always', 'never',\n ],\n type: 'string',\n },\n {\n additionalProperties: false,\n description: `The options object may have the following property to indicate behavior for\nother tags besides the \\`@param\\` tag (or the \\`@arg\\` tag if so set).`,\n properties: {\n tags: {\n anyOf: [\n {\n patternProperties: {\n '.*': {\n enum: [\n 'always', 'never',\n ],\n type: 'string',\n },\n },\n type: 'object',\n },\n {\n enum: [\n 'any',\n ],\n type: 'string',\n },\n ],\n description: `Object whose keys indicate different tags to check for the\n presence or absence of hyphens; the key value should be \"always\" or \"never\",\n indicating how hyphens are to be applied, e.g., \\`{property: 'never'}\\`\n to ensure \\`@property\\` never uses hyphens. A key can also be set as \\`*\\`, e.g.,\n \\`'*': 'always'\\` to apply hyphen checking to any tag (besides the preferred\n \\`@param\\` tag which follows the main string option setting and besides any\n other \\`tags\\` entries).`,\n },\n },\n type: 'object',\n },\n ],\n type: 'layout',\n },\n});\n"],"mappings":"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","ignoreList":[]}