Skip to content

Commit d5fa8da

Browse files
brettz9brettz9
committed
feat: new rule convert-to-jsdoc-comments; fixes #1002 
1 parent 394b85f commit d5fa8da

9 files changed

+844
-4
lines changed

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

+62
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
# `convert-to-jsdoc-comments`
2+
3+
Converts single line or non-JSDoc, multiline comments into JSDoc comments.
4+
5+
## Options
6+
7+
### `enableFixer`
8+
9+
Set to `false` to disable fixing.
10+
11+
### `lineOrBlockStyle`
12+
13+
What style of comments to which to apply JSDoc conversion.
14+
15+
- `block` - Applies to block-style comments (`/* ... */`)
16+
- `line` - Applies to line-style comments (`// ...`)
17+
- `both` - Applies to both block and line-style comments
18+
19+
Defaults to `both`.
20+
21+
### `enforceJsdocLineStyle`
22+
23+
What policy to enforce on the conversion of non-JSDoc comments without
24+
line breaks. (Non-JSDoc (mulitline) comments with line breaks will always
25+
be converted to `multi` style JSDoc comments.)
26+
27+
- `multi` - Convert to multi-line style
28+
```js
29+
/**
30+
* Some text
31+
*/
32+
```
33+
- `single` - Convert to single-line style
34+
```js
35+
/** Some text */
36+
```
37+
38+
Defaults to `multi`.
39+
40+
### `allowedPrefixes`
41+
42+
An array of prefixes to allow at the beginning of a comment.
43+
44+
Defaults to `['@ts-', 'istanbul ', 'c8 ', 'v8 ', 'eslint', 'prettier-']`.
45+
46+
Supplying your own value overrides the defaults.
47+
48+
|||
49+
|---|---|
50+
|Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`|
51+
|Tags|(N/A)|
52+
|Recommended|false|
53+
|Settings|`minLines`, `maxLines`|
54+
|Options|`enableFixer`, `enforceJsdocLineStyle`, `lineOrBlockStyle`|
55+
56+
## Failing examples
57+
58+
<!-- assertions-failing convertToJsdocComments -->
59+
60+
## Passing examples
61+
62+
<!-- assertions-passing convertToJsdocComments -->

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

+179
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,179 @@
1+
<a name="user-content-convert-to-jsdoc-comments"></a>
2+
<a name="convert-to-jsdoc-comments"></a>
3+
# <code>convert-to-jsdoc-comments</code>
4+
5+
Converts single line or non-JSDoc, multiline comments into JSDoc comments.
6+
7+
<a name="user-content-convert-to-jsdoc-comments-options"></a>
8+
<a name="convert-to-jsdoc-comments-options"></a>
9+
## Options
10+
11+
<a name="user-content-convert-to-jsdoc-comments-options-enablefixer"></a>
12+
<a name="convert-to-jsdoc-comments-options-enablefixer"></a>
13+
### <code>enableFixer</code>
14+
15+
Set to `false` to disable fixing.
16+
17+
<a name="user-content-convert-to-jsdoc-comments-options-lineorblockstyle"></a>
18+
<a name="convert-to-jsdoc-comments-options-lineorblockstyle"></a>
19+
### <code>lineOrBlockStyle</code>
20+
21+
What style of comments to which to apply JSDoc conversion.
22+
23+
- `block` - Applies to block-style comments (`/* ... */`)
24+
- `line` - Applies to line-style comments (`// ...`)
25+
- `both` - Applies to both block and line-style comments
26+
27+
Defaults to `both`.
28+
29+
<a name="user-content-convert-to-jsdoc-comments-options-enforcejsdoclinestyle"></a>
30+
<a name="convert-to-jsdoc-comments-options-enforcejsdoclinestyle"></a>
31+
### <code>enforceJsdocLineStyle</code>
32+
33+
What policy to enforce on the conversion of non-JSDoc comments without
34+
line breaks. (Non-JSDoc (mulitline) comments with line breaks will always
35+
be converted to `multi` style JSDoc comments.)
36+
37+
- `multi` - Convert to multi-line style
38+
```js
39+
/**
40+
* Some text
41+
*/
42+
```
43+
- `single` - Convert to single-line style
44+
```js
45+
/** Some text */
46+
```
47+
48+
Defaults to `multi`.
49+
50+
<a name="user-content-convert-to-jsdoc-comments-options-allowedprefixes"></a>
51+
<a name="convert-to-jsdoc-comments-options-allowedprefixes"></a>
52+
### <code>allowedPrefixes</code>
53+
54+
An array of prefixes to allow at the beginning of a comment.
55+
56+
Defaults to `['@ts-', 'istanbul ', 'c8 ', 'v8 ', 'eslint', 'prettier-']`.
57+
58+
Supplying your own value overrides the defaults.
59+
60+
|||
61+
|---|---|
62+
|Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`|
63+
|Tags|(N/A)|
64+
|Recommended|false|
65+
|Settings|`minLines`, `maxLines`|
66+
|Options|`enableFixer`, `enforceJsdocLineStyle`, `lineOrBlockStyle`|
67+
68+
<a name="user-content-convert-to-jsdoc-comments-failing-examples"></a>
69+
<a name="convert-to-jsdoc-comments-failing-examples"></a>
70+
## Failing examples
71+
72+
The following patterns are considered problems:
73+
74+
````js
75+
// A single line comment
76+
function quux () {}
77+
// "jsdoc/convert-to-jsdoc-comments": ["error"|"warn", {"enforceJsdocLineStyle":"single"}]
78+
// Message: Line comments should be JSDoc-style.
79+
80+
// A single line comment
81+
function quux () {}
82+
// "jsdoc/convert-to-jsdoc-comments": ["error"|"warn", {"contexts":[{"context":"FunctionDeclaration","inlineCommentBlock":true}]}]
83+
// Message: Line comments should be JSDoc-style.
84+
85+
// A single line comment
86+
function quux () {}
87+
// "jsdoc/convert-to-jsdoc-comments": ["error"|"warn", {"enableFixer":false,"enforceJsdocLineStyle":"single"}]
88+
// Message: Line comments should be JSDoc-style.
89+
90+
// A single line comment
91+
function quux () {}
92+
// "jsdoc/convert-to-jsdoc-comments": ["error"|"warn", {"lineOrBlockStyle":"line","enforceJsdocLineStyle":"single"}]
93+
// Message: Line comments should be JSDoc-style.
94+
95+
/* A single line comment */
96+
function quux () {}
97+
// "jsdoc/convert-to-jsdoc-comments": ["error"|"warn", {"enforceJsdocLineStyle":"single"}]
98+
// Message: Block comments should be JSDoc-style.
99+
100+
/* A single line comment */
101+
function quux () {}
102+
// "jsdoc/convert-to-jsdoc-comments": ["error"|"warn", {"lineOrBlockStyle":"block","enforceJsdocLineStyle":"single"}]
103+
// Message: Block comments should be JSDoc-style.
104+
105+
// A single line comment
106+
function quux () {}
107+
// "jsdoc/convert-to-jsdoc-comments": ["error"|"warn", {"enforceJsdocLineStyle":"multi"}]
108+
// Message: Line comments should be JSDoc-style.
109+
110+
// A single line comment
111+
function quux () {}
112+
// Message: Line comments should be JSDoc-style.
113+
114+
/* A single line comment */
115+
function quux () {}
116+
// "jsdoc/convert-to-jsdoc-comments": ["error"|"warn", {"enforceJsdocLineStyle":"multi"}]
117+
// Message: Block comments should be JSDoc-style.
118+
119+
// Single line comment
120+
function quux() {
121+
122+
}
123+
// Settings: {"jsdoc":{"structuredTags":{"see":{"name":false,"required":["name"]}}}}
124+
// Message: Cannot add "name" to `require` with the tag's `name` set to `false`
125+
126+
/* Entity to represent a user in the system. */
127+
@Entity('users', getVal())
128+
export class User {
129+
}
130+
// "jsdoc/convert-to-jsdoc-comments": ["error"|"warn", {"contexts":["ClassDeclaration"]}]
131+
// Message: Block comments should be JSDoc-style.
132+
133+
/* A single line comment */ function quux () {}
134+
// Settings: {"jsdoc":{"minLines":0,"maxLines":0}}
135+
// "jsdoc/convert-to-jsdoc-comments": ["error"|"warn", {"enforceJsdocLineStyle":"single"}]
136+
// Message: Block comments should be JSDoc-style.
137+
````
138+
139+
140+
141+
<a name="user-content-convert-to-jsdoc-comments-passing-examples"></a>
142+
<a name="convert-to-jsdoc-comments-passing-examples"></a>
143+
## Passing examples
144+
145+
The following patterns are not considered problems:
146+
147+
````js
148+
/** A single line comment */
149+
function quux () {}
150+
// "jsdoc/convert-to-jsdoc-comments": ["error"|"warn", {"enforceJsdocLineStyle":"single"}]
151+
152+
/** A single line comment */
153+
function quux () {}
154+
// "jsdoc/convert-to-jsdoc-comments": ["error"|"warn", {"enforceJsdocLineStyle":"multi"}]
155+
156+
/** A single line comment */
157+
function quux () {}
158+
// "jsdoc/convert-to-jsdoc-comments": ["error"|"warn", {"lineOrBlockStyle":"line"}]
159+
160+
/** A single line comment */
161+
function quux () {}
162+
// "jsdoc/convert-to-jsdoc-comments": ["error"|"warn", {"lineOrBlockStyle":"block"}]
163+
164+
/* A single line comment */
165+
function quux () {}
166+
// "jsdoc/convert-to-jsdoc-comments": ["error"|"warn", {"lineOrBlockStyle":"line","enforceJsdocLineStyle":"single"}]
167+
168+
// A single line comment
169+
function quux () {}
170+
// "jsdoc/convert-to-jsdoc-comments": ["error"|"warn", {"lineOrBlockStyle":"block","enforceJsdocLineStyle":"single"}]
171+
172+
// @ts-expect-error
173+
function quux () {}
174+
175+
// @custom-something
176+
function quux () {}
177+
// "jsdoc/convert-to-jsdoc-comments": ["error"|"warn", {"allowedPrefixes":["@custom-"]}]
178+
````
179+

‎package.json

+1-1
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.43.1",
8+
"@es-joy/jsdoccomment": "~0.44.0",
99
"are-docs-informative": "^0.0.2",
1010
"comment-parser": "1.4.1",
1111
"debug": "^4.3.5",

‎pnpm-lock.yaml

+15-2
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎src/bin/generateRule.js

+1-1
Original file line numberDiff line numberDiff line change
@@ -121,7 +121,7 @@ export default iterateJsdoc(({
121121
await fs.writeFile(ruleTestPath, ruleTestTemplate);
122122
}
123123

124-
const ruleReadmeTemplate = `### \`${ruleName}\`
124+
const ruleReadmeTemplate = `# \`${ruleName}\`
125125
126126
|||
127127
|---|---|

‎src/index.js

+3
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,7 @@ import checkSyntax from './rules/checkSyntax.js';
99
import checkTagNames from './rules/checkTagNames.js';
1010
import checkTypes from './rules/checkTypes.js';
1111
import checkValues from './rules/checkValues.js';
12+
import convertToJsdocComments from './rules/convertToJsdocComments.js';
1213
import emptyTags from './rules/emptyTags.js';
1314
import implementsOnClasses from './rules/implementsOnClasses.js';
1415
import importsAsDependencies from './rules/importsAsDependencies.js';
@@ -81,6 +82,7 @@ const index = {
8182
'check-tag-names': checkTagNames,
8283
'check-types': checkTypes,
8384
'check-values': checkValues,
85+
'convert-to-jsdoc-comments': convertToJsdocComments,
8486
'empty-tags': emptyTags,
8587
'implements-on-classes': implementsOnClasses,
8688
'imports-as-dependencies': importsAsDependencies,
@@ -153,6 +155,7 @@ const createRecommendedRuleset = (warnOrError, flatName) => {
153155
'jsdoc/check-tag-names': warnOrError,
154156
'jsdoc/check-types': warnOrError,
155157
'jsdoc/check-values': warnOrError,
158+
'jsdoc/convert-to-jsdoc-comments': 'off',
156159
'jsdoc/empty-tags': warnOrError,
157160
'jsdoc/implements-on-classes': warnOrError,
158161
'jsdoc/imports-as-dependencies': 'off',

0 commit comments

Comments
 (0)