Skip to content

Commit dc88471

Browse files
brettz9brettz9
committed
docs: add docs
1 parent 78d9d3d commit dc88471

File tree

6 files changed

+180
-2
lines changed

6 files changed

+180
-2
lines changed

‎.README/README.md

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -101,7 +101,13 @@ export default [
101101

102102
A `plugins` property can also be supplied to merge with the resulting `jsdoc` plugin.
103103

104-
Other config properties such as `files`, `ignores`, etc. are also copied over.
104+
Other config properties such as `files`, `ignores`, etc. are also copied over,
105+
though noting that if the specified config produces an array, they will not
106+
currently function.
107+
108+
There is also a `extraRuleDefinitions.forbid` option, the details of which are
109+
explained in the [Advanced](./docs/advanced.md#forbidding-structures) docs
110+
(under creating your own rules and forbidding structures).
105111

106112
### Flat config (declarative)
107113

‎.README/advanced.md

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -86,3 +86,79 @@ we have
8686
to the selector you wish so as to get messages reported in the bottom right
8787
pane which match your [esquery](https://github.com/estools/esquery/#readme)
8888
selector).
89+
90+
### Creating your own rules
91+
92+
#### Forbidding structures
93+
94+
Although `jsdoc/no-restricted-syntax` is available for restricting certain syntax,
95+
it comes at a cost that, no matter how many restrictions one adds, one can only
96+
disable a single restriction by disabling them all.
97+
98+
With the `extraRuleDefinitions.forbid` option, one can add information that is used
99+
to create extra individual rules forbidding specific structures, and these rules can
100+
then be selectively enabled and optionally disabled on a case-by-case basis.
101+
102+
For each `forbid` key, add the name of the context (this will be appended to
103+
`forbid-` to decide the name of the rule, so with "Any" as the key, the rule
104+
created will be `forbid-Any`). Then provide an optional `description` key
105+
(which will be used for the created rule's `meta.docs.description`) and the
106+
`contexts` array. See the `jsdoc/restricted-syntax` rule for more details.
107+
108+
```js
109+
import {jsdoc} from 'eslint-plugin-jsdoc';
110+
111+
export default [
112+
jsdoc({
113+
config: 'flat/recommended',
114+
extraRuleDefinitions: {
115+
forbid: {
116+
Any: {
117+
contexts: [
118+
{
119+
comment: 'JsdocBlock:has(JsdocTypeName[value="any"])',
120+
context: 'any',
121+
message: '`any` is not allowed; use a more specific type',
122+
},
123+
],
124+
descriptions: 'Testing here',
125+
},
126+
Function: {
127+
contexts: [
128+
{
129+
comment: 'JsdocBlock:has(JsdocTypeName[value="Function"])',
130+
context: 'any',
131+
message: '`Function` is not allowed; use a more specific type',
132+
},
133+
],
134+
},
135+
},
136+
},
137+
// Be sure to enable the rules as well
138+
rules: {
139+
'jsdoc/forbid-Any': [
140+
'error',
141+
],
142+
'jsdoc/forbid-Function': [
143+
'warn',
144+
],
145+
},
146+
}),
147+
];
148+
```
149+
150+
Now you can selectively disable the rules you have created. In the following,
151+
because of the individual disable directive, only the `Function` rule will be
152+
triggered (as a warning since its rule was set to "warn"):
153+
154+
```js
155+
/* eslint-disable jsdoc/forbid-Any */
156+
/**
157+
* @param {any} abc Test
158+
* @param {Function} def Test2
159+
*/
160+
export const a = (abc, def) => {
161+
b(5, abc, def);
162+
};
163+
/* eslint-enable jsdoc/forbid-Any */
164+
```

‎.README/rules/no-restricted-syntax.md

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,10 @@ structures, (whether or not you add a specific `comment` condition).
1616
Note that if your parser supports comment AST (as [jsdoc-eslint-parser](https://github.com/brettz9/jsdoc-eslint-parser)
1717
is designed to do), you can just use ESLint's rule.
1818

19+
For an alternative to this rule, see the
20+
[Advanced](./docs/advanced.md#forbidding-structures) docs under
21+
creating your own rules and forbidding structures.
22+
1923
## Options
2024

2125
### `contexts`

‎README.md

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -120,7 +120,13 @@ export default [
120120

121121
A `plugins` property can also be supplied to merge with the resulting `jsdoc` plugin.
122122

123-
Other config properties such as `files`, `ignores`, etc. are also copied over.
123+
Other config properties such as `files`, `ignores`, etc. are also copied over,
124+
though noting that if the specified config produces an array, they will not
125+
currently function.
126+
127+
There is also a `extraRuleDefinitions.forbid` option, the details of which are
128+
explained in the [Advanced](./docs/advanced.md#forbidding-structures) docs
129+
(under creating your own rules and forbidding structures).
124130

125131
<a name="user-content-eslint-plugin-jsdoc-configuration-flat-config-declarative"></a>
126132
<a name="eslint-plugin-jsdoc-configuration-flat-config-declarative"></a>

‎docs/advanced.md

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,8 @@
66
* [`contexts` format](#user-content-advanced-ast-and-selectors-contexts-format)
77
* [Discovering available AST definitions](#user-content-advanced-ast-and-selectors-discovering-available-ast-definitions)
88
* [Uses/Tips for AST](#user-content-advanced-ast-and-selectors-uses-tips-for-ast)
9+
* [Creating your own rules](#user-content-advanced-creating-your-own-rules)
10+
* [Forbidding structures](#user-content-advanced-creating-your-own-rules-forbidding-structures)
911

1012

1113
<a name="user-content-advanced-ast-and-selectors"></a>
@@ -100,3 +102,83 @@ we have
100102
to the selector you wish so as to get messages reported in the bottom right
101103
pane which match your [esquery](https://github.com/estools/esquery/#readme)
102104
selector).
105+
106+
<a name="user-content-advanced-creating-your-own-rules"></a>
107+
<a name="advanced-creating-your-own-rules"></a>
108+
### Creating your own rules
109+
110+
<a name="user-content-advanced-creating-your-own-rules-forbidding-structures"></a>
111+
<a name="advanced-creating-your-own-rules-forbidding-structures"></a>
112+
#### Forbidding structures
113+
114+
Although `jsdoc/no-restricted-syntax` is available for restricting certain syntax,
115+
it comes at a cost that, no matter how many restrictions one adds, one can only
116+
disable a single restriction by disabling them all.
117+
118+
With the `extraRuleDefinitions.forbid` option, one can add information that is used
119+
to create extra individual rules forbidding specific structures, and these rules can
120+
then be selectively enabled and optionally disabled on a case-by-case basis.
121+
122+
For each `forbid` key, add the name of the context (this will be appended to
123+
`forbid-` to decide the name of the rule, so with "Any" as the key, the rule
124+
created will be `forbid-Any`). Then provide an optional `description` key
125+
(which will be used for the created rule's `meta.docs.description`) and the
126+
`contexts` array. See the `jsdoc/restricted-syntax` rule for more details.
127+
128+
```js
129+
import {jsdoc} from 'eslint-plugin-jsdoc';
130+
131+
export default [
132+
jsdoc({
133+
config: 'flat/recommended',
134+
extraRuleDefinitions: {
135+
forbid: {
136+
Any: {
137+
contexts: [
138+
{
139+
comment: 'JsdocBlock:has(JsdocTypeName[value="any"])',
140+
context: 'any',
141+
message: '`any` is not allowed; use a more specific type',
142+
},
143+
],
144+
descriptions: 'Testing here',
145+
},
146+
Function: {
147+
contexts: [
148+
{
149+
comment: 'JsdocBlock:has(JsdocTypeName[value="Function"])',
150+
context: 'any',
151+
message: '`Function` is not allowed; use a more specific type',
152+
},
153+
],
154+
},
155+
},
156+
},
157+
// Be sure to enable the rules as well
158+
rules: {
159+
'jsdoc/forbid-Any': [
160+
'error',
161+
],
162+
'jsdoc/forbid-Function': [
163+
'warn',
164+
],
165+
},
166+
}),
167+
];
168+
```
169+
170+
Now you can selectively disable the rules you have created. In the following,
171+
because of the individual disable directive, only the `Function` rule will be
172+
triggered (as a warning since its rule was set to "warn"):
173+
174+
```js
175+
/* eslint-disable jsdoc/forbid-Any */
176+
/**
177+
* @param {any} abc Test
178+
* @param {Function} def Test2
179+
*/
180+
export const a = (abc, def) => {
181+
b(5, abc, def);
182+
};
183+
/* eslint-enable jsdoc/forbid-Any */
184+
```

‎docs/rules/no-restricted-syntax.md

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,10 @@ structures, (whether or not you add a specific `comment` condition).
2323
Note that if your parser supports comment AST (as [jsdoc-eslint-parser](https://github.com/brettz9/jsdoc-eslint-parser)
2424
is designed to do), you can just use ESLint's rule.
2525

26+
For an alternative to this rule, see the
27+
[Advanced](./docs/advanced.md#forbidding-structures) docs under
28+
creating your own rules and forbidding structures.
29+
2630
<a name="user-content-no-restricted-syntax-options"></a>
2731
<a name="no-restricted-syntax-options"></a>
2832
## Options

0 commit comments

Comments
 (0)