Skip to content

Commit 8a37b83

Browse files
brettz9brettz9
committed
feat: export function for building configs
1 parent b2764fc commit 8a37b83

File tree

9 files changed

+407
-323
lines changed

9 files changed

+407
-323
lines changed

‎.README/README.md

Lines changed: 60 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -27,7 +27,64 @@ 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 jsdoc({
38+
config: 'flat/recommended',
39+
});
40+
```
41+
42+
Or with settings supplied:
43+
44+
```js
45+
import jsdoc from 'eslint-plugin-jsdoc';
46+
47+
export default jsdoc({
48+
config: 'flat/recommended',
49+
// Uncomment this if you wish your `settings` to overwrite the config's own settings;
50+
// otherwise, the default behavior is to merge recursively
51+
// mergeSettings: false,
52+
settings: {
53+
// Do not add a `jsdoc` child object here as you would for regular ESLint `settings`
54+
structuredTags: {
55+
see: {
56+
name: 'namepath-referencing',
57+
required: [
58+
'name',
59+
],
60+
},
61+
},
62+
/*
63+
// The above will be merged by default with the following tags (which are
64+
// being allowed and requiring a type):
65+
structuredTags: {
66+
next: {
67+
required: [
68+
'type',
69+
],
70+
},
71+
throws: {
72+
required: [
73+
'type',
74+
],
75+
},
76+
yields: {
77+
required: [
78+
'type',
79+
],
80+
},
81+
},
82+
*/
83+
}
84+
});
85+
```
86+
87+
### Flat config (declarative)
3188

3289
```js
3390
import jsdoc from 'eslint-plugin-jsdoc';
@@ -38,6 +95,7 @@ const config = [
3895
// other configuration objects...
3996
{
4097
files: ['**/*.js'],
98+
// `plugins` here is not necessary if including the above config
4199
plugins: {
42100
jsdoc,
43101
},
@@ -74,7 +132,7 @@ These each only enable mostly or only rules from the recommended starting rules:
74132
- `jsdoc.configs['flat/logical-typescript-error']`: for TypeScript files, with reports set to error
75133
- `jsdoc.configs['flat/logical-typescript-flavor']`: for files using JavaScript syntax and JSDoc types, with reports set to warn
76134
- `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
135+
- **Requirements**: rules that enforce tags exist or have or don't have types
78136
- `jsdoc.configs['flat/requirements-typescript']`: for TypeScript files, with reports set to warn
79137
- `jsdoc.configs['flat/requirements-typescript-error']`: for TypeScript files, with reports set to error
80138
- `jsdoc.configs['flat/requirements-typescript-flavor']`: for files using JavaScript syntax and JSDoc types, with reports set to warn

‎README.md

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

50110
```js
51111
import jsdoc from 'eslint-plugin-jsdoc';
@@ -56,6 +116,7 @@ const config = [
56116
// other configuration objects...
57117
{
58118
files: ['**/*.js'],
119+
// `plugins` here is not necessary if including the above config
59120
plugins: {
60121
jsdoc,
61122
},
@@ -77,8 +138,8 @@ The general starting rulesets you can extend from in flat config are:
77138
- `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`)
78139
- `jsdoc.configs['flat/recommended-typescript-flavor-error']`: The same, reporting with failing errors instead of mere warnings
79140

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>
141+
<a name="user-content-eslint-plugin-jsdoc-configuration-flat-config-declarative-granular-flat-configs"></a>
142+
<a name="eslint-plugin-jsdoc-configuration-flat-config-declarative-granular-flat-configs"></a>
82143
#### Granular Flat Configs
83144

84145
There also exist several more granular, standalone TypeScript rulesets you can extend from.
@@ -94,7 +155,7 @@ These each only enable mostly or only rules from the recommended starting rules:
94155
- `jsdoc.configs['flat/logical-typescript-error']`: for TypeScript files, with reports set to error
95156
- `jsdoc.configs['flat/logical-typescript-flavor']`: for files using JavaScript syntax and JSDoc types, with reports set to warn
96157
- `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
158+
- **Requirements**: rules that enforce tags exist or have or don't have types
98159
- `jsdoc.configs['flat/requirements-typescript']`: for TypeScript files, with reports set to warn
99160
- `jsdoc.configs['flat/requirements-typescript-error']`: for TypeScript files, with reports set to error
100161
- `jsdoc.configs['flat/requirements-typescript-flavor']`: for files using JavaScript syntax and JSDoc types, with reports set to warn
@@ -117,8 +178,8 @@ export default [
117178
];
118179
```
119180

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

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