Skip to content

Commit 1ef0ee8

Browse files
brettz9brettz9
committed
feat(no-undefined-types): only check @template in no-undefined-types for types in "closure" and "typescript" modes; fixes part of #356
BREAKING CHANGE: `@template` has no special meaning for regular jsdoc (is not even allowed by default), so don't check in "jsdoc" mode.
1 parent 42476b2 commit 1ef0ee8

File tree

5 files changed

+85
-11
lines changed

5 files changed

+85
-11
lines changed

‎.README/README.md

Lines changed: 8 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -91,10 +91,14 @@ You can then selectively add to or override the recommended rules.
9191
### Mode
9292

9393
- `settings.jsdoc.mode` - Set to `jsdoc` (the default), `typescript`, or `closure`.
94-
Currently is used for checking preferred tag names and in the `check-tag-names`
95-
rule. For type-checking rules, the setting also determines which tags will be
96-
checked for types (Closure allows types on some tags which the others do not,
97-
so these tags will additionally be checked in "closure" mode).
94+
Currently is used for the following:
95+
- Determine valid tags for `check-tag-names`
96+
- Only check `@template` in `no-undefined-types` for types in "closure" and
97+
"typescript" modes
98+
- For type-checking rules, determine which tags will be checked for types
99+
(Closure allows types on some tags which the others do not,
100+
so these tags will additionally be checked in "closure" mode)
101+
- Check preferred tag names
98102

99103
### Alias Preference
100104

