Skip to content

Commit e570b79

Browse files
brettz9brettz9
committed
refactor: work on converting to jsdoc comments (after)
1 parent d5fa8da commit e570b79

9 files changed

+983
-497
lines changed

‎.README/rules/convert-to-jsdoc-comments.md

+24-1
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,9 @@
22

33
Converts single line or non-JSDoc, multiline comments into JSDoc comments.
44

5+
Note that this rule is experimental. As usual with fixers, please confirm
6+
the results before committing.
7+
58
## Options
69

710
### `enableFixer`
@@ -45,13 +48,33 @@ Defaults to `['@ts-', 'istanbul ', 'c8 ', 'v8 ', 'eslint', 'prettier-']`.
4548

4649
Supplying your own value overrides the defaults.
4750

51+
### `contexts`
52+
53+
The contexts which will be checked for preceding content.
54+
55+
Defaults to `ArrowFunctionExpression`, `FunctionDeclaration`,
56+
`FunctionExpression`, `TSDeclareFunction`.
57+
58+
### `contextsAfter`
59+
60+
The contexts which will be checked for content on the same line after.
61+
62+
Defaults to an empty array.
63+
64+
### `contextsBeforeAndAfter`
65+
66+
The contexts which will be checked for content before and on the same
67+
line after.
68+
69+
Defaults to `VariableDeclarator`, `TSPropertySignature`, `PropertyDefinition`.
70+
4871
|||
4972
|---|---|
5073
|Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`|
5174
|Tags|(N/A)|
5275
|Recommended|false|
5376
|Settings|`minLines`, `maxLines`|
54-
|Options|`enableFixer`, `enforceJsdocLineStyle`, `lineOrBlockStyle`|
77+
|Options|`enableFixer`, `enforceJsdocLineStyle`, `lineOrBlockStyle`, `allowedPrefixes`, `contexts`, `contextsAfter`, `contextsBeforeAndAfter`|
5578

5679
## Failing examples
5780

‎.ncurc.cjs

+5
Original file line numberDiff line numberDiff line change
@@ -8,5 +8,10 @@ module.exports = {
88
'decamelize',
99
'escape-string-regexp',
1010
'open-editor',
11+
12+
// todo[engine:node@>=20]: Can reenable
13+
'glob',
14+
// todo[engine:node@>=20]: Can reenable
15+
'rimraf'
1116
],
1217
};

‎docs/rules/convert-to-jsdoc-comments.md

+72-1
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,9 @@
44

55
Converts single line or non-JSDoc, multiline comments into JSDoc comments.
66

7+
Note that this rule is experimental. As usual with fixers, please confirm
8+
the results before committing.
9+
710
<a name="user-content-convert-to-jsdoc-comments-options"></a>
811
<a name="convert-to-jsdoc-comments-options"></a>
912
## Options
@@ -57,13 +60,39 @@ Defaults to `['@ts-', 'istanbul ', 'c8 ', 'v8 ', 'eslint', 'prettier-']`.
5760

5861
Supplying your own value overrides the defaults.
5962

63+
<a name="user-content-convert-to-jsdoc-comments-options-contexts"></a>
64+
<a name="convert-to-jsdoc-comments-options-contexts"></a>
65+
### <code>contexts</code>
66+
67+
The contexts which will be checked for preceding content.
68+
69+
Defaults to `ArrowFunctionExpression`, `FunctionDeclaration`,
70+
`FunctionExpression`, `TSDeclareFunction`.
71+
72+
<a name="user-content-convert-to-jsdoc-comments-options-contextsafter"></a>
73+
<a name="convert-to-jsdoc-comments-options-contextsafter"></a>
74+
### <code>contextsAfter</code>
75+
76+
The contexts which will be checked for content on the same line after.
77+
78+
Defaults to an empty array.
79+
80+
<a name="user-content-convert-to-jsdoc-comments-options-contextsbeforeandafter"></a>
81+
<a name="convert-to-jsdoc-comments-options-contextsbeforeandafter"></a>
82+
### <code>contextsBeforeAndAfter</code>
83+
84+
The contexts which will be checked for content before and on the same
85+
line after.
86+
87+
Defaults to `VariableDeclarator`, `TSPropertySignature`, `PropertyDefinition`.
88+
6089
|||
6190
|---|---|
6291
|Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`|
6392
|Tags|(N/A)|
6493
|Recommended|false|
6594
|Settings|`minLines`, `maxLines`|
66-
|Options|`enableFixer`, `enforceJsdocLineStyle`, `lineOrBlockStyle`|
95+
|Options|`enableFixer`, `enforceJsdocLineStyle`, `lineOrBlockStyle`, `allowedPrefixes`, `contexts`, `contextsAfter`, `contextsBeforeAndAfter`|
6796

