Skip to content

Commit 6a2217b

Browse files
author
Eli Skeggs
committed
feat: add check-prefix rule
This rule checks that each line of the jsdoc comment starts with an asterisk. For composability with other rules, this does not check the alignment or indentation of the comment content. fix #199
1 parent 6014360 commit 6a2217b

File tree

7 files changed

+158
-0
lines changed

7 files changed

+158
-0
lines changed

‎.README/README.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -44,6 +44,7 @@ Finally, enable all of the rules that you would like to use.
4444
"jsdoc/check-examples": 1,
4545
"jsdoc/check-indentation": 1,
4646
"jsdoc/check-param-names": 1, // Recommended
47+
"jsdoc/check-prefix": 1,
4748
"jsdoc/check-syntax": 1,
4849
"jsdoc/check-tag-names": 1, // Recommended
4950
"jsdoc/check-types": 1, // Recommended
@@ -327,6 +328,7 @@ only (e.g., to match `Array` if the type is `Array` vs. `Array.<string>`).
327328
{"gitdown": "include", "file": "./rules/check-examples.md"}
328329
{"gitdown": "include", "file": "./rules/check-indentation.md"}
329330
{"gitdown": "include", "file": "./rules/check-param-names.md"}
331+
{"gitdown": "include", "file": "./rules/check-prefix.md"}
330332
{"gitdown": "include", "file": "./rules/check-syntax.md"}
331333
{"gitdown": "include", "file": "./rules/check-tag-names.md"}
332334
{"gitdown": "include", "file": "./rules/check-types.md"}

‎.README/rules/check-prefix.md

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
### `check-prefix`
2+
3+
Ensures that each JSDoc line starts with an `*`.
4+
5+
|||
6+
|---|---|
7+
|Context|everywhere|
8+
|Tags|N/a|

