Skip to content

Commit 9abc1a6

Browse files
brettz9brettz9
committed
feat: export function for building configs
1 parent b2764fc commit 9abc1a6

File tree

9 files changed

+417
-323
lines changed

9 files changed

+417
-323
lines changed

‎.README/README.md‎

Lines changed: 65 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -27,7 +27,69 @@ 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+
// Since the recommended config has been chosen, the above settings will
67+
// be merged by default with the following (which are tags that are
68+
// being allowed and requiring a type):
69+
structuredTags: {
70+
next: {
71+
required: [
72+
'type',
73+
],
74+
},
75+
throws: {
76+
required: [
77+
'type',
78+
],
79+
},
80+
yields: {
81+
required: [
82+
'type',
83+
],
84+
},
85+
},
86+
*/
87+
}
88+
})
89+
];
90+
```
91+
92+
### Flat config (declarative)
3193

3294
```js
3395
import jsdoc from 'eslint-plugin-jsdoc';
@@ -38,6 +100,7 @@ const config = [
38100
// other configuration objects...
39101
{
40102
files: ['**/*.js'],
103+
// `plugins` here is not necessary if including the above config
41104
plugins: {
42105
jsdoc,
43106
},
@@ -74,7 +137,7 @@ These each only enable mostly or only rules from the recommended starting rules:
74137
- `jsdoc.configs['flat/logical-typescript-error']`: for TypeScript files, with reports set to error
75138
- `jsdoc.configs['flat/logical-typescript-flavor']`: for files using JavaScript syntax and JSDoc types, with reports set to warn
76139
- `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
140+
- **Requirements**: rules that enforce tags exist or have or don't have types
78141
- `jsdoc.configs['flat/requirements-typescript']`: for TypeScript files, with reports set to warn
79142
- `jsdoc.configs['flat/requirements-typescript-error']`: for TypeScript files, with reports set to error
80143
- `jsdoc.configs['flat/requirements-typescript-flavor']`: for files using JavaScript syntax and JSDoc types, with reports set to warn

‎README.md‎

Lines changed: 75 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,73 @@ 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+
// Since the recommended config has been chosen, the above settings will
86+
// be merged by default with the following (which are tags that are
87+
// being allowed and requiring a type):
88+
structuredTags: {
89+
next: {
90+
required: [
91+
'type',
92+
],
93+
},
94+
throws: {
95+
required: [
96+
'type',
97+
],
98+
},
99+
yields: {
100+
required: [
101+
'type',
102+
],
103+
},
104+
},
105+
*/
106+
}
107+
})
108+
];
109+
```
110+
111+
<a name="user-content-eslint-plugin-jsdoc-configuration-flat-config-declarative"></a>
112+
<a name="eslint-plugin-jsdoc-configuration-flat-config-declarative"></a>
113+
### Flat config (declarative)
49114

50115
```js
51116
import jsdoc from 'eslint-plugin-jsdoc';
@@ -56,6 +121,7 @@ const config = [
56121
// other configuration objects...
57122
{
58123
files: ['**/*.js'],
124+
// `plugins` here is not necessary if including the above config
59125
plugins: {
60126
jsdoc,
61127
},
@@ -77,8 +143,8 @@ The general starting rulesets you can extend from in flat config are:
77143
- `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`)
78144
- `jsdoc.configs['flat/recommended-typescript-flavor-error']`: The same, reporting with failing errors instead of mere warnings
79145

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>
146+
<a name="user-content-eslint-plugin-jsdoc-configuration-flat-config-declarative-granular-flat-configs"></a>
147+
<a name="eslint-plugin-jsdoc-configuration-flat-config-declarative-granular-flat-configs"></a>
82148
#### Granular Flat Configs
83149

84150
There also exist several more granular, standalone TypeScript rulesets you can extend from.
@@ -94,7 +160,7 @@ These each only enable mostly or only rules from the recommended starting rules:
94160
- `jsdoc.configs['flat/logical-typescript-error']`: for TypeScript files, with reports set to error
95161
- `jsdoc.configs['flat/logical-typescript-flavor']`: for files using JavaScript syntax and JSDoc types, with reports set to warn
96162
- `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
163+
- **Requirements**: rules that enforce tags exist or have or don't have types
98164
- `jsdoc.configs['flat/requirements-typescript']`: for TypeScript files, with reports set to warn
99165
- `jsdoc.configs['flat/requirements-typescript-error']`: for TypeScript files, with reports set to error
100166
- `jsdoc.configs['flat/requirements-typescript-flavor']`: for files using JavaScript syntax and JSDoc types, with reports set to warn
@@ -117,8 +183,8 @@ export default [
117183
];
118184
```
119185

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>
186+
<a name="user-content-eslint-plugin-jsdoc-configuration-flat-config-declarative-granular-flat-configs-why-certain-rules-were-excluded-from-the-granular-configs"></a>
187+
<a name="eslint-plugin-jsdoc-configuration-flat-config-declarative-granular-flat-configs-why-certain-rules-were-excluded-from-the-granular-configs"></a>
122188
##### Why certain rules were excluded from the granular configs
123189

124190
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)