6897
<a name="user-content-convert-to-jsdoc-comments-failing-examples"></a>
6998
<a name="convert-to-jsdoc-comments-failing-examples"></a>
@@ -134,6 +163,44 @@ export class User {
134163
// Settings: {"jsdoc":{"minLines":0,"maxLines":0}}
135164
// "jsdoc/convert-to-jsdoc-comments": ["error"|"warn", {"enforceJsdocLineStyle":"single"}]
136165
// Message: Block comments should be JSDoc-style.
166+
167+
var a = []; // Test comment
168+
// "jsdoc/convert-to-jsdoc-comments": ["error"|"warn", {"contextsBeforeAndAfter":[],"contextsAfter":["VariableDeclarator"]}]
169+
// Message: Line comments should be JSDoc-style.
170+
171+
var a = []; // Test comment
172+
// "jsdoc/convert-to-jsdoc-comments": ["error"|"warn", {"contextsBeforeAndAfter":[],"contextsAfter":[{"context":"VariableDeclarator","inlineCommentBlock":true}]}]
173+
// Message: Line comments should be JSDoc-style.
174+
175+
var a = []; // Test comment
176+
// Settings: {"jsdoc":{"minLines":0,"maxLines":0}}
177+
// "jsdoc/convert-to-jsdoc-comments": ["error"|"warn", {"contextsBeforeAndAfter":[],"contextsAfter":[{"context":"VariableDeclarator","inlineCommentBlock":true}]}]
178+
// Message: Line comments should be JSDoc-style.
179+
180+
// Test comment
181+
var a = [];
182+
// "jsdoc/convert-to-jsdoc-comments": ["error"|"warn", {"contextsBeforeAndAfter":["VariableDeclaration"]}]
183+
// Message: Line comments should be JSDoc-style.
184+
185+
var a = []; // Test comment
186+
// "jsdoc/convert-to-jsdoc-comments": ["error"|"warn", {"contextsBeforeAndAfter":["VariableDeclaration"]}]
187+
// Message: Line comments should be JSDoc-style.
188+
189+
interface B {
190+
g: () => string; // Test comment
191+
}
192+
// "jsdoc/convert-to-jsdoc-comments": ["error"|"warn", {"contextsBeforeAndAfter":["TSPropertySignature"]}]
193+
// Message: Line comments should be JSDoc-style.
194+
195+
class TestClass {
196+
public Test: (id: number) => string; // Test comment
197+
}
198+
// "jsdoc/convert-to-jsdoc-comments": ["error"|"warn", {"contextsBeforeAndAfter":["PropertyDefinition"]}]
199+
// Message: Line comments should be JSDoc-style.
200+
201+
var a = []; // Test comment
202+
// "jsdoc/convert-to-jsdoc-comments": ["error"|"warn", {"contextsBeforeAndAfter":["VariableDeclarator"]}]
203+
// Message: Line comments should be JSDoc-style.
137204
````
138205

139206

@@ -175,5 +242,9 @@ function quux () {}
175242
// @custom-something
176243
function quux () {}
177244
// "jsdoc/convert-to-jsdoc-comments": ["error"|"warn", {"allowedPrefixes":["@custom-"]}]
245+
246+
// Test comment
247+
var a = [];
248+
// "jsdoc/convert-to-jsdoc-comments": ["error"|"warn", {"contextsBeforeAndAfter":[],"contextsAfter":["VariableDeclarator"]}]
178249
````
179250

‎package.json

+11-11
Original file line numberDiff line numberDiff line change
@@ -5,13 +5,13 @@
55
"url": "http://gajus.com"
66
},
77
"dependencies": {
8-
"@es-joy/jsdoccomment": "~0.44.0",
8+
"@es-joy/jsdoccomment": "~0.45.0",
99
"are-docs-informative": "^0.0.2",
1010
"comment-parser": "1.4.1",
1111
"debug": "^4.3.5",
1212
"escape-string-regexp": "^4.0.0",
13-
"esquery": "^1.5.0",
14-
"parse-imports": "^2.1.0",
13+
"esquery": "^1.6.0",
14+
"parse-imports": "^2.1.1",
1515
"semver": "^7.6.2",
1616
"spdx-expression-parse": "^4.0.0",
1717
"synckit": "^0.9.0"
@@ -29,7 +29,7 @@
2929
"@es-joy/jsdoc-eslint-parser": "^0.21.1",
3030
"@hkdobrev/run-if-changed": "^0.3.1",
3131
"@semantic-release/commit-analyzer": "^13.0.0",
32-
"@semantic-release/github": "^10.0.6",
32+
"@semantic-release/github": "^10.1.0",
3333
"@semantic-release/npm": "^12.0.1",
3434
"@types/chai": "^4.3.16",
3535
"@types/debug": "^4.1.12",
@@ -39,35 +39,35 @@
3939
"@types/json-schema": "^7.0.15",
4040
"@types/lodash.defaultsdeep": "^4.6.9",
4141
"@types/mocha": "^10.0.7",
42-
"@types/node": "^20.14.9",
42+
"@types/node": "^20.14.10",
4343
"@types/semver": "^7.5.8",
4444
"@types/spdx-expression-parse": "^3.0.5",
45-
"@typescript-eslint/types": "^7.14.1",
45+
"@typescript-eslint/types": "^7.16.0",
4646
"babel-plugin-add-module-exports": "^1.0.4",
47-
"babel-plugin-istanbul": "^6.1.1",
47+
"babel-plugin-istanbul": "^7.0.0",
4848
"babel-plugin-transform-import-meta": "^2.2.1",
4949
"c8": "^10.1.2",
5050
"camelcase": "^6.3.0",
5151
"chai": "^4.3.10",
5252
"cross-env": "^7.0.3",
5353
"decamelize": "^5.0.1",
54-
"eslint": "9.5.0",
54+
"eslint": "9.6.0",
5555
"eslint-config-canonical": "~43.0.13",
5656
"espree": "^10.1.0",
5757
"gitdown": "^3.1.5",
5858
"glob": "^10.4.2",
59-
"globals": "^15.6.0",
59+
"globals": "^15.8.0",
6060
"husky": "^9.0.11",
6161
"jsdoc-type-pratt-parser": "^4.0.0",
6262
"json-schema": "^0.4.0",
6363
"lint-staged": "^15.2.7",
6464
"lodash.defaultsdeep": "^4.6.1",
65-
"mocha": "^10.5.2",
65+
"mocha": "^10.6.0",
6666
"open-editor": "^3.0.0",
6767
"replace": "^1.2.2",
6868
"rimraf": "^5.0.7",
6969
"semantic-release": "^24.0.0",
70-
"typescript": "5.3.x",
70+
"typescript": "5.5.x",
7171
"typescript-eslint": "^8.0.0-alpha.34"
7272
},
7373
"engines": {

0 commit comments

Comments
 (0)