Skip to content

Commit 92bf39e

Browse files
brettz9brettz9
committed
feat(ts-method-signature-style): add new rule
1 parent 38770c4 commit 92bf39e

File tree

14 files changed

+1018
-163
lines changed

14 files changed

+1018
-163
lines changed

‎.README/README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -278,6 +278,7 @@ Finally, enable all of the rules that you would like to use.
278278
"jsdoc/sort-tags": 1,
279279
"jsdoc/tag-lines": 1, // Recommended
280280
"jsdoc/text-escaping": 1,
281+
"jsdoc/ts-method-signature-style": 1,
281282
"jsdoc/type-formatting": 1,
282283
"jsdoc/valid-types": 1 // Recommended
283284
}

‎.README/rules/ts-method-signature-style.md‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
# `ts-method-signature-style`
2+
3+
Inspired by `typescript-eslint`'s [method-signature-style](https://typescript-eslint.io/rules/method-signature-style/) rule.
4+
5+
See that rule for the rationale behind preferring the function
6+
property.
7+
8+
## Options
9+
10+
{"gitdown": "options"}
11+
12+
|||
13+
|---|---|
14+
|Context|everywhere|
15+
|Tags|``|
16+
|Recommended|false|
17+
|Settings||
18+
|Options|string ("method", "property") followed by object with `enableFixer`|
19+
20+
## Failing examples
21+
22+
<!-- assertions-failing tsMethodSignatureStyle -->
23+
24+
## Passing examples
25+
26+
<!-- assertions-passing tsMethodSignatureStyle -->