‎.README/rules/no-undefined-types.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@ In addition to considering globals found in code (or in ESLint-indicated
1111
name(path) definitions to also serve as a potential "type" for checking
1212
the tag types in the table below:
1313

14-
`@callback`, `@class` (or `@constructor`), `@constant` (or `@const`), `@event`, `@external` (or `@host`), `@function` (or `@func` or `@method`), `@interface`, `@member` (or `@var`), `@mixin`, `@name`, `@namespace`, `@template` (for Closure/TypeScript), `@typedef`.
14+
`@callback`, `@class` (or `@constructor`), `@constant` (or `@const`), `@event`, `@external` (or `@host`), `@function` (or `@func` or `@method`), `@interface`, `@member` (or `@var`), `@mixin`, `@name`, `@namespace`, `@template` (for "closure" or "typescript" `settings.jsdoc.mode` only), `@typedef`.
1515

1616
The following tags will also be checked but only when the mode is `closure`:
1717

‎README.md

Lines changed: 27 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -133,10 +133,14 @@ You can then selectively add to or override the recommended rules.
133133
### Mode
134134

135135
- `settings.jsdoc.mode` - Set to `jsdoc` (the default), `typescript`, or `closure`.
136-
Currently is used for checking preferred tag names and in the `check-tag-names`
137-
rule. For type-checking rules, the setting also determines which tags will be
138-
checked for types (Closure allows types on some tags which the others do not,
139-
so these tags will additionally be checked in "closure" mode).
136+
Currently is used for the following:
137+
- Determine valid tags for `check-tag-names`
138+
- Only check `@template` in `no-undefined-types` for types in "closure" and
139+
"typescript" modes
140+
- For type-checking rules, determine which tags will be checked for types
141+
(Closure allows types on some tags which the others do not,
142+
so these tags will additionally be checked in "closure" mode)
143+
- Check preferred tag names
140144

141145
<a name="eslint-plugin-jsdoc-settings-alias-preference"></a>
142146
### Alias Preference
@@ -3915,7 +3919,7 @@ In addition to considering globals found in code (or in ESLint-indicated
39153919
name(path) definitions to also serve as a potential "type" for checking
39163920
the tag types in the table below:
39173921

3918-
`@callback`, `@class` (or `@constructor`), `@constant` (or `@const`), `@event`, `@external` (or `@host`), `@function` (or `@func` or `@method`), `@interface`, `@member` (or `@var`), `@mixin`, `@name`, `@namespace`, `@template` (for Closure/TypeScript), `@typedef`.
3922+
`@callback`, `@class` (or `@constructor`), `@constant` (or `@const`), `@event`, `@external` (or `@host`), `@function` (or `@func` or `@method`), `@interface`, `@member` (or `@var`), `@mixin`, `@name`, `@namespace`, `@template` (for "closure" or "typescript" `settings.jsdoc.mode` only), `@typedef`.
39193923

39203924
The following tags will also be checked but only when the mode is `closure`:
39213925

@@ -4018,6 +4022,7 @@ function quux(foo, bar, baz) {
40184022
*/
40194023
function foo (bar) {
40204024
};
4025+
// Settings: {"jsdoc":{"mode":"closure"}}
40214026
// Message: The type 'WRONG_TEMPLATE_TYPE' is undefined.
40224027

40234028
class Foo {
@@ -4047,6 +4052,7 @@ class Bar {
40474052
validTemplateReference () {
40484053
}
40494054
}
4055+
// Settings: {"jsdoc":{"mode":"typescript"}}
40504056
// Message: The type 'TEMPLATE_TYPE' is undefined.
40514057

40524058
/**
@@ -4056,6 +4062,19 @@ var quux = {
40564062

40574063
};
40584064
// Message: The type 'strnig' is undefined.
4065+
4066+
/**
4067+
* @template TEMPLATE_TYPE_A, TEMPLATE_TYPE_B
4068+
*/
4069+
class Foo {
4070+
/**
4071+
* @param {TEMPLATE_TYPE_A} baz
4072+
* @return {TEMPLATE_TYPE_B}
4073+
*/
4074+
bar (baz) {
4075+
}
4076+
}
4077+
// Message: The type 'TEMPLATE_TYPE_A' is undefined.
40594078
````
40604079

40614080
The following patterns are not considered problems:
@@ -4213,6 +4232,7 @@ function quux(foo, bar, baz) {
42134232
*/
42144233
function foo (bar) {
42154234
};
4235+
// Settings: {"jsdoc":{"mode":"closure"}}
42164236

42174237
/**
42184238
* @template TEMPLATE_TYPE
@@ -4224,6 +4244,7 @@ class Foo {
42244244
bar () {
42254245
}
42264246
}
4247+
// Settings: {"jsdoc":{"mode":"closure"}}
42274248

42284249
/**
42294250
* @template TEMPLATE_TYPE_A, TEMPLATE_TYPE_B
@@ -4236,6 +4257,7 @@ class Foo {
42364257
bar (baz) {
42374258
}
42384259
}
4260+
// Settings: {"jsdoc":{"mode":"closure"}}
42394261

42404262
/****/
42414263

‎src/rules/noUndefinedTypes.js

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -103,7 +103,7 @@ export default iterateJsdoc(({
103103
.concat(typedefDeclarations)
104104
.concat(definedTypes)
105105
.concat(definedPreferredTypes)
106-
.concat(closureGenericTypes);
106+
.concat(settings.mode === 'jsdoc' ? [] : closureGenericTypes);
107107

108108
const jsdocTagsWithPossibleType = utils.filterTags((tag) => {
109109
return utils.tagMightHaveAType(tag.tag);

‎test/rules/assertions/noUndefinedTypes.js

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -163,6 +163,11 @@ export default {
163163
message: 'The type \'WRONG_TEMPLATE_TYPE\' is undefined.',
164164
},
165165
],
166+
settings: {
167+
jsdoc: {
168+
mode: 'closure',
169+
},
170+
},
166171
},
167172
{
168173
code: `
@@ -208,6 +213,11 @@ export default {
208213
message: 'The type \'TEMPLATE_TYPE\' is undefined.',
209214
},
210215
],
216+
settings: {
217+
jsdoc: {
218+
mode: 'typescript',
219+
},
220+
},
211221
},
212222
{
213223
code: `
@@ -228,6 +238,29 @@ export default {
228238
'no-undef': 'error',
229239
},
230240
},
241+
{
242+
code: `
243+
/**
244+
* @template TEMPLATE_TYPE_A, TEMPLATE_TYPE_B
245+
*/
246+
class Foo {
247+
/**
248+
* @param {TEMPLATE_TYPE_A} baz
249+
* @return {TEMPLATE_TYPE_B}
250+
*/
251+
bar (baz) {
252+
}
253+
}
254+
`,
255+
errors: [
256+
{
257+
message: 'The type \'TEMPLATE_TYPE_A\' is undefined.',
258+
},
259+
{
260+
message: 'The type \'TEMPLATE_TYPE_B\' is undefined.',
261+
},
262+
],
263+
},
231264
],
232265
valid: [
233266
{
@@ -472,6 +505,11 @@ export default {
472505
function foo (bar) {
473506
};
474507
`,
508+
settings: {
509+
jsdoc: {
510+
mode: 'closure',
511+
},
512+
},
475513
},
476514
{
477515
code: `
@@ -486,6 +524,11 @@ export default {
486524
}
487525
}
488526
`,
527+
settings: {
528+
jsdoc: {
529+
mode: 'closure',
530+
},
531+
},
489532
},
490533
{
491534
code: `
@@ -501,6 +544,11 @@ export default {
501544
}
502545
}
503546
`,
547+
settings: {
548+
jsdoc: {
549+
mode: 'closure',
550+
},
551+
},
504552
},
505553
{
506554
code: `

0 commit comments

Comments
 (0)