‎README.md

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,7 @@ JSDoc linting rules for ESLint.
2424
* [`check-examples`](#eslint-plugin-jsdoc-rules-check-examples)
2525
* [`check-indentation`](#eslint-plugin-jsdoc-rules-check-indentation)
2626
* [`check-param-names`](#eslint-plugin-jsdoc-rules-check-param-names)
27+
* [`check-prefix`](#eslint-plugin-jsdoc-rules-check-prefix)
2728
* [`check-syntax`](#eslint-plugin-jsdoc-rules-check-syntax)
2829
* [`check-tag-names`](#eslint-plugin-jsdoc-rules-check-tag-names)
2930
* [`check-types`](#eslint-plugin-jsdoc-rules-check-types)
@@ -87,6 +88,7 @@ Finally, enable all of the rules that you would like to use.
8788
"jsdoc/check-examples": 1,
8889
"jsdoc/check-indentation": 1,
8990
"jsdoc/check-param-names": 1, // Recommended
91+
"jsdoc/check-prefix": 1,
9092
"jsdoc/check-syntax": 1,
9193
"jsdoc/check-tag-names": 1, // Recommended
9294
"jsdoc/check-types": 1, // Recommended
@@ -1642,6 +1644,16 @@ function quux ({
16421644

16431645
Likewise for the pattern `[a, b]` which is an [`ArrayPattern`](https://github.com/estree/estree/blob/master/es2015.md#arraypattern).
16441646

1647+
<a name="eslint-plugin-jsdoc-rules-check-prefix"></a>
1648+
### <code>check-prefix</code>
1649+
1650+
Ensures that each JSDoc line starts with an `*`.
1651+
1652+
|||
1653+
|---|---|
1654+
|Context|everywhere|
1655+
|Tags|N/a|
1656+
16451657
<a name="eslint-plugin-jsdoc-rules-check-syntax"></a>
16461658
### <code>check-syntax</code>
16471659

‎src/index.js

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@ import checkAlignment from './rules/checkAlignment';
44
import checkExamples from './rules/checkExamples';
55
import checkIndentation from './rules/checkIndentation';
66
import checkParamNames from './rules/checkParamNames';
7+
import checkPrefix from './rules/checkPrefix';
78
import checkSyntax from './rules/checkSyntax';
89
import checkTagNames from './rules/checkTagNames';
910
import checkTypes from './rules/checkTypes';
@@ -39,6 +40,7 @@ export default {
3940
'jsdoc/check-examples': 'off',
4041
'jsdoc/check-indentation': 'off',
4142
'jsdoc/check-param-names': 'warn',
43+
'jsdoc/check-prefix': 'off',
4244
'jsdoc/check-syntax': 'off',
4345
'jsdoc/check-tag-names': 'warn',
4446
'jsdoc/check-types': 'warn',
@@ -72,6 +74,7 @@ export default {
7274
'check-examples': checkExamples,
7375
'check-indentation': checkIndentation,
7476
'check-param-names': checkParamNames,
77+
'check-prefix': checkPrefix,
7578
'check-syntax': checkSyntax,
7679
'check-tag-names': checkTagNames,
7780
'check-types': checkTypes,

‎src/rules/checkPrefix.js

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
import iterateJsdoc from '../iterateJsdoc';
2+
3+
const prefixMatch = /^(\s+)(?:\*( ?))?/u;
4+
const validPrefix = /^\s+\*(?:\/?$| )/u;
5+
6+
export default iterateJsdoc(({
7+
sourceCode,
8+
jsdocNode,
9+
report,
10+
}) => {
11+
const fix = (fixer) => {
12+
const replacement = sourceCode.getText(jsdocNode).split('\n')
13+
.map((line, index) => {
14+
return index && !validPrefix.test(line) ? line.replace(prefixMatch, (_, $1, $2) => {
15+
return `${$1}*${$2 || ' '}`;
16+
}) : line;
17+
})
18+
.join('\n');
19+
20+
return fixer.replaceText(jsdocNode, replacement);
21+
};
22+
23+
sourceCode.getText(jsdocNode).split('\n').some((line, index) => {
24+
const lineNum = parseInt(index, 10);
25+
if (lineNum && !validPrefix.test(line)) {
26+
report('Expected JSDoc block to have the prefix.', fix, {
27+
line: lineNum,
28+
});
29+
30+
return true;
31+
}
32+
33+
return false;
34+
});
35+
}, {
36+
iterateAllJsdocs: true,
37+
meta: {
38+
fixable: 'code',
39+
type: 'layout',
40+
},
41+
});

‎test/rules/assertions/checkPrefix.js

Lines changed: 91 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,91 @@
1+
export default {
2+
invalid: [
3+
{
4+
code: `
5+
6+
/**
7+
@param {Number} foo
8+
*/
9+
function quux (foo) {
10+
// with spaces
11+
}
12+
`,
13+
errors: [
14+
{
15+
line: 4,
16+
message: 'Expected JSDoc block to have the prefix.',
17+
},
18+
],
19+
output: `
20+
21+
/**
22+
* @param {Number} foo
23+
*/
24+
function quux (foo) {
25+
// with spaces
26+
}
27+
`,
28+
},
29+
{
30+
code: `
31+
/**
32+
@param {Number} foo
33+
*/function quux (foo) {
34+
// with spaces
35+
}
36+
`,
37+
errors: [
38+
{
39+
line: 3,
40+
message: 'Expected JSDoc block to have the prefix.',
41+
},
42+
],
43+
output: `
44+
/**
45+
* @param {Number} foo
46+
*/function quux (foo) {
47+
// with spaces
48+
}
49+
`,
50+
},
51+
],
52+
valid: [
53+
{
54+
code: `
55+
/**
56+
* Desc
57+
*
58+
* @param {Number} foo
59+
* This is more comment.
60+
*/
61+
function quux (foo) {
62+
63+
}
64+
`,
65+
},
66+
{
67+
code: `
68+
/**
69+
* Desc
70+
*
71+
* @param {{
72+
* foo: Bar,
73+
* bar: Baz
74+
* }} foo
75+
*
76+
*/
77+
function quux (foo) {
78+
79+
}
80+
`,
81+
},
82+
{
83+
code: `
84+
/* <- JSDoc must start with 2 stars.
85+
So this is unchecked.
86+
*/
87+
function quux (foo) {}
88+
`,
89+
},
90+
],
91+
};

‎test/rules/index.js

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,7 @@ const ruleTester = new RuleTester();
1313
'check-examples',
1414
'check-indentation',
1515
'check-param-names',
16+
'check-prefix',
1617
'check-syntax',
1718
'check-tag-names',
1819
'check-types',

0 commit comments

Comments
 (0)