Skip to content

Commit 09ee4ab

Browse files
authored
feat(require-template): add exemptedBy; fixes #1460 (#1463)
1 parent b4c9b58 commit 09ee4ab

File tree

4 files changed

+75
-2
lines changed

4 files changed

+75
-2
lines changed

.README/rules/require-template.md

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -38,13 +38,21 @@ templates of this format:
3838

3939
Defaults to `false`.
4040

41+
### `exemptedBy`
42+
43+
Array of tags (e.g., `['type']`) whose presence on the document
44+
block avoids the need for a `@template`. Defaults to an array with
45+
`inheritdoc`. If you set this array, it will overwrite the default,
46+
so be sure to add back `inheritdoc` if you wish its presence to cause
47+
exemption of the rule.
48+
4149
|||
4250
|---|---|
4351
|Context|everywhere|
4452
|Tags|`template`|
4553
|Recommended|false|
4654
|Settings||
47-
|Options|`requireSeparateTemplates`|
55+
|Options|`exemptedBy`, `requireSeparateTemplates`|
4856

4957
## Failing examples
5058

docs/rules/require-template.md

Lines changed: 23 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -44,13 +44,23 @@ templates of this format:
4444

4545
Defaults to `false`.
4646

47+
<a name="user-content-require-template-options-exemptedby"></a>
48+
<a name="require-template-options-exemptedby"></a>
49+
### <code>exemptedBy</code>
50+
51+
Array of tags (e.g., `['type']`) whose presence on the document
52+
block avoids the need for a `@template`. Defaults to an array with
53+
`inheritdoc`. If you set this array, it will overwrite the default,
54+
so be sure to add back `inheritdoc` if you wish its presence to cause
55+
exemption of the rule.
56+
4757
|||
4858
|---|---|
4959
|Context|everywhere|
5060
|Tags|`template`|
5161
|Recommended|false|
5262
|Settings||
53-
|Options|`requireSeparateTemplates`|
63+
|Options|`exemptedBy`, `requireSeparateTemplates`|
5464

5565
<a name="user-content-require-template-failing-examples"></a>
5666
<a name="require-template-failing-examples"></a>
@@ -362,5 +372,17 @@ export default class <NumType> {
362372
* @property {U} aNumber number
363373
* @property {string} parentPath path
364374
*/
375+
376+
/**
377+
* @type {Something}
378+
*/
379+
type Pairs<D, V> = [D, V | undefined];
380+
// "jsdoc/require-template": ["error"|"warn", {"exemptedBy":["type"]}]
381+
382+
/**
383+
* @inheritdoc
384+
* @typedef {[D, V | undefined]} Pairs
385+
*/
386+
// "jsdoc/require-template": ["error"|"warn", {"exemptedBy":["inheritdoc"]}]
365387
````
366388

src/rules/requireTemplate.js

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,10 @@ export default iterateJsdoc(({
1212
settings,
1313
utils,
1414
}) => {
15+
if (utils.avoidDocs()) {
16+
return;
17+
}
18+
1519
const {
1620
requireSeparateTemplates = false,
1721
} = context.options[0] || {};
@@ -189,6 +193,12 @@ export default iterateJsdoc(({
189193
{
190194
additionalProperties: false,
191195
properties: {
196+
exemptedBy: {
197+
items: {
198+
type: 'string',
199+
},
200+
type: 'array',
201+
},
192202
requireSeparateTemplates: {
193203
type: 'boolean',
194204
},

test/rules/assertions/requireTemplate.js

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -645,5 +645,38 @@ export default /** @type {import('../index.js').TestCases} */ ({
645645
*/
646646
`,
647647
},
648+
{
649+
code: `
650+
/**
651+
* @type {Something}
652+
*/
653+
type Pairs<D, V> = [D, V | undefined];
654+
`,
655+
languageOptions: {
656+
parser: typescriptEslintParser,
657+
},
658+
options: [
659+
{
660+
exemptedBy: [
661+
'type',
662+
],
663+
},
664+
],
665+
},
666+
{
667+
code: `
668+
/**
669+
* @inheritdoc
670+
* @typedef {[D, V | undefined]} Pairs
671+
*/
672+
`,
673+
options: [
674+
{
675+
exemptedBy: [
676+
'inheritdoc',
677+
],
678+
},
679+
],
680+
},
648681
],
649682
});

0 commit comments

Comments
 (0)