Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit 214a5f2

Browse files
brettz9brettz9
committed
feat(require-next-description, require-throws-decription, require-yields-description): add rules; fixes #1526 
1 parent 2ff5f14 commit 214a5f2

16 files changed

+347
-2
lines changed

‎.README/README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -375,4 +375,4 @@ non-default-recommended fixer).
375375

376376
|recommended|fixable|rule|description|
377377
|-|-|-|-|
378-
{"gitdown": "rulestable"}
378+
{"gitdown": "rules-table"}

‎.README/rules/require-next-description.md‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
# `require-next-description`
2+
3+
Requires a description for (non-standard) `@next` tags.
4+
5+
|||
6+
|---|---|
7+
|Context|everywhere|
8+
|Tags|`next`|
9+
|Recommended|false|
10+
|Settings||
11+
|Options||
12+
13+
## Failing examples
14+
15+
<!-- assertions-failing requireNextDescription -->
16+
17+
## Passing examples
18+
19+
<!-- assertions-passing requireNextDescription -->

‎.README/rules/require-throws-description.md‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
# `require-throws-description`
2+
3+
Requires a description for `@throws` tags.
4+
5+
|||
6+
|---|---|
7+
|Context|everywhere|
8+
|Tags|`throws`|
9+
|Recommended|false|
10+
|Settings||
11+
|Options||
12+
13+
## Failing examples
14+
15+
<!-- assertions-failing requireThrowsDescription -->
16+
17+
## Passing examples
18+
19+
<!-- assertions-passing requireThrowsDescription -->

‎.README/rules/require-yields-description.md‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
# `require-yields-description`
2+
3+
Requires a description for `@yields` tags.
4+
5+
|||
6+
|---|---|
7+
|Context|everywhere|
8+
|Tags|`yields`|
9+
|Recommended|false|
10+
|Settings||
11+
|Options||
12+
13+
## Failing examples
14+
15+
<!-- assertions-failing requireYieldsDescription -->
16+
17+
## Passing examples
18+
19+
<!-- assertions-passing requireYieldsDescription -->

