Skip to content

Commit 62a56f5

Browse files
gajusgajus
authored
Merge pull request #186 from vulkd/vk/rule-check-alignment
feat: add rule check alignment
2 parents 676a617 + 9d22831 commit 62a56f5

File tree

7 files changed

+236
-0
lines changed

7 files changed

+236
-0
lines changed

‎.README/README.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,7 @@ This table maps the rules between `eslint-plugin-jsdoc` and `jscs-jsdoc`.
1414

1515
| `eslint-plugin-jsdoc` | `jscs-jsdoc` |
1616
| --- | --- |
17+
| [`check-alignment`](https://github.com/gajus/eslint-plugin-jsdoc#eslint-plugin-jsdoc-rules-check-alignment) | N/A |
1718
| [`check-examples`](https://github.com/gajus/eslint-plugin-jsdoc#eslint-plugin-jsdoc-rules-check-examples) | N/A |
1819
| [`check-param-names`](https://github.com/gajus/eslint-plugin-jsdoc#eslint-plugin-jsdoc-rules-check-param-names) | [`checkParamNames`](https://github.com/jscs-dev/jscs-jsdoc#checkparamnames) |
1920
| [`check-syntax`](https://github.com/gajus/eslint-plugin-jsdoc#eslint-plugin-jsdoc-rules-check-syntax) | N/A |
@@ -72,6 +73,7 @@ Finally, enable all of the rules that you would like to use.
7273
```json
7374
{
7475
"rules": {
76+
"jsdoc/check-alignment": 1,
7577
"jsdoc/check-examples": 1,
7678
"jsdoc/check-param-names": 1,
7779
"jsdoc/check-syntax": 1,
@@ -247,6 +249,7 @@ Finally, the following rule pertains to inline disable directives:
247249

248250
## Rules
249251

252+
{"gitdown": "include", "file": "./rules/check-alignment.md"}
250253
{"gitdown": "include", "file": "./rules/check-examples.md"}
251254
{"gitdown": "include", "file": "./rules/check-param-names.md"}
252255
{"gitdown": "include", "file": "./rules/check-syntax.md"}

‎.README/rules/check-alignment.md

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
### `check-alignment`
2+
3+
Reports invalid alignment of JSDoc block asterisks.
4+
5+
|||
6+
|---|---|
7+
|Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`|
8+
|Tags|N/A|
9+
10+
<!-- assertions checkAlignment -->

‎README.md

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,7 @@ JSDoc linting rules for ESLint.
1717
* [Allow `@override` Without Accompanying `@param` Tags](#eslint-plugin-jsdoc-settings-allow-override-without-accompanying-param-tags)
1818
* [Settings to Configure `check-examples`](#eslint-plugin-jsdoc-settings-settings-to-configure-check-examples)
1919
* [Rules](#eslint-plugin-jsdoc-rules)
20+
* [`check-alignment`](#eslint-plugin-jsdoc-rules-check-alignment)
2021
* [`check-examples`](#eslint-plugin-jsdoc-rules-check-examples)
2122
* [`check-param-names`](#eslint-plugin-jsdoc-rules-check-param-names)
2223
* [`check-syntax`](#eslint-plugin-jsdoc-rules-check-syntax)
@@ -46,6 +47,7 @@ This table maps the rules between `eslint-plugin-jsdoc` and `jscs-jsdoc`.
4647

4748
| `eslint-plugin-jsdoc` | `jscs-jsdoc` |
4849
| --- | --- |
50+
| [`check-alignment`](https://github.com/gajus/eslint-plugin-jsdoc#eslint-plugin-jsdoc-rules-check-alignment) | N/A |
4951
| [`check-examples`](https://github.com/gajus/eslint-plugin-jsdoc#eslint-plugin-jsdoc-rules-check-examples) | N/A |
5052
| [`check-param-names`](https://github.com/gajus/eslint-plugin-jsdoc#eslint-plugin-jsdoc-rules-check-param-names) | [`checkParamNames`](https://github.com/jscs-dev/jscs-jsdoc#checkparamnames) |
5153
| [`check-syntax`](https://github.com/gajus/eslint-plugin-jsdoc#eslint-plugin-jsdoc-rules-check-syntax) | N/A |
@@ -106,6 +108,7 @@ Finally, enable all of the rules that you would like to use.
106108
```json
107109
{
108110
"rules": {
111+
"jsdoc/check-alignment": 1,
109112
"jsdoc/check-examples": 1,
110113
"jsdoc/check-param-names": 1,
111114
"jsdoc/check-syntax": 1,
@@ -288,6 +291,87 @@ Finally, the following rule pertains to inline disable directives:
288291
<a name="eslint-plugin-jsdoc-rules"></a>
289292
## Rules
290293

294+
<a name="eslint-plugin-jsdoc-rules-check-alignment"></a>
295+
### <code>check-alignment</code>
296+
297+
Reports invalid alignment of JSDoc block asterisks.
298+
299+
|||
300+
|---|---|
301+
|Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`|
302+
|Tags|N/A|
303+
304+
The following patterns are considered problems:
305+
306+
````js
307+
/**
308+
* @param {Number} foo
309+
*/
310+
function quux (foo) {
311+
312+
}
313+
// Message: Expected JSDoc block to be aligned.
314+
315+
/**
316+
* @param {Number} foo
317+
*/
318+
function quux (foo) {
319+
320+
}
321+
// Message: Expected JSDoc block to be aligned.
322+
323+
/**
324+
* @param {Number} foo
325+
*/
326+
function quux (foo) {
327+
328+
}
329+
// Message: Expected JSDoc block to be aligned.
330+
331+
/**
332+
* @param {Number} foo
333+
*/
334+
function quux (foo) {
335+
336+
}
337+
// Message: Expected JSDoc block to be aligned.
338+
339+
/**
340+
* @param {Number} foo
341+
*/
342+
function quux (foo) {
343+
344+
}
345+
// Message: Expected JSDoc block to be aligned.
346+
````
347+
348+
The following patterns are not considered problems:
349+
350+
````js
351+
/**
352+
* Desc
353+
*
354+
* @param {Number} foo
355+
*/
356+
function quux (foo) {
357+
358+
}
359+
360+
/**
361+
* Desc
362+
*
363+
* @param {{
364+
foo: Bar,
365+
bar: Baz
366+
* }} foo
367+
*
368+
*/
369+
function quux (foo) {
370+
371+
}
372+
````
373+
374+
291375
<a name="eslint-plugin-jsdoc-rules-check-examples"></a>
292376
### <code>check-examples</code>
293377

‎src/index.js

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
11
/* eslint-disable import/max-dependencies */
2+
import checkAlignment from './rules/checkAlignment';
23
import checkExamples from './rules/checkExamples';
34
import checkParamNames from './rules/checkParamNames';
45
import checkSyntax from './rules/checkSyntax';
@@ -24,6 +25,7 @@ export default {
2425
configs: {
2526
recommended: {
2627
rules: {
28+
'jsdoc/check-alignment': 'warn',
2729
'jsdoc/check-examples': 'off',
2830
'jsdoc/check-param-names': 'warn',
2931
'jsdoc/check-syntax': 'off',
@@ -48,6 +50,7 @@ export default {
4850
}
4951
},
5052
rules: {
53+
'check-alignment': checkAlignment,
5154
'check-examples': checkExamples,
5255
'check-param-names': checkParamNames,
5356
'check-syntax': checkSyntax,

‎src/rules/checkAlignment.js

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
import iterateJsdoc from '../iterateJsdoc';
2+
3+
export default iterateJsdoc(({
4+
sourceCode,
5+
jsdocNode,
6+
report,
7+
indent
8+
}) => {
9+
// `indent` is whitespace from line 1 (`/**`), so slice and account for "/".
10+
const indentLevel = indent.length + 1;
11+
const sourceLines = sourceCode.getText(jsdocNode).split('\n')
12+
.slice(1)
13+
.map((line) => {
14+
return line.split('*')[0];
15+
})
16+
.filter((line) => {
17+
return !line.trim().length;
18+
});
19+
20+
for (const line of sourceLines) {
21+
if (line.length !== indentLevel) {
22+
report('Expected JSDoc block to be aligned.');
23+
break;
24+
}
25+
}
26+
});

‎test/rules/assertions/checkAlignment.js

Lines changed: 109 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,109 @@
1+
export default {
2+
invalid: [
3+
{
4+
code: `
5+
/**
6+
* @param {Number} foo
7+
*/
8+
function quux (foo) {
9+
10+
}
11+
`,
12+
errors: [
13+
{
14+
message: 'Expected JSDoc block to be aligned.'
15+
}
16+
]
17+
},
18+
{
19+
code: `
20+
/**
21+
* @param {Number} foo
22+
*/
23+
function quux (foo) {
24+
25+
}
26+
`,
27+
errors: [
28+
{
29+
message: 'Expected JSDoc block to be aligned.'
30+
}
31+
]
32+
},
33+
{
34+
code: `
35+
/**
36+
* @param {Number} foo
37+
*/
38+
function quux (foo) {
39+
40+
}
41+
`,
42+
errors: [
43+
{
44+
message: 'Expected JSDoc block to be aligned.'
45+
}
46+
]
47+
},
48+
{
49+
code: `
50+
/**
51+
* @param {Number} foo
52+
*/
53+
function quux (foo) {
54+
55+
}
56+
`,
57+
errors: [
58+
{
59+
message: 'Expected JSDoc block to be aligned.'
60+
}
61+
]
62+
},
63+
{
64+
code: `
65+
/**
66+
* @param {Number} foo
67+
*/
68+
function quux (foo) {
69+
70+
}
71+
`,
72+
errors: [
73+
{
74+
message: 'Expected JSDoc block to be aligned.'
75+
}
76+
]
77+
}
78+
],
79+
valid: [
80+
{
81+
code: `
82+
/**
83+
* Desc
84+
*
85+
* @param {Number} foo
86+
*/
87+
function quux (foo) {
88+
89+
}
90+
`
91+
},
92+
{
93+
code: `
94+
/**
95+
* Desc
96+
*
97+
* @param {{
98+
foo: Bar,
99+
bar: Baz
100+
* }} foo
101+
*
102+
*/
103+
function quux (foo) {
104+
105+
}
106+
`
107+
}
108+
]
109+
};

‎test/rules/index.js

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@ import config from '../../src';
77
const ruleTester = new RuleTester();
88

99
_.forEach([
10+
'check-alignment',
1011
'check-examples',
1112
'check-param-names',
1213
'check-syntax',

0 commit comments

Comments
 (0)