@depup/eslint-plugin-jsdoc 63.3.2-depup.1 → 64.0.0-depup.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 (272) hide show
  1. package/README.md +3 -11
  2. package/changes.json +3 -16
  3. package/dist/index.d.ts +7 -4
  4. package/package.json +29 -67
  5. package/src/index.js +7 -8
  6. package/dist/WarnSettings.cjs +0 -38
  7. package/dist/WarnSettings.cjs.map +0 -1
  8. package/dist/alignTransform.cjs +0 -402
  9. package/dist/alignTransform.cjs.map +0 -1
  10. package/dist/buildForbidRuleDefinition.cjs +0 -101
  11. package/dist/buildForbidRuleDefinition.cjs.map +0 -1
  12. package/dist/buildRejectOrPreferRuleDefinition.cjs +0 -352
  13. package/dist/buildRejectOrPreferRuleDefinition.cjs.map +0 -1
  14. package/dist/cjs/WarnSettings.d.ts +0 -16
  15. package/dist/cjs/alignTransform.d.ts +0 -33
  16. package/dist/cjs/buildForbidRuleDefinition.d.ts +0 -14
  17. package/dist/cjs/buildRejectOrPreferRuleDefinition.d.ts +0 -8
  18. package/dist/cjs/defaultTagOrder.d.ts +0 -4
  19. package/dist/cjs/exportParser.d.ts +0 -40
  20. package/dist/cjs/getDefaultTagStructureForMode.d.ts +0 -10
  21. package/dist/cjs/getJsdocProcessorPlugin.d.cts +0 -5
  22. package/dist/cjs/getJsdocProcessorPlugin.d.ts +0 -66
  23. package/dist/cjs/index-cjs.d.ts +0 -23
  24. package/dist/cjs/index.cjs.d.cts +0 -2
  25. package/dist/cjs/iterateJsdoc.d.cts +0 -7
  26. package/dist/cjs/iterateJsdoc.d.ts +0 -495
  27. package/dist/cjs/jsdocUtils.d.ts +0 -500
  28. package/dist/cjs/rules/checkAccess.d.ts +0 -2
  29. package/dist/cjs/rules/checkAlignment.d.ts +0 -2
  30. package/dist/cjs/rules/checkExamples.d.ts +0 -3
  31. package/dist/cjs/rules/checkIndentation.d.ts +0 -2
  32. package/dist/cjs/rules/checkLineAlignment.d.ts +0 -9
  33. package/dist/cjs/rules/checkParamNames.d.ts +0 -2
  34. package/dist/cjs/rules/checkPropertyNames.d.ts +0 -2
  35. package/dist/cjs/rules/checkSyntax.d.ts +0 -2
  36. package/dist/cjs/rules/checkTagNames.d.ts +0 -2
  37. package/dist/cjs/rules/checkTemplateNames.d.ts +0 -2
  38. package/dist/cjs/rules/checkTypes.d.ts +0 -7
  39. package/dist/cjs/rules/checkValues.d.ts +0 -2
  40. package/dist/cjs/rules/convertToJsdocComments.d.ts +0 -266
  41. package/dist/cjs/rules/emptyTags.d.ts +0 -2
  42. package/dist/cjs/rules/escapeInlineTags.d.ts +0 -2
  43. package/dist/cjs/rules/implementsOnClasses.d.ts +0 -2
  44. package/dist/cjs/rules/importsAsDependencies.d.ts +0 -2
  45. package/dist/cjs/rules/informativeDocs.d.ts +0 -2
  46. package/dist/cjs/rules/linesBeforeBlock.d.ts +0 -2
  47. package/dist/cjs/rules/matchDescription.d.ts +0 -2
  48. package/dist/cjs/rules/matchName.d.ts +0 -2
  49. package/dist/cjs/rules/multilineBlocks.d.ts +0 -2
  50. package/dist/cjs/rules/noBadBlocks.d.ts +0 -2
  51. package/dist/cjs/rules/noBlankBlockDescriptions.d.ts +0 -2
  52. package/dist/cjs/rules/noBlankBlocks.d.ts +0 -2
  53. package/dist/cjs/rules/noDefaults.d.ts +0 -2
  54. package/dist/cjs/rules/noMissingSyntax.d.ts +0 -9
  55. package/dist/cjs/rules/noMultiAsterisks.d.ts +0 -2
  56. package/dist/cjs/rules/noRestrictedSyntax.d.ts +0 -2
  57. package/dist/cjs/rules/noTypes.d.ts +0 -2
  58. package/dist/cjs/rules/noUndefinedTypes.d.ts +0 -2
  59. package/dist/cjs/rules/normalizeSeeLinks.d.ts +0 -2
  60. package/dist/cjs/rules/preferImportTag.d.ts +0 -2
  61. package/dist/cjs/rules/requireAsteriskPrefix.d.ts +0 -2
  62. package/dist/cjs/rules/requireDescription.d.ts +0 -2
  63. package/dist/cjs/rules/requireDescriptionCompleteSentence.d.ts +0 -2
  64. package/dist/cjs/rules/requireExample.d.ts +0 -2
  65. package/dist/cjs/rules/requireFileOverview.d.ts +0 -2
  66. package/dist/cjs/rules/requireHyphenBeforeParamDescription.d.ts +0 -2
  67. package/dist/cjs/rules/requireJsdoc.d.ts +0 -24
  68. package/dist/cjs/rules/requireParam.d.ts +0 -3
  69. package/dist/cjs/rules/requireParamDescription.d.ts +0 -2
  70. package/dist/cjs/rules/requireParamName.d.ts +0 -2
  71. package/dist/cjs/rules/requireParamType.d.ts +0 -2
  72. package/dist/cjs/rules/requireProperty.d.ts +0 -2
  73. package/dist/cjs/rules/requirePropertyDescription.d.ts +0 -2
  74. package/dist/cjs/rules/requirePropertyName.d.ts +0 -2
  75. package/dist/cjs/rules/requirePropertyType.d.ts +0 -2
  76. package/dist/cjs/rules/requireRejects.d.ts +0 -2
  77. package/dist/cjs/rules/requireReturns.d.ts +0 -2
  78. package/dist/cjs/rules/requireReturnsCheck.d.ts +0 -2
  79. package/dist/cjs/rules/requireReturnsDescription.d.ts +0 -2
  80. package/dist/cjs/rules/requireReturnsType.d.ts +0 -2
  81. package/dist/cjs/rules/requireTags.d.ts +0 -2
  82. package/dist/cjs/rules/requireTemplate.d.ts +0 -2
  83. package/dist/cjs/rules/requireThrows.d.ts +0 -2
  84. package/dist/cjs/rules/requireYields.d.ts +0 -2
  85. package/dist/cjs/rules/requireYieldsCheck.d.ts +0 -2
  86. package/dist/cjs/rules/sortTags.d.ts +0 -2
  87. package/dist/cjs/rules/tagLines.d.ts +0 -2
  88. package/dist/cjs/rules/textEscaping.d.ts +0 -2
  89. package/dist/cjs/rules/tsMethodSignatureStyle.d.ts +0 -2
  90. package/dist/cjs/rules/tsNoEmptyObjectType.d.ts +0 -2
  91. package/dist/cjs/rules/tsNoUnnecessaryTemplateExpression.d.ts +0 -2
  92. package/dist/cjs/rules/tsPreferFunctionType.d.ts +0 -2
  93. package/dist/cjs/rules/typeFormatting.d.ts +0 -2
  94. package/dist/cjs/rules/validTypes.d.ts +0 -2
  95. package/dist/cjs/tagNames.d.ts +0 -15
  96. package/dist/cjs/utils/hasReturnValue.d.ts +0 -19
  97. package/dist/defaultTagOrder.cjs +0 -46
  98. package/dist/defaultTagOrder.cjs.map +0 -1
  99. package/dist/exportParser.cjs +0 -732
  100. package/dist/exportParser.cjs.map +0 -1
  101. package/dist/generateDocs.cjs +0 -342
  102. package/dist/generateDocs.cjs.map +0 -1
  103. package/dist/generateOptions.cjs +0 -62
  104. package/dist/generateOptions.cjs.map +0 -1
  105. package/dist/generateRule.cjs +0 -248
  106. package/dist/generateRule.cjs.map +0 -1
  107. package/dist/generateRuleTypes.cjs +0 -24
  108. package/dist/generateRuleTypes.cjs.map +0 -1
  109. package/dist/getDefaultTagStructureForMode.cjs +0 -289
  110. package/dist/getDefaultTagStructureForMode.cjs.map +0 -1
  111. package/dist/getJsdocProcessorPlugin.cjs +0 -587
  112. package/dist/getJsdocProcessorPlugin.cjs.map +0 -1
  113. package/dist/getJsdocProcessorPlugin.cts +0 -5
  114. package/dist/index-cjs.cjs +0 -598
  115. package/dist/index-cjs.cjs.map +0 -1
  116. package/dist/index-cjs.d.ts +0 -24
  117. package/dist/index-esm.cjs +0 -162
  118. package/dist/index-esm.cjs.map +0 -1
  119. package/dist/index-esm.d.ts +0 -72
  120. package/dist/index.cjs +0 -746
  121. package/dist/index.cjs.cts +0 -3
  122. package/dist/index.cjs.map +0 -1
  123. package/dist/iterateJsdoc.cjs +0 -2150
  124. package/dist/iterateJsdoc.cjs.map +0 -1
  125. package/dist/iterateJsdoc.cts +0 -7
  126. package/dist/jsdocUtils.cjs +0 -1786
  127. package/dist/jsdocUtils.cjs.map +0 -1
  128. package/dist/rules/checkAccess.cjs +0 -40
  129. package/dist/rules/checkAccess.cjs.map +0 -1
  130. package/dist/rules/checkAlignment.cjs +0 -78
  131. package/dist/rules/checkAlignment.cjs.map +0 -1
  132. package/dist/rules/checkExamples.cjs +0 -521
  133. package/dist/rules/checkExamples.cjs.map +0 -1
  134. package/dist/rules/checkIndentation.cjs +0 -170
  135. package/dist/rules/checkIndentation.cjs.map +0 -1
  136. package/dist/rules/checkLineAlignment.cjs +0 -398
  137. package/dist/rules/checkLineAlignment.cjs.map +0 -1
  138. package/dist/rules/checkParamNames.cjs +0 -407
  139. package/dist/rules/checkParamNames.cjs.map +0 -1
  140. package/dist/rules/checkPropertyNames.cjs +0 -135
  141. package/dist/rules/checkPropertyNames.cjs.map +0 -1
  142. package/dist/rules/checkSyntax.cjs +0 -38
  143. package/dist/rules/checkSyntax.cjs.map +0 -1
  144. package/dist/rules/checkTagNames.cjs +0 -312
  145. package/dist/rules/checkTagNames.cjs.map +0 -1
  146. package/dist/rules/checkTemplateNames.cjs +0 -192
  147. package/dist/rules/checkTemplateNames.cjs.map +0 -1
  148. package/dist/rules/checkTypes.cjs +0 -111
  149. package/dist/rules/checkTypes.cjs.map +0 -1
  150. package/dist/rules/checkValues.cjs +0 -166
  151. package/dist/rules/checkValues.cjs.map +0 -1
  152. package/dist/rules/convertToJsdocComments.cjs +0 -356
  153. package/dist/rules/convertToJsdocComments.cjs.map +0 -1
  154. package/dist/rules/emptyTags.cjs +0 -98
  155. package/dist/rules/emptyTags.cjs.map +0 -1
  156. package/dist/rules/escapeInlineTags.cjs +0 -234
  157. package/dist/rules/escapeInlineTags.cjs.map +0 -1
  158. package/dist/rules/implementsOnClasses.cjs +0 -74
  159. package/dist/rules/implementsOnClasses.cjs.map +0 -1
  160. package/dist/rules/importsAsDependencies.cjs +0 -104
  161. package/dist/rules/importsAsDependencies.cjs.map +0 -1
  162. package/dist/rules/informativeDocs.cjs +0 -187
  163. package/dist/rules/informativeDocs.cjs.map +0 -1
  164. package/dist/rules/linesBeforeBlock.cjs +0 -120
  165. package/dist/rules/linesBeforeBlock.cjs.map +0 -1
  166. package/dist/rules/matchDescription.cjs +0 -356
  167. package/dist/rules/matchDescription.cjs.map +0 -1
  168. package/dist/rules/matchName.cjs +0 -160
  169. package/dist/rules/matchName.cjs.map +0 -1
  170. package/dist/rules/multilineBlocks.cjs +0 -431
  171. package/dist/rules/multilineBlocks.cjs.map +0 -1
  172. package/dist/rules/noBadBlocks.cjs +0 -100
  173. package/dist/rules/noBadBlocks.cjs.map +0 -1
  174. package/dist/rules/noBlankBlockDescriptions.cjs +0 -63
  175. package/dist/rules/noBlankBlockDescriptions.cjs.map +0 -1
  176. package/dist/rules/noBlankBlocks.cjs +0 -54
  177. package/dist/rules/noBlankBlocks.cjs.map +0 -1
  178. package/dist/rules/noDefaults.cjs +0 -102
  179. package/dist/rules/noDefaults.cjs.map +0 -1
  180. package/dist/rules/noMissingSyntax.cjs +0 -196
  181. package/dist/rules/noMissingSyntax.cjs.map +0 -1
  182. package/dist/rules/noMultiAsterisks.cjs +0 -126
  183. package/dist/rules/noMultiAsterisks.cjs.map +0 -1
  184. package/dist/rules/noRestrictedSyntax.cjs +0 -68
  185. package/dist/rules/noRestrictedSyntax.cjs.map +0 -1
  186. package/dist/rules/noTypes.cjs +0 -101
  187. package/dist/rules/noTypes.cjs.map +0 -1
  188. package/dist/rules/noUndefinedTypes.cjs +0 -616
  189. package/dist/rules/noUndefinedTypes.cjs.map +0 -1
  190. package/dist/rules/normalizeSeeLinks.cjs +0 -271
  191. package/dist/rules/normalizeSeeLinks.cjs.map +0 -1
  192. package/dist/rules/preferImportTag.cjs +0 -362
  193. package/dist/rules/preferImportTag.cjs.map +0 -1
  194. package/dist/rules/requireAsteriskPrefix.cjs +0 -190
  195. package/dist/rules/requireAsteriskPrefix.cjs.map +0 -1
  196. package/dist/rules/requireDescription.cjs +0 -164
  197. package/dist/rules/requireDescription.cjs.map +0 -1
  198. package/dist/rules/requireDescriptionCompleteSentence.cjs +0 -321
  199. package/dist/rules/requireDescriptionCompleteSentence.cjs.map +0 -1
  200. package/dist/rules/requireExample.cjs +0 -136
  201. package/dist/rules/requireExample.cjs.map +0 -1
  202. package/dist/rules/requireFileOverview.cjs +0 -194
  203. package/dist/rules/requireFileOverview.cjs.map +0 -1
  204. package/dist/rules/requireHyphenBeforeParamDescription.cjs +0 -166
  205. package/dist/rules/requireHyphenBeforeParamDescription.cjs.map +0 -1
  206. package/dist/rules/requireJsdoc.cjs +0 -721
  207. package/dist/rules/requireJsdoc.cjs.map +0 -1
  208. package/dist/rules/requireParam.cjs +0 -772
  209. package/dist/rules/requireParam.cjs.map +0 -1
  210. package/dist/rules/requireParamDescription.cjs +0 -105
  211. package/dist/rules/requireParamDescription.cjs.map +0 -1
  212. package/dist/rules/requireParamName.cjs +0 -68
  213. package/dist/rules/requireParamName.cjs.map +0 -1
  214. package/dist/rules/requireParamType.cjs +0 -104
  215. package/dist/rules/requireParamType.cjs.map +0 -1
  216. package/dist/rules/requireProperty.cjs +0 -63
  217. package/dist/rules/requireProperty.cjs.map +0 -1
  218. package/dist/rules/requirePropertyDescription.cjs +0 -29
  219. package/dist/rules/requirePropertyDescription.cjs.map +0 -1
  220. package/dist/rules/requirePropertyName.cjs +0 -29
  221. package/dist/rules/requirePropertyName.cjs.map +0 -1
  222. package/dist/rules/requirePropertyType.cjs +0 -29
  223. package/dist/rules/requirePropertyType.cjs.map +0 -1
  224. package/dist/rules/requireRejects.cjs +0 -226
  225. package/dist/rules/requireRejects.cjs.map +0 -1
  226. package/dist/rules/requireReturns.cjs +0 -262
  227. package/dist/rules/requireReturns.cjs.map +0 -1
  228. package/dist/rules/requireReturnsCheck.cjs +0 -225
  229. package/dist/rules/requireReturnsCheck.cjs.map +0 -1
  230. package/dist/rules/requireReturnsDescription.cjs +0 -72
  231. package/dist/rules/requireReturnsDescription.cjs.map +0 -1
  232. package/dist/rules/requireReturnsType.cjs +0 -68
  233. package/dist/rules/requireReturnsType.cjs.map +0 -1
  234. package/dist/rules/requireTags.cjs +0 -74
  235. package/dist/rules/requireTags.cjs.map +0 -1
  236. package/dist/rules/requireTemplate.cjs +0 -220
  237. package/dist/rules/requireTemplate.cjs.map +0 -1
  238. package/dist/rules/requireThrows.cjs +0 -118
  239. package/dist/rules/requireThrows.cjs.map +0 -1
  240. package/dist/rules/requireYields.cjs +0 -224
  241. package/dist/rules/requireYields.cjs.map +0 -1
  242. package/dist/rules/requireYieldsCheck.cjs +0 -179
  243. package/dist/rules/requireYieldsCheck.cjs.map +0 -1
  244. package/dist/rules/sortTags.cjs +0 -656
  245. package/dist/rules/sortTags.cjs.map +0 -1
  246. package/dist/rules/tagLines.cjs +0 -374
  247. package/dist/rules/tagLines.cjs.map +0 -1
  248. package/dist/rules/textEscaping.cjs +0 -141
  249. package/dist/rules/textEscaping.cjs.map +0 -1
  250. package/dist/rules/tsMethodSignatureStyle.cjs +0 -240
  251. package/dist/rules/tsMethodSignatureStyle.cjs.map +0 -1
  252. package/dist/rules/tsNoEmptyObjectType.cjs +0 -62
  253. package/dist/rules/tsNoEmptyObjectType.cjs.map +0 -1
  254. package/dist/rules/tsNoUnnecessaryTemplateExpression.cjs +0 -104
  255. package/dist/rules/tsNoUnnecessaryTemplateExpression.cjs.map +0 -1
  256. package/dist/rules/tsPreferFunctionType.cjs +0 -110
  257. package/dist/rules/tsPreferFunctionType.cjs.map +0 -1
  258. package/dist/rules/typeFormatting.cjs +0 -607
  259. package/dist/rules/typeFormatting.cjs.map +0 -1
  260. package/dist/rules/validTypes.cjs +0 -324
  261. package/dist/rules/validTypes.cjs.map +0 -1
  262. package/dist/tagNames.cjs +0 -244
  263. package/dist/tagNames.cjs.map +0 -1
  264. package/dist/to-valid-identifier.cjs +0 -263
  265. package/dist/utils/hasReturnValue.cjs +0 -495
  266. package/dist/utils/hasReturnValue.cjs.map +0 -1
  267. package/rollup.config.js +0 -16
  268. package/src/getJsdocProcessorPlugin.cts +0 -5
  269. package/src/index-cjs.js +0 -758
  270. package/src/index-esm.js +0 -196
  271. package/src/index.cjs.cts +0 -3
  272. 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":[]}