Skip to content

Commit a96bc7c

Browse files
manbearwizbrettz9
manbearwiz
authored and
brettz9
committed
feat(tsdoc-ruleset): add recommended TSDoc ruleset
feat(tsdoc-ruleset): add recommended TSDoc ruleset
1 parent 26276d4 commit a96bc7c

4 files changed

Lines changed: 94 additions & 0 deletions

File tree

‎.README/README.md‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -138,6 +138,8 @@ The general starting rulesets you can extend from in flat config are:
138138
- `jsdoc.configs['flat/recommended-typescript-error']`: The same, reporting with failing errors instead of mere warnings
139139
- `jsdoc.configs['flat/recommended-typescript-flavor']`: A similar recommended starting list, adjusted for projects using JavaScript syntax (source files that are still `.js`) but using TypeScript flavor within JSDoc (i.e., the default "typescript" `mode` in `eslint-plugin-jsdoc`)
140140
- `jsdoc.configs['flat/recommended-typescript-flavor-error']`: The same, reporting with failing errors instead of mere warnings
141+
- `jsdoc.configs['flat/recommended-tsdoc']`: Like `flat/recommended-typescript` but with `require-throws-type`, `require-yields-type`, and `require-next-type` turned off, for use with [TSDoc](https://tsdoc.org/) (e.g., [TypeDoc](https://typedoc.org/))
142+
- `jsdoc.configs['flat/recommended-tsdoc-error']`: The same, reporting with failing errors instead of mere warnings
141143
- `jsdoc.configs['flat/recommended-mixed']`: A combination of `flat/recommended-typescript-flavor` and `flat/recommended-typescript` with automatic assignment of subconfig based on file extension (`**/*.{js,jsx,cjs,mjs}` and `**/*.{ts,tsx,cts,mts}`, respectively)
142144

143145
#### Granular Flat Configs
@@ -351,6 +353,26 @@ use:
351353
}
352354
```
353355

356+
If you are using [TSDoc](https://tsdoc.org/) (e.g., with [TSDoc](https://tsdoc.org/) or
357+
[TypeDoc](https://typedoc.org/)), you may use the `tsdoc` config, which is like
358+
`recommended-typescript` but additionally turns off `require-throws-type`,
359+
`require-yields-type`, and `require-next-type` (since TSDoc does not support
360+
`{Type}` annotations on those tags):
361+
362+
```json
363+
{
364+
"extends": ["plugin:jsdoc/recommended-tsdoc"]
365+
}
366+
```
367+
368+
...or to report with failing errors instead of mere warnings:
369+
370+
```json
371+
{
372+
"extends": ["plugin:jsdoc/recommended-tsdoc-error"]
373+
}
374+
```
375+
354376
## Options
355377

356378
Rules may, as per the [ESLint user guide](https://eslint.org/docs/user-guide/configuring), have their own individual options. In `eslint-plugin-jsdoc`, a few options,

‎README.md‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -159,6 +159,8 @@ The general starting rulesets you can extend from in flat config are:
159159
- `jsdoc.configs['flat/recommended-typescript-error']`: The same, reporting with failing errors instead of mere warnings
160160
- `jsdoc.configs['flat/recommended-typescript-flavor']`: A similar recommended starting list, adjusted for projects using JavaScript syntax (source files that are still `.js`) but using TypeScript flavor within JSDoc (i.e., the default "typescript" `mode` in `eslint-plugin-jsdoc`)
161161
- `jsdoc.configs['flat/recommended-typescript-flavor-error']`: The same, reporting with failing errors instead of mere warnings
162+
- `jsdoc.configs['flat/recommended-tsdoc']`: Like `flat/recommended-typescript` but with `require-throws-type`, `require-yields-type`, and `require-next-type` turned off, for use with [TSDoc](https://tsdoc.org/) (e.g., [TypeDoc](https://typedoc.org/))
163+
- `jsdoc.configs['flat/recommended-tsdoc-error']`: The same, reporting with failing errors instead of mere warnings
162164
- `jsdoc.configs['flat/recommended-mixed']`: A combination of `flat/recommended-typescript-flavor` and `flat/recommended-typescript` with automatic assignment of subconfig based on file extension (`**/*.{js,jsx,cjs,mjs}` and `**/*.{ts,tsx,cts,mts}`, respectively)
163165

164166
<a name="user-content-eslint-plugin-jsdoc-configuration-flat-config-declarative-granular-flat-configs"></a>
@@ -378,6 +380,26 @@ use:
378380
}
379381
```
380382

