eslint-plugin-jsdoc 63.3.3 → 64.0.1

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