Skip to content

Commit 3e86e19

Browse files
brettz9brettz9
committed
feat: export function for building configs
1 parent b2764fc commit 3e86e19

File tree

9 files changed

+415
-323
lines changed

9 files changed

+415
-323
lines changed

‎.README/README.md

Lines changed: 64 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -27,7 +27,68 @@ npm install --save-dev eslint-plugin-jsdoc
2727

2828
## Configuration
2929

30-
### Flat config
30+
### Flat config (procedural)
31+
32+
This is the currently recommended approach.
33+
34+
```js
35+
import jsdoc from 'eslint-plugin-jsdoc';
36+
37+
export default [
38+
...jsdoc({
39+
config: 'flat/recommended',
40+
})
41+
];
42+
```
43+
44+
Or with settings supplied:
45+
46+
```js
47+
import jsdoc from 'eslint-plugin-jsdoc';
48+
49+
export default [
50+
...jsdoc({
51+
config: 'flat/recommended',
52+
// Uncomment this if you wish your `settings` to overwrite the config's own settings;
53+
// otherwise, the default behavior is to merge recursively
54+
// mergeSettings: false,
55+
settings: {
56+
// Do not add a `jsdoc` child object here as you would for regular ESLint `settings`
57+
structuredTags: {
58+
see: {
59+
name: 'namepath-referencing',
60+
required: [
61+
'name',
62+
],
63+
},
64+
},
65+
/*
66+
// The above will be merged by default with the following tags (which are
67+
// being allowed and requiring a type):
68+
structuredTags: {
69+
next: {
70+
required: [
71+
'type',
72+
],
73+
},
74+
throws: {
75+
required: [
76+
'type',
77+
],
78+
},
79+
yields: {
80+
required: [
81+
'type',
82+
],
83+
},
84+
},
85+
*/
86+
}
87+
})
88+
];
89+
```
90+
91+
### Flat config (declarative)
3192