383+
If you are using [TSDoc](https://tsdoc.org/) (e.g., with [TSDoc](https://tsdoc.org/) or
384+
[TypeDoc](https://typedoc.org/)), you may use the `tsdoc` config, which is like
385+
`recommended-typescript` but additionally turns off `require-throws-type`,
386+
`require-yields-type`, and `require-next-type` (since TSDoc does not support
387+
`{Type}` annotations on those tags):
388+
389+
```json
390+
{
391+
"extends": ["plugin:jsdoc/recommended-tsdoc"]
392+
}
393+
```
394+
395+
...or to report with failing errors instead of mere warnings:
396+
397+
```json
398+
{
399+
"extends": ["plugin:jsdoc/recommended-tsdoc-error"]
400+
}
401+
```
402+
381403
<a name="user-content-eslint-plugin-jsdoc-options"></a>
382404
<a name="eslint-plugin-jsdoc-options"></a>
383405
## Options

‎src/index-cjs.js‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -394,6 +394,27 @@ const createRecommendedTypeScriptRuleset = (warnOrError, flatName) => {
394394
};
395395
};
396396

397+
/**
398+
* @param {"warn"|"error"} warnOrError
399+
* @param {string} [flatName]
400+
* @returns {import('eslint').Linter.Config}
401+
*/
402+
const createRecommendedTsDocRuleset = (warnOrError, flatName) => {
403+
const ruleset = createRecommendedTypeScriptRuleset(warnOrError, flatName);
404+
405+
return {
406+
...ruleset,
407+
rules: {
408+
...ruleset.rules,
409+
/* eslint-disable @stylistic/indent -- Extra indent to avoid use by auto-rule-editing */
410+
'jsdoc/require-next-type': 'off',
411+
'jsdoc/require-throws-type': 'off',
412+
'jsdoc/require-yields-type': 'off',
413+
/* eslint-enable @stylistic/indent */
414+
},
415+
};
416+
};
417+
397418
/**
398419
* @param {"warn"|"error"} warnOrError
399420
* @param {string} [flatName]
@@ -543,13 +564,17 @@ index.configs['recommended-typescript'] = createRecommendedTypeScriptRuleset('wa
543564
index.configs['recommended-typescript-error'] = createRecommendedTypeScriptRuleset('error');
544565
index.configs['recommended-typescript-flavor'] = createRecommendedTypeScriptFlavorRuleset('warn');
545566
index.configs['recommended-typescript-flavor-error'] = createRecommendedTypeScriptFlavorRuleset('error');
567+
index.configs['recommended-tsdoc'] = createRecommendedTsDocRuleset('warn');
568+
index.configs['recommended-tsdoc-error'] = createRecommendedTsDocRuleset('error');
546569

547570
index.configs['flat/recommended'] = createRecommendedRuleset('warn', 'flat/recommended');
548571
index.configs['flat/recommended-error'] = createRecommendedRuleset('error', 'flat/recommended-error');
549572
index.configs['flat/recommended-typescript'] = createRecommendedTypeScriptRuleset('warn', 'flat/recommended-typescript');
550573
index.configs['flat/recommended-typescript-error'] = createRecommendedTypeScriptRuleset('error', 'flat/recommended-typescript-error');
551574
index.configs['flat/recommended-typescript-flavor'] = createRecommendedTypeScriptFlavorRuleset('warn', 'flat/recommended-typescript-flavor');
552575
index.configs['flat/recommended-typescript-flavor-error'] = createRecommendedTypeScriptFlavorRuleset('error', 'flat/recommended-typescript-flavor-error');
576+
index.configs['flat/recommended-tsdoc'] = createRecommendedTsDocRuleset('warn', 'flat/recommended-tsdoc');
577+
index.configs['flat/recommended-tsdoc-error'] = createRecommendedTsDocRuleset('error', 'flat/recommended-tsdoc-error');
553578

554579
index.configs['flat/contents-typescript'] = createContentsTypescriptRuleset('warn', 'flat/contents-typescript');
555580
index.configs['flat/contents-typescript-error'] = createContentsTypescriptRuleset('error', 'flat/contents-typescript-error');

‎src/index.js‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -400,6 +400,27 @@ const createRecommendedTypeScriptRuleset = (warnOrError, flatName) => {
400400
};
401401
};
402402

403+
/**
404+
* @param {"warn"|"error"} warnOrError
405+
* @param {string} [flatName]
406+
* @returns {import('eslint').Linter.Config}
407+
*/
408+
const createRecommendedTsDocRuleset = (warnOrError, flatName) => {
409+
const ruleset = createRecommendedTypeScriptRuleset(warnOrError, flatName);
410+
411+
return {
412+
...ruleset,
413+
rules: {
414+
...ruleset.rules,
415+
/* eslint-disable @stylistic/indent -- Extra indent to avoid use by auto-rule-editing */
416+
'jsdoc/require-next-type': 'off',
417+
'jsdoc/require-throws-type': 'off',
418+
'jsdoc/require-yields-type': 'off',
419+
/* eslint-enable @stylistic/indent */
420+
},
421+
};
422+
};
423+
403424
/**
404425
* @param {"warn"|"error"} warnOrError
405426
* @param {string} [flatName]
@@ -549,13 +570,17 @@ index.configs['recommended-typescript'] = createRecommendedTypeScriptRuleset('wa
549570
index.configs['recommended-typescript-error'] = createRecommendedTypeScriptRuleset('error');
550571
index.configs['recommended-typescript-flavor'] = createRecommendedTypeScriptFlavorRuleset('warn');
551572
index.configs['recommended-typescript-flavor-error'] = createRecommendedTypeScriptFlavorRuleset('error');
573+
index.configs['recommended-tsdoc'] = createRecommendedTsDocRuleset('warn');
574+
index.configs['recommended-tsdoc-error'] = createRecommendedTsDocRuleset('error');
552575

553576
index.configs['flat/recommended'] = createRecommendedRuleset('warn', 'flat/recommended');
554577
index.configs['flat/recommended-error'] = createRecommendedRuleset('error', 'flat/recommended-error');
555578
index.configs['flat/recommended-typescript'] = createRecommendedTypeScriptRuleset('warn', 'flat/recommended-typescript');
556579
index.configs['flat/recommended-typescript-error'] = createRecommendedTypeScriptRuleset('error', 'flat/recommended-typescript-error');
557580
index.configs['flat/recommended-typescript-flavor'] = createRecommendedTypeScriptFlavorRuleset('warn', 'flat/recommended-typescript-flavor');
558581
index.configs['flat/recommended-typescript-flavor-error'] = createRecommendedTypeScriptFlavorRuleset('error', 'flat/recommended-typescript-flavor-error');
582+
index.configs['flat/recommended-tsdoc'] = createRecommendedTsDocRuleset('warn', 'flat/recommended-tsdoc');
583+
index.configs['flat/recommended-tsdoc-error'] = createRecommendedTsDocRuleset('error', 'flat/recommended-tsdoc-error');
559584

560585
index.configs['flat/contents-typescript'] = createContentsTypescriptRuleset('warn', 'flat/contents-typescript');
561586
index.configs['flat/contents-typescript-error'] = createContentsTypescriptRuleset('error', 'flat/contents-typescript-error');

0 commit comments

Comments
 (0)