‎README.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -305,6 +305,7 @@ Finally, enable all of the rules that you would like to use.
305305
"jsdoc/sort-tags": 1,
306306
"jsdoc/tag-lines": 1, // Recommended
307307
"jsdoc/text-escaping": 1,
308+
"jsdoc/ts-method-signature-style": 1,
308309
"jsdoc/type-formatting": 1,
309310
"jsdoc/valid-types": 1 // Recommended
310311
}
@@ -497,5 +498,6 @@ non-default-recommended fixer).
497498
||:wrench:| [sort-tags](./docs/rules/sort-tags.md#readme) | Sorts tags by a specified sequence according to tag name, optionally adding line breaks between tag groups. |
498499
|:heavy_check_mark:|:wrench:| [tag-lines](./docs/rules/tag-lines.md#readme) | Enforces lines (or no lines) before, after, or between tags. |
499500
||:wrench:| [text-escaping](./docs/rules/text-escaping.md#readme) | Auto-escape certain characters that are input within block and tag descriptions. |
501+
||:wrench:| [ts-method-signature-style](./docs/rules/ts-method-signature-style.md#readme) | Prefers either function properties or method signatures |
500502
||:wrench:| [type-formatting](./docs/rules/type-formatting.md#readme) | Formats JSDoc type values. |
501503
|:heavy_check_mark:|| [valid-types](./docs/rules/valid-types.md#readme) | Requires all types/namepaths to be valid JSDoc, Closure compiler, or TypeScript types (configurable in settings). |

‎docs/rules/ts-method-signature-style.md‎

Lines changed: 163 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,163 @@
1+
<a name="user-content-ts-method-signature-style"></a>
2+
<a name="ts-method-signature-style"></a>
3+
# <code>ts-method-signature-style</code>
4+
5+
Inspired by `typescript-eslint`'s [method-signature-style](https://typescript-eslint.io/rules/method-signature-style/) rule.
6+
7+
See that rule for the rationale behind preferring the function
8+
property.
9+
10+
<a name="user-content-ts-method-signature-style-options"></a>
11+
<a name="ts-method-signature-style-options"></a>
12+
## Options
13+
14+
The first option is a string with the following possible values: "method", "property".
15+
16+
17+
The next option is an object with the following properties.
18+
19+
<a name="user-content-ts-method-signature-style-options-enablefixer"></a>
20+
<a name="ts-method-signature-style-options-enablefixer"></a>
21+
### <code>enableFixer</code>
22+
23+
Whether to enable the fixer. Defaults to `true`.
24+
25+
26+
|||
27+
|---|---|
28+
|Context|everywhere|
29+
|Tags|``|
30+
|Recommended|false|
31+
|Settings||
32+
|Options|string ("method", "property") followed by object with `enableFixer`|
33+
34+
<a name="user-content-ts-method-signature-style-failing-examples"></a>
35+
<a name="ts-method-signature-style-failing-examples"></a>
36+
## Failing examples
37+
38+
The following patterns are considered problems:
39+
40+
````ts
41+
/**
42+
* @param {{
43+
* func(arg: string): number
44+
* }} someName
45+
*/
46+
// "jsdoc/ts-method-signature-style": ["error"|"warn", "property"]
47+
// Message: Found method signature; prefer function property.
48+
49+
/**
50+
* @param {{
51+
* func(arg: string): number
52+
* }} someName
53+
*/
54+
// "jsdoc/ts-method-signature-style": ["error"|"warn", "property",{"enableFixer":false}]
55+
// Message: Found method signature; prefer function property.
56+
57+
/**
58+
* @param {{
59+
* func(arg: number): void
60+
* func(arg: string): void
61+
* func(arg: boolean): void
62+
* }} someName
63+
*/
64+
// Message: Found method signature; prefer function property.
65+
66+
/**
67+
* @param {{
68+
* func: (arg: string) => number
69+
* }} someName
70+
*/
71+
// "jsdoc/ts-method-signature-style": ["error"|"warn", "method"]
72+
// Message: Found function property; prefer method signature.
73+
74+
/**
75+
* @param {{
76+
* func: (arg: string) => number
77+
* }} someName
78+
*/
79+
// "jsdoc/ts-method-signature-style": ["error"|"warn", "method",{"enableFixer":false}]
80+
// Message: Found function property; prefer method signature.
81+
82+
/**
83+
* @type {{
84+
* func: ((arg: number) => void) &
85+
* ((arg: string) => void) &
86+
* ((arg: boolean) => void)
87+
* }}
88+
*/
89+
// "jsdoc/ts-method-signature-style": ["error"|"warn", "method"]
90+
// Message: Found function property; prefer method signature.
91+
92+
/**
93+
* @param {{
94+
* func: ((arg: number) => void) &
95+
* ((arg: string) => void) &
96+
* ((arg: boolean) => void)
97+
* }} someName
98+
*/
99+
// "jsdoc/ts-method-signature-style": ["error"|"warn", "method",{"enableFixer":false}]
100+
// Message: Found function property; prefer method signature.
101+
102+
/**
103+
* @param {{
104+
* "func"(arg: string): number
105+
* }} someName
106+
*/
107+
// "jsdoc/ts-method-signature-style": ["error"|"warn", "property"]
108+
// Message: Found method signature; prefer function property.
109+
110+
/**
111+
* @param {{
112+
* 'func': (arg: string) => number
113+
* }} someName
114+
*/
115+
// "jsdoc/ts-method-signature-style": ["error"|"warn", "method"]
116+
// Message: Found function property; prefer method signature.
117+
118+
/** @type {{
119+
* func: ((arg: number) => void) &
120+
* ((arg: string) => void) &
121+
* ((arg: boolean) => void)
122+
* }}
123+
*/
124+
// "jsdoc/ts-method-signature-style": ["error"|"warn", "method"]
125+
// Message: Found function property; prefer method signature.
126+
````
127+
128+
129+
130+
<a name="user-content-ts-method-signature-style-passing-examples"></a>
131+
<a name="ts-method-signature-style-passing-examples"></a>
132+
## Passing examples
133+
134+
The following patterns are not considered problems:
135+
136+
````ts
137+
/**
138+
* @param {{
139+
* func: (arg: string) => number
140+
* }}
141+
*/
142+
// "jsdoc/ts-method-signature-style": ["error"|"warn", "property"]
143+
144+
/**
145+
* @param {{
146+
* func: ((arg: number) => void) &
147+
* ((arg: string) => void) &
148+
* ((arg: boolean) => void)
149+
* }}
150+
*/
151+
152+
/**
153+
* @param {abc<}
154+
*/
155+
156+
/**
157+
* @param {{
158+
* func: ((arg: number) => void) & (SomeType)
159+
* }}
160+
*/
161+
// "jsdoc/ts-method-signature-style": ["error"|"warn", "method"]
162+
````
163+

‎package.json‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@
55
"url": "http://gajus.com"
66
},
77
"dependencies": {
8-
"@es-joy/jsdoccomment": "~0.75.0",
8+
"@es-joy/jsdoccomment": "~0.76.0",
99
"are-docs-informative": "^0.0.2",
1010
"comment-parser": "1.4.1",
1111
"debug": "^4.4.3",
@@ -58,7 +58,7 @@
5858
"glob": "^11.0.3",
5959
"globals": "^16.4.0",
6060
"husky": "^9.1.7",
61-
"jsdoc-type-pratt-parser": "^6.9.1",
61+
"jsdoc-type-pratt-parser": "^6.10.0",
6262
"json-schema": "^0.4.0",
6363
"json-schema-to-typescript": "^15.0.4",
6464
"lint-staged": "^16.2.3",

‎pnpm-lock.yaml‎

Lines changed: 11 additions & 11 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎src/index-cjs.js‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -66,6 +66,7 @@ import requireYieldsCheck from './rules/requireYieldsCheck.js';
6666
import sortTags from './rules/sortTags.js';
6767
import tagLines from './rules/tagLines.js';
6868
import textEscaping from './rules/textEscaping.js';
69+
import tsMethodSignatureStyle from './rules/tsMethodSignatureStyle.js';
6970
import typeFormatting from './rules/typeFormatting.js';
7071
import validTypes from './rules/validTypes.js';
7172

@@ -251,6 +252,7 @@ index.rules = {
251252
'sort-tags': sortTags,
252253
'tag-lines': tagLines,
253254
'text-escaping': textEscaping,
255+
'ts-method-signature-style': tsMethodSignatureStyle,
254256
'type-formatting': typeFormatting,
255257
'valid-types': validTypes,
256258
};
@@ -341,6 +343,7 @@ const createRecommendedRuleset = (warnOrError, flatName) => {
341343
'jsdoc/sort-tags': 'off',
342344
'jsdoc/tag-lines': warnOrError,
343345
'jsdoc/text-escaping': 'off',
346+
'jsdoc/ts-method-signature-style': 'off',
344347
'jsdoc/type-formatting': 'off',
345348
'jsdoc/valid-types': warnOrError,
346349
},

‎src/index.js‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -72,6 +72,7 @@ import requireYieldsCheck from './rules/requireYieldsCheck.js';
7272
import sortTags from './rules/sortTags.js';
7373
import tagLines from './rules/tagLines.js';
7474
import textEscaping from './rules/textEscaping.js';
75+
import tsMethodSignatureStyle from './rules/tsMethodSignatureStyle.js';
7576
import typeFormatting from './rules/typeFormatting.js';
7677
import validTypes from './rules/validTypes.js';
7778

@@ -257,6 +258,7 @@ index.rules = {
257258
'sort-tags': sortTags,
258259
'tag-lines': tagLines,
259260
'text-escaping': textEscaping,
261+
'ts-method-signature-style': tsMethodSignatureStyle,
260262
'type-formatting': typeFormatting,
261263
'valid-types': validTypes,
262264
};
@@ -347,6 +349,7 @@ const createRecommendedRuleset = (warnOrError, flatName) => {
347349
'jsdoc/sort-tags': 'off',
348350
'jsdoc/tag-lines': warnOrError,
349351
'jsdoc/text-escaping': 'off',
352+
'jsdoc/ts-method-signature-style': 'off',
350353
'jsdoc/type-formatting': 'off',
351354
'jsdoc/valid-types': warnOrError,
352355
},

0 commit comments

Comments
 (0)