3293
```js
3394
import jsdoc from 'eslint-plugin-jsdoc';
@@ -38,6 +99,7 @@ const config = [
3899
// other configuration objects...
39100
{
40101
files: ['**/*.js'],
102+
// `plugins` here is not necessary if including the above config
41103
plugins: {
42104
jsdoc,
43105
},
@@ -74,7 +136,7 @@ These each only enable mostly or only rules from the recommended starting rules:
74136
- `jsdoc.configs['flat/logical-typescript-error']`: for TypeScript files, with reports set to error
75137
- `jsdoc.configs['flat/logical-typescript-flavor']`: for files using JavaScript syntax and JSDoc types, with reports set to warn
76138
- `jsdoc.configs['flat/logical-typescript-flavor-error']`: for files using JavaScript syntax and JSDoc types, with reports set to error
77-
- **Requirements**: rules that enforce tags exist
139+
- **Requirements**: rules that enforce tags exist or have or don't have types
78140
- `jsdoc.configs['flat/requirements-typescript']`: for TypeScript files, with reports set to warn
79141
- `jsdoc.configs['flat/requirements-typescript-error']`: for TypeScript files, with reports set to error
80142
- `jsdoc.configs['flat/requirements-typescript-flavor']`: for files using JavaScript syntax and JSDoc types, with reports set to warn

‎README.md

Lines changed: 74 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,8 @@ JSDoc linting rules for ESLint.
1212
* [eslint-plugin-jsdoc](#user-content-eslint-plugin-jsdoc)
1313
* [Installation](#user-content-eslint-plugin-jsdoc-installation)
1414
* [Configuration](#user-content-eslint-plugin-jsdoc-configuration)
15-
* [Flat config](#user-content-eslint-plugin-jsdoc-configuration-flat-config)
15+
* [Flat config (procedural)](#user-content-eslint-plugin-jsdoc-configuration-flat-config-procedural)
16+
* [Flat config (declarative)](#user-content-eslint-plugin-jsdoc-configuration-flat-config-declarative)
1617
* [`eslintrc`](#user-content-eslint-plugin-jsdoc-configuration-eslintrc)
1718
* [Options](#user-content-eslint-plugin-jsdoc-options)
1819
* [Settings](#user-content-eslint-plugin-jsdoc-settings)
@@ -43,9 +44,72 @@ npm install --save-dev eslint-plugin-jsdoc
4344
<a name="eslint-plugin-jsdoc-configuration"></a>
4445
## Configuration
4546

46-
<a name="user-content-eslint-plugin-jsdoc-configuration-flat-config"></a>
47-
<a name="eslint-plugin-jsdoc-configuration-flat-config"></a>
48-
### Flat config
47+
<a name="user-content-eslint-plugin-jsdoc-configuration-flat-config-procedural"></a>
48+
<a name="eslint-plugin-jsdoc-configuration-flat-config-procedural"></a>
49+
### Flat config (procedural)
50+
51+
This is the currently recommended approach.
52+
53+
```js
54+
import jsdoc from 'eslint-plugin-jsdoc';
55+
56+
export default [
57+
...jsdoc({
58+
config: 'flat/recommended',
59+
})
60+
];
61+
```
62+
63+
Or with settings supplied:
64+
65+
```js
66+
import jsdoc from 'eslint-plugin-jsdoc';
67+
68+
export default [
69+
...jsdoc({
70+
config: 'flat/recommended',
71+
// Uncomment this if you wish your `settings` to overwrite the config's own settings;
72+
// otherwise, the default behavior is to merge recursively
73+
// mergeSettings: false,
74+
settings: {
75+
// Do not add a `jsdoc` child object here as you would for regular ESLint `settings`
76+
structuredTags: {
77+
see: {
78+
name: 'namepath-referencing',
79+
required: [
80+
'name',
81+
],
82+
},
83+
},
84+
/*
85+
// The above will be merged by default with the following tags (which are
86+
// being allowed and requiring a type):
87+
structuredTags: {
88+
next: {
89+
required: [
90+
'type',
91+
],
92+
},
93+
throws: {
94+
required: [
95+
'type',
96+
],
97+
},
98+
yields: {
99+
required: [
100+
'type',
101+
],
102+
},
103+
},
104+
*/
105+
}
106+
})
107+
];
108+
```
109+
110+
<a name="user-content-eslint-plugin-jsdoc-configuration-flat-config-declarative"></a>
111+
<a name="eslint-plugin-jsdoc-configuration-flat-config-declarative"></a>
112+
### Flat config (declarative)
49113

50114
```js
51115
import jsdoc from 'eslint-plugin-jsdoc';
@@ -56,6 +120,7 @@ const config = [
56120
// other configuration objects...
57121
{
58122
files: ['**/*.js'],
123+
// `plugins` here is not necessary if including the above config
59124
plugins: {
60125
jsdoc,
61126
},
@@ -77,8 +142,8 @@ The general starting rulesets you can extend from in flat config are:
77142
- `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`)
78143
- `jsdoc.configs['flat/recommended-typescript-flavor-error']`: The same, reporting with failing errors instead of mere warnings
79144

80-
<a name="user-content-eslint-plugin-jsdoc-configuration-flat-config-granular-flat-configs"></a>
81-
<a name="eslint-plugin-jsdoc-configuration-flat-config-granular-flat-configs"></a>
145+
<a name="user-content-eslint-plugin-jsdoc-configuration-flat-config-declarative-granular-flat-configs"></a>
146+
<a name="eslint-plugin-jsdoc-configuration-flat-config-declarative-granular-flat-configs"></a>
82147
#### Granular Flat Configs
83148

84149
There also exist several more granular, standalone TypeScript rulesets you can extend from.
@@ -94,7 +159,7 @@ These each only enable mostly or only rules from the recommended starting rules:
94159
- `jsdoc.configs['flat/logical-typescript-error']`: for TypeScript files, with reports set to error
95160
- `jsdoc.configs['flat/logical-typescript-flavor']`: for files using JavaScript syntax and JSDoc types, with reports set to warn
96161
- `jsdoc.configs['flat/logical-typescript-flavor-error']`: for files using JavaScript syntax and JSDoc types, with reports set to error
97-
- **Requirements**: rules that enforce tags exist
162+
- **Requirements**: rules that enforce tags exist or have or don't have types
98163
- `jsdoc.configs['flat/requirements-typescript']`: for TypeScript files, with reports set to warn
99164
- `jsdoc.configs['flat/requirements-typescript-error']`: for TypeScript files, with reports set to error
100165
- `jsdoc.configs['flat/requirements-typescript-flavor']`: for files using JavaScript syntax and JSDoc types, with reports set to warn
@@ -117,8 +182,8 @@ export default [
117182
];
118183
```
119184

120-
<a name="user-content-eslint-plugin-jsdoc-configuration-flat-config-granular-flat-configs-why-certain-rules-were-excluded-from-the-granular-configs"></a>
121-
<a name="eslint-plugin-jsdoc-configuration-flat-config-granular-flat-configs-why-certain-rules-were-excluded-from-the-granular-configs"></a>
185+
<a name="user-content-eslint-plugin-jsdoc-configuration-flat-config-declarative-granular-flat-configs-why-certain-rules-were-excluded-from-the-granular-configs"></a>
186+
<a name="eslint-plugin-jsdoc-configuration-flat-config-declarative-granular-flat-configs-why-certain-rules-were-excluded-from-the-granular-configs"></a>
122187
##### Why certain rules were excluded from the granular configs
123188

124189
A few rules were left out of the granular configs. Here is why:

‎package.json

Lines changed: 4 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,7 @@
1212
"escape-string-regexp": "^4.0.0",
1313
"espree": "^10.4.0",
1414
"esquery": "^1.6.0",
15+
"object-deep-merge": "^1.0.5",
1516
"parse-imports-exports": "^0.2.4",
1617
"semver": "^7.7.2",
1718
"spdx-expression-parse": "^4.0.0"
@@ -21,7 +22,6 @@
2122
"@babel/cli": "^7.28.3",
2223
"@babel/core": "^7.28.4",
2324
"@babel/eslint-parser": "^7.28.4",
24-
"@babel/node": "^7.28.0",
2525
"@babel/plugin-syntax-class-properties": "^7.12.13",
2626
"@babel/plugin-transform-flow-strip-types": "^7.27.1",
2727
"@babel/preset-env": "^7.28.3",
@@ -37,7 +37,6 @@
3737
"@types/esquery": "^1.5.4",
3838
"@types/estree": "^1.0.8",
3939
"@types/json-schema": "^7.0.15",
40-
"@types/lodash.defaultsdeep": "^4.6.9",
4140
"@types/mocha": "^10.0.10",
4241
"@types/node": "^24.3.1",
4342
"@types/semver": "^7.7.1",
@@ -59,7 +58,6 @@
5958
"jsdoc-type-pratt-parser": "^5.1.1",
6059
"json-schema": "^0.4.0",
6160
"lint-staged": "^16.1.6",
62-
"lodash.defaultsdeep": "^4.6.1",
6361
"mocha": "^11.7.2",
6462
"open-editor": "^5.1.0",
6563
"replace": "^1.2.2",
@@ -140,9 +138,9 @@
140138
"tsc": "tsc",
141139
"tsc-build": "tsc -p tsconfig-prod.json",
142140
"build": "rimraf ./dist && NODE_ENV=production babel ./src --out-file-extension .cjs --out-dir ./dist --copy-files --source-maps --ignore ./src/bin/*.js --no-copy-ignored && replace 'require\\(\"\\.(.*?)\\.[^.]*?\"\\)' 'require(\".$1.cjs\")' 'dist' -r --include=\"*.cjs\" && pnpm tsc-build",
143-
"check-docs": "babel-node ./src/bin/generateDocs.js --check",
144-
"create-docs": "pnpm run create-options && babel-node ./src/bin/generateDocs.js",
145-
"create-rule": "babel-node ./src/bin/generateRule.js",
141+
"check-docs": "node ./src/bin/generateDocs.js --check",
142+
"create-docs": "pnpm run create-options && node ./src/bin/generateDocs.js",
143+
"create-rule": "node ./src/bin/generateRule.js",
146144
"create-options": "node ./src/bin/generateOptions.js",
147145
"install-offline": "pnpm install --prefer-offline --no-audit",
148146
"lint": "eslint",

0 commit comments

Comments
 (0)