Skip to content

Commit 0645428

Browse files
brettz9brettz9
committed
feat(require-next-type, require-throws-type, require-yields-type): adds new rules and adds to recommended and required configs; fixes #1461
BREAKING CHANGE: It is unlikely to affect users but when using the jsdoc constructor with a recommended config , this commit removes `throws` and `yields` from the `structuredTags` settings recently added to the config output to require types for these tags in favor of the herein added equivalent recommended rules. (`next` is still part of `structuredTags` output, however, because this setting ensures the non-standard next tag is treated as allowable without need for separate configuration.) Also: - chore: remove unused linting directives
1 parent dc88471 commit 0645428

26 files changed

+729
-317
lines changed

‎.README/README.md

Lines changed: 3 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -82,16 +82,6 @@ export default [
8282
'type',
8383
],
8484
},
85-
throws: {
86-
required: [
87-
'type',
88-
],
89-
},
90-
yields: {
91-
required: [
92-
'type',
93-
],
94-
},
9585
},
9686
*/
9787
}
@@ -419,6 +409,7 @@ non-default-recommended fixer).
419409
|||[require-file-overview](./docs/rules/require-file-overview.md#readme)|By default, requires a single `@file` tag at the beginning of each linted file|
420410
||:wrench:|[require-hyphen-before-param-description](./docs/rules/require-hyphen-before-param-description.md#readme)|Requires a hyphen before `@param` descriptions (and optionally before `@property` descriptions)|
421411
|: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).|
412+
|:heavy_check_mark:||[require-next-type](./docs/rules/require-next-type.md#readme)|Requires a type on the (non-standard) `@next` tag.|
422413
|:heavy_check_mark:|:wrench:|[require-param](./docs/rules/require-param.md#readme)|Requires that all function parameters are documented with a `@param` tag.|
423414
|:heavy_check_mark:||[require-param-description](./docs/rules/require-param-description.md#readme)|Requires that each `@param` tag has a `description` value.|
424415
|:heavy_check_mark:||[require-param-name](./docs/rules/require-param-name.md#readme)|Requires that all `@param` tags have names.|
@@ -433,8 +424,10 @@ non-default-recommended fixer).
433424
|:heavy_check_mark: (off in TS)||[require-returns-type](./docs/rules/require-returns-type.md#readme)|Requires that `@returns` tag has a type value (in curly brackets).|
434425
| || [require-template](./docs/rules/require-template.md#readme) | Requires `@template` tags be present when type parameters are used.|
435426
|||[require-throws](./docs/rules/require-throws.md#readme)|Requires that throw statements are documented|
427+
|:heavy_check_mark:||[require-throws-type](./docs/rules/require-throws-type.md#readme)|Requires a type on the `@throws` tag.|
436428
|:heavy_check_mark:||[require-yields](./docs/rules/require-yields.md#readme)|Requires that yields are documented|
437429
|: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)|
430+
|:heavy_check_mark:||[require-yields-type](./docs/rules/require-yields-type.md#readme)|Requires a type on the `@yields` tag.|
438431
|||[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|
439432
|:heavy_check_mark:|:wrench:|[tag-lines](./docs/rules/tag-lines.md#readme)|Enforces lines (or no lines) between tags|
440433
||:wrench:|[text-escaping](./docs/rules/text-escaping.md#readme)|This rule can auto-escape certain characters that are input within block and tag descriptions|

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

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# `require-next-type`
2+
3+
Requires a type on the (non-standard) `@next` tag.
4+
See the `jsdoc/require-yields` rule for details on this tag.
5+
6+
|||
7+
|---|---|
8+
|Context|everywhere|
9+
|Tags|`next`|
10+
|Recommended|true|
11+
|Settings||
12+
|Options||
13+
14+
## Failing examples
15+
16+
<!-- assertions-failing requireNextType -->
17+
18+
## Passing examples
19+
20+
<!-- assertions-passing requireNextType -->

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

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

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

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

‎README.md

Lines changed: 3 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -101,16 +101,6 @@ export default [
101101
'type',
102102
],
103103
},
104-
throws: {
105-
required: [
106-
'type',
107-
],
108-
},
109-
yields: {
110-
required: [
111-
'type',
112-
],
113-
},
114104
},
115105
*/
116106
}
@@ -456,6 +446,7 @@ non-default-recommended fixer).
456446
|||[require-file-overview](./docs/rules/require-file-overview.md#readme)|By default, requires a single `@file` tag at the beginning of each linted file|
457447
||:wrench:|[require-hyphen-before-param-description](./docs/rules/require-hyphen-before-param-description.md#readme)|Requires a hyphen before `@param` descriptions (and optionally before `@property` descriptions)|
458448
|: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).|
449+
|:heavy_check_mark:||[require-next-type](./docs/rules/require-next-type.md#readme)|Requires a type on the (non-standard) `@next` tag.|
459450
|:heavy_check_mark:|:wrench:|[require-param](./docs/rules/require-param.md#readme)|Requires that all function parameters are documented with a `@param` tag.|
460451
|:heavy_check_mark:||[require-param-description](./docs/rules/require-param-description.md#readme)|Requires that each `@param` tag has a `description` value.|
461452
|:heavy_check_mark:||[require-param-name](./docs/rules/require-param-name.md#readme)|Requires that all `@param` tags have names.|
@@ -470,8 +461,10 @@ non-default-recommended fixer).
470461
|:heavy_check_mark: (off in TS)||[require-returns-type](./docs/rules/require-returns-type.md#readme)|Requires that `@returns` tag has a type value (in curly brackets).|
471462
| || [require-template](./docs/rules/require-template.md#readme) | Requires `@template` tags be present when type parameters are used.|
472463
|||[require-throws](./docs/rules/require-throws.md#readme)|Requires that throw statements are documented|
464+
|:heavy_check_mark:||[require-throws-type](./docs/rules/require-throws-type.md#readme)|Requires a type on the `@throws` tag.|
473465
|:heavy_check_mark:||[require-yields](./docs/rules/require-yields.md#readme)|Requires that yields are documented|
474466
|: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)|
467+
|:heavy_check_mark:||[require-yields-type](./docs/rules/require-yields-type.md#readme)|Requires a type on the `@yields` tag.|
475468
|||[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|
476469
|:heavy_check_mark:|:wrench:|[tag-lines](./docs/rules/tag-lines.md#readme)|Enforces lines (or no lines) between tags|
477470
||:wrench:|[text-escaping](./docs/rules/text-escaping.md#readme)|This rule can auto-escape certain characters that are input within block and tag descriptions|

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

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

‎docs/rules/require-throws-type.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-type"></a>
2+
<a name="require-throws-type"></a>
3+
# <code>require-throws-type</code>
4+
5+
Requires a type on the `@throws` tag.
6+
7+
|||
8+
|---|---|
9+
|Context|everywhere|
10+
|Tags|`throws`|
11+
|Recommended|true|
12+
|Settings||
13+
|Options||
14+
15+
<a name="user-content-require-throws-type-failing-examples"></a>
16+
<a name="require-throws-type-failing-examples"></a>
17+
## Failing examples
18+
19+
The following patterns are considered problems:
20+
21+
````ts
22+
/**
23+
* @throws
24+
*/
25+
// Message: @throws should have a type
26+
````
27+
28+
29+
30+
<a name="user-content-require-throws-type-passing-examples"></a>
31+
<a name="require-throws-type-passing-examples"></a>
32+
## Passing examples
33+
34+
The following patterns are not considered problems:
35+
36+
````ts
37+
/**
38+
* @throws {SomeType}
39+
*/
40+
````
41+

‎docs/rules/require-yields-type.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-type"></a>
2+
<a name="require-yields-type"></a>
3+
# <code>require-yields-type</code>
4+
5+
Requires a type on the `@yields` tag.
6+
7+
|||
8+
|---|---|
9+
|Context|everywhere|
10+
|Tags|`yields`|
11+
|Recommended|true|
12+
|Settings||
13+
|Options||
14+
15+
<a name="user-content-require-yields-type-failing-examples"></a>
16+
<a name="require-yields-type-failing-examples"></a>
17+
## Failing examples
18+
19+
The following patterns are considered problems:
20+
21+
````ts
22+
/**
23+
* @yields
24+
*/
25+
// Message: @yields should have a type
26+
````
27+
28+
29+
30+
<a name="user-content-require-yields-type-passing-examples"></a>
31+
<a name="require-yields-type-passing-examples"></a>
32+
## Passing examples
33+
34+
The following patterns are not considered problems:
35+
36+
````ts
37+
/**
38+
* @yields {SomeType}
39+
*/
40+
````
41+

‎eslint.config.js

Lines changed: 2 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -11,46 +11,17 @@ import globals from 'globals';
1111

1212
const common = {
1313
linterOptions: {
14-
reportUnusedDisableDirectives: 'off',
14+
reportUnusedDisableDirectives: 'error',
15+
reportUnusedInlineConfigs: 'error',
1516
},
1617
};
1718

18-
// /**
19-
// * @param {any} abc Test
20-
// */
21-
// export const a = (abc) => {
22-
// // eslint-disable-next-line no-console -- Testing
23-
// console.log('abc', abc);
24-
// };
25-
2619
export default [
2720
...canonical,
2821
...canonicalJsdoc,
2922
...jsdoc({
3023
config: 'examples-and-default-expressions',
3124
}),
32-
// jsdoc({
33-
// config: 'flat/recommended',
34-
// extraRuleDefinitions: {
35-
// forbid: {
36-
// Any: {
37-
// contexts: [
38-
// {
39-
// comment: 'JsdocBlock:has(JsdocTypeName[value="any"])',
40-
// context: 'any',
41-
// message: '`any` is not allowed; use a more specific type',
42-
// },
43-
// ],
44-
// descriptions: 'Testing here',
45-
// },
46-
// },
47-
// },
48-
// rules: {
49-
// 'jsdoc/forbid-Any': [
50-
// 'error',
51-
// ],
52-
// },
53-
// }),
5425
{
5526
// Must be by itself
5627
ignores: [

‎src/exportParser.js

Lines changed: 0 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -103,8 +103,6 @@ const getIdentifier = function (node, globals, scope, opts) {
103103
/** @type {CreateSymbol} */
104104
let createSymbol; // eslint-disable-line prefer-const
105105

106-
/* eslint-disable complexity -- Temporary */
107-
108106
/**
109107
* @typedef {{
110108
* simpleIdentifier?: boolean
@@ -120,7 +118,6 @@ let createSymbol; // eslint-disable-line prefer-const
120118
* @returns {CreatedNode|null}
121119
*/
122120
const getSymbol = function (node, globals, scope, opt) {
123-
/* eslint-enable complexity -- Temporary */
124121
const opts = opt || {};
125122
/* c8 ignore next */
126123
switch (node.type) {
@@ -478,8 +475,6 @@ const initVariables = function (node, globals, opts) {
478475
}
479476
};
480477

481-
/* eslint-disable complexity -- Temporary */
482-
483478
/**
484479
* Populates variable maps using AST
485480
* @param {import('eslint').Rule.Node|import('@typescript-eslint/types').TSESTree.Node} node
@@ -489,7 +484,6 @@ const initVariables = function (node, globals, opts) {
489484
* @returns {boolean}
490485
*/
491486
const mapVariables = function (node, globals, opt, isExport) {
492-
/* eslint-enable complexity -- Temporary */
493487
/* c8 ignore next */
494488
const opts = opt || {};
495489
/* c8 ignore next */

0 commit comments

Comments
 (0)