‎README.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -451,6 +451,7 @@ non-default-recommended fixer).
451451
||| [require-file-overview](./docs/rules/require-file-overview.md#readme) | Checks that all files have one `@file`, `@fileoverview`, or `@overview` tag at the beginning of the file. |
452452
||:wrench:| [require-hyphen-before-param-description](./docs/rules/require-hyphen-before-param-description.md#readme) | Requires a hyphen before the `@param` description (and optionally before `@property` descriptions). |
453453
|:heavy_check_mark:|:wrench:| [require-jsdoc](./docs/rules/require-jsdoc.md#readme) | Checks for presence of JSDoc comments, on functions and potentially other contexts (optionally limited to exports). |
454+
||| [require-next-description](./docs/rules/require-next-description.md#readme) | Requires a description for `@next` tags |
454455
|:heavy_check_mark:|| [require-next-type](./docs/rules/require-next-type.md#readme) | Requires a type for `@next` tags |
455456
|:heavy_check_mark:|:wrench:| [require-param](./docs/rules/require-param.md#readme) | Requires that all function parameters are documented with a `@param` tag. |
456457
|:heavy_check_mark:|:wrench:| [require-param-description](./docs/rules/require-param-description.md#readme) | Requires that each `@param` tag has a `description` value. |
@@ -466,9 +467,11 @@ non-default-recommended fixer).
466467
|:heavy_check_mark: (Off in TS; On in TS flavor)|| [require-returns-type](./docs/rules/require-returns-type.md#readme) | Requires that `@returns` tag has type value (in curly brackets). |
467468
||| [require-template](./docs/rules/require-template.md#readme) | Requires `@template` tags be present when type parameters are used. |
468469
||| [require-throws](./docs/rules/require-throws.md#readme) | Requires that throw statements are documented with `@throws` tags. |
470+
||| [require-throws-description](./docs/rules/require-throws-description.md#readme) | Requires a description for `@throws` tags |
469471
|:heavy_check_mark:|| [require-throws-type](./docs/rules/require-throws-type.md#readme) | Requires a type for `@throws` tags |
470472
|:heavy_check_mark:|| [require-yields](./docs/rules/require-yields.md#readme) | Requires yields are documented with `@yields` tags. |
471473
|:heavy_check_mark:|| [require-yields-check](./docs/rules/require-yields-check.md#readme) | Ensures that if a `@yields` is present that a `yield` (or `yield` with a value) is present in the function body (or that if a `@next` is present that there is a yield with a return value present). |
474+
||| [require-yields-description](./docs/rules/require-yields-description.md#readme) | Requires a description for `@yields` tags |
472475
|:heavy_check_mark:|| [require-yields-type](./docs/rules/require-yields-type.md#readme) | Requires a type for `@yields` tags |
473476
||:wrench:| [sort-tags](./docs/rules/sort-tags.md#readme) | Sorts tags by a specified sequence according to tag name, optionally adding line breaks between tag groups. |
474477
|:heavy_check_mark:|:wrench:| [tag-lines](./docs/rules/tag-lines.md#readme) | Enforces lines (or no lines) between tags. |

‎docs/rules/require-next-description.md‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
<a name="user-content-require-next-description"></a>
2+
<a name="require-next-description"></a>
3+
# <code>require-next-description</code>
4+
5+
Requires a description for (non-standard) `@next` tags.
6+
7+
|||
8+
|---|---|
9+
|Context|everywhere|
10+
|Tags|`next`|
11+
|Recommended|false|
12+
|Settings||
13+
|Options||
14+
15+
<a name="user-content-require-next-description-failing-examples"></a>
16+
<a name="require-next-description-failing-examples"></a>
17+
## Failing examples
18+
19+
The following patterns are considered problems:
20+
21+
````ts
22+
/**
23+
* @next {SomeType}
24+
*/
25+
// Message: @next should have a description
26+
````
27+
28+
29+
30+
<a name="user-content-require-next-description-passing-examples"></a>
31+
<a name="require-next-description-passing-examples"></a>
32+
## Passing examples
33+
34+
The following patterns are not considered problems:
35+
36+
````ts
37+
/**
38+
* @next {SomeType} Has a description
39+
*/
40+
````
41+

‎docs/rules/require-throws-description.md‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
<a name="user-content-require-throws-description"></a>
2+
<a name="require-throws-description"></a>
3+
# <code>require-throws-description</code>
4+
5+
Requires a description for `@throws` tags.
6+
7+
|||
8+
|---|---|
9+
|Context|everywhere|
10+
|Tags|`throws`|
11+
|Recommended|false|
12+
|Settings||
13+
|Options||
14+
15+
<a name="user-content-require-throws-description-failing-examples"></a>
16+
<a name="require-throws-description-failing-examples"></a>
17+
## Failing examples
18+
19+
The following patterns are considered problems:
20+
21+
````ts
22+
/**
23+
* @throws {SomeType}
24+
*/
25+
// Message: @throws should have a description
26+
````
27+
28+
29+
30+
<a name="user-content-require-throws-description-passing-examples"></a>
31+
<a name="require-throws-description-passing-examples"></a>
32+
## Passing examples
33+
34+
The following patterns are not considered problems:
35+
36+
````ts
37+
/**
38+
* @throws {SomeType} Has a description
39+
*/
40+
````
41+

‎docs/rules/require-yields-description.md‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
<a name="user-content-require-yields-description"></a>
2+
<a name="require-yields-description"></a>
3+
# <code>require-yields-description</code>
4+
5+
Requires a description for `@yields` tags.
6+
7+
|||
8+
|---|---|
9+
|Context|everywhere|
10+
|Tags|`yields`|
11+
|Recommended|false|
12+
|Settings||
13+
|Options||
14+
15+
<a name="user-content-require-yields-description-failing-examples"></a>
16+
<a name="require-yields-description-failing-examples"></a>
17+
## Failing examples
18+
19+
The following patterns are considered problems:
20+
21+
````ts
22+
/**
23+
* @yields {SomeType}
24+
*/
25+
// Message: @yields should have a description
26+
````
27+
28+
29+
30+
<a name="user-content-require-yields-description-passing-examples"></a>
31+
<a name="require-yields-description-passing-examples"></a>
32+
## Passing examples
33+
34+
The following patterns are not considered problems:
35+
36+
````ts
37+
/**
38+
* @yields {SomeType} Has a description
39+
*/
40+
````
41+

‎src/bin/generateDocs.js‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -213,7 +213,7 @@ const generateDocs = async () => {
213213
},
214214
});
215215

216-
gitdown.registerHelper('rulestable', {
216+
gitdown.registerHelper('rules-table', {
217217
compile () {
218218
return tableRows.toSorted(({
219219
decamelized,

‎src/index-cjs.js‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -144,6 +144,17 @@ index.rules = {
144144
'require-file-overview': requireFileOverview,
145145
'require-hyphen-before-param-description': requireHyphenBeforeParamDescription,
146146
'require-jsdoc': requireJsdoc,
147+
'require-next-description': buildForbidRuleDefinition({
148+
contexts: [
149+
{
150+
comment: 'JsdocBlock:has(JsdocTag[tag=next]:not([name!=""]))',
151+
context: 'any',
152+
message: '@next should have a description',
153+
},
154+
],
155+
description: 'Requires a description for `@next` tags',
156+
url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-next-description.md#repos-sticky-header',
157+
}),
147158
'require-next-type': buildForbidRuleDefinition({
148159
contexts: [
149160
{
@@ -169,6 +180,17 @@ index.rules = {
169180
'require-returns-type': requireReturnsType,
170181
'require-template': requireTemplate,
171182
'require-throws': requireThrows,
183+
'require-throws-description': buildForbidRuleDefinition({
184+
contexts: [
185+
{
186+
comment: 'JsdocBlock:has(JsdocTag[tag=throws]:not([description!=""]))',
187+
context: 'any',
188+
message: '@throws should have a description',
189+
},
190+
],
191+
description: 'Requires a description for `@throws` tags',
192+
url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-throws-description.md#repos-sticky-header',
193+
}),
172194
'require-throws-type': buildForbidRuleDefinition({
173195
contexts: [
174196
{
@@ -182,6 +204,17 @@ index.rules = {
182204
}),
183205
'require-yields': requireYields,
184206
'require-yields-check': requireYieldsCheck,
207+
'require-yields-description': buildForbidRuleDefinition({
208+
contexts: [
209+
{
210+
comment: 'JsdocBlock:has(JsdocTag[tag=yields]:not([name!=""]))',
211+
context: 'any',
212+
message: '@yields should have a description',
213+
},
214+
],
215+
description: 'Requires a description for `@yields` tags',
216+
url: 'https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-yields-description.md#repos-sticky-header',
217+
}),
185218
'require-yields-type': buildForbidRuleDefinition({
186219
contexts: [
187220
{
@@ -257,6 +290,7 @@ const createRecommendedRuleset = (warnOrError, flatName) => {
257290
'jsdoc/require-file-overview': 'off',
258291
'jsdoc/require-hyphen-before-param-description': 'off',
259292
'jsdoc/require-jsdoc': warnOrError,
293+
'jsdoc/require-next-description': 'off',
260294
'jsdoc/require-next-type': warnOrError,
261295
'jsdoc/require-param': warnOrError,
262296
'jsdoc/require-param-description': warnOrError,
@@ -272,9 +306,11 @@ const createRecommendedRuleset = (warnOrError, flatName) => {
272306
'jsdoc/require-returns-type': warnOrError,
273307
'jsdoc/require-template': 'off',
274308
'jsdoc/require-throws': 'off',
309+
'jsdoc/require-throws-description': 'off',
275310
'jsdoc/require-throws-type': warnOrError,
276311
'jsdoc/require-yields': warnOrError,
277312
'jsdoc/require-yields-check': warnOrError,
313+
'jsdoc/require-yields-description': 'off',
278314
'jsdoc/require-yields-type': warnOrError,
279315
'jsdoc/sort-tags': 'off',
280316
'jsdoc/tag-lines': warnOrError,

0 commit comments

Comments
 (0)