Skip to content

Commit f9b102d

Browse files
feat(lines-before-block): move start-of-block checking behind off-by-default checkBlockStarts option (#1341)
1 parent feba293 commit f9b102d

File tree

4 files changed

+212
-5
lines changed

4 files changed

+212
-5
lines changed

.README/rules/lines-before-block.md

+7-2
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,15 @@
11
# `lines-before-block`
22

33
This rule enforces minimum number of newlines before JSDoc comment blocks
4-
(except at the beginning of a file).
4+
(except at the beginning of a block or file).
55

66
## Options
77

8+
### `checkBlockStarts`
9+
10+
Whether to additionally check the start of blocks, such as classes or functions.
11+
Defaults to `false`.
12+
813
### `lines`
914

1015
The minimum number of lines to require. Defaults to 1.
@@ -26,7 +31,7 @@ lines before the block will not be added).
2631
|Tags|N/A|
2732
|Recommended|false|
2833
|Settings||
29-
|Options|`excludedTags`, `ignoreSameLine`, `lines`|
34+
|Options|`checkBlockStarts`, `excludedTags`, `ignoreSameLine`, `lines`|
3035

3136
## Failing examples
3237

docs/rules/lines-before-block.md

+66-2
Original file line numberDiff line numberDiff line change
@@ -3,12 +3,19 @@
33
# <code>lines-before-block</code>
44

55
This rule enforces minimum number of newlines before JSDoc comment blocks
6-
(except at the beginning of a file).
6+
(except at the beginning of a block or file).
77

88
<a name="user-content-lines-before-block-options"></a>
99
<a name="lines-before-block-options"></a>
1010
## Options
1111

12+
<a name="user-content-lines-before-block-options-checkblockstarts"></a>
13+
<a name="lines-before-block-options-checkblockstarts"></a>
14+
### <code>checkBlockStarts</code>
15+
16+
Whether to additionally check the start of blocks, such as classes or functions.
17+
Defaults to `false`.
18+
1219
<a name="user-content-lines-before-block-options-lines"></a>
1320
<a name="lines-before-block-options-lines"></a>
1421
### <code>lines</code>
@@ -36,7 +43,7 @@ lines before the block will not be added).
3643
|Tags|N/A|
3744
|Recommended|false|
3845
|Settings||
39-
|Options|`excludedTags`, `ignoreSameLine`, `lines`|
46+
|Options|`checkBlockStarts`, `excludedTags`, `ignoreSameLine`, `lines`|
4047

4148
<a name="user-content-lines-before-block-failing-examples"></a>
4249
<a name="lines-before-block-failing-examples"></a>
@@ -87,6 +94,42 @@ someCode;
8794
*
8895
*/
8996
// Message: Required 1 line(s) before JSDoc block
97+
98+
{
99+
/**
100+
* Description.
101+
*/
102+
let value;
103+
}
104+
// "jsdoc/lines-before-block": ["error"|"warn", {"checkBlockStarts":true}]
105+
// Message: Required 1 line(s) before JSDoc block
106+
107+
class MyClass {
108+
/**
109+
* Description.
110+
*/
111+
method() {}
112+
}
113+
// "jsdoc/lines-before-block": ["error"|"warn", {"checkBlockStarts":true}]
114+
// Message: Required 1 line(s) before JSDoc block
115+
116+
function myFunction() {
117+
/**
118+
* Description.
119+
*/
120+
let value;
121+
}
122+
// "jsdoc/lines-before-block": ["error"|"warn", {"checkBlockStarts":true}]
123+
// Message: Required 1 line(s) before JSDoc block
124+
125+
const values = [
126+
/**
127+
* Description.
128+
*/
129+
value,
130+
];
131+
// "jsdoc/lines-before-block": ["error"|"warn", {"checkBlockStarts":true}]
132+
// Message: Required 1 line(s) before JSDoc block
90133
````
91134

92135

@@ -146,5 +189,26 @@ const a = /** @lends SomeClass */ {
146189
someProp: (someVal)
147190
};
148191
// "jsdoc/lines-before-block": ["error"|"warn", {"excludedTags":["lends"],"ignoreSameLine":false}]
192+
193+
{
194+
/**
195+
* Description.
196+
*/
197+
let value;
198+
}
199+
200+
class MyClass {
201+
/**
202+
* Description.
203+
*/
204+
method() {}
205+
}
206+
207+
function myFunction() {
208+
/**
209+
* Description.
210+
*/
211+
let value;
212+
}
149213
````
150214

src/rules/linesBeforeBlock.js

+5-1
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@ export default iterateJsdoc(({
88
utils,
99
}) => {
1010
const {
11+
checkBlockStarts,
1112
lines = 1,
1213
ignoreSameLine = true,
1314
excludedTags = ['type']
@@ -19,7 +20,7 @@ export default iterateJsdoc(({
1920

2021
const tokensBefore = sourceCode.getTokensBefore(jsdocNode, {includeComments: true});
2122
const tokenBefore = tokensBefore.slice(-1)[0];
22-
if (!tokenBefore) {
23+
if (!tokenBefore || (tokenBefore.value === '{' && !checkBlockStarts)) {
2324
return;
2425
}
2526

@@ -80,6 +81,9 @@ export default iterateJsdoc(({
8081
{
8182
additionalProperties: false,
8283
properties: {
84+
checkBlockStarts: {
85+
type: 'boolean',
86+
},
8387
excludedTags: {
8488
type: 'array',
8589
items: {

test/rules/assertions/linesBeforeBlock.js

+134
Original file line numberDiff line numberDiff line change
@@ -161,6 +161,110 @@ export default {
161161
*/
162162
`,
163163
},
164+
{
165+
code: `
166+
{
167+
/**
168+
* Description.
169+
*/
170+
let value;
171+
}
172+
`,
173+
errors: [
174+
{
175+
line: 3,
176+
message: 'Required 1 line(s) before JSDoc block'
177+
}
178+
],
179+
options: [{ checkBlockStarts: true }],
180+
output: `
181+
{
182+
183+
/**
184+
* Description.
185+
*/
186+
let value;
187+
}
188+
`,
189+
},
190+
{
191+
code: `
192+
class MyClass {
193+
/**
194+
* Description.
195+
*/
196+
method() {}
197+
}
198+
`,
199+
errors: [
200+
{
201+
line: 3,
202+
message: 'Required 1 line(s) before JSDoc block'
203+
}
204+
],
205+
options: [{ checkBlockStarts: true }],
206+
output: `
207+
class MyClass {
208+
209+
/**
210+
* Description.
211+
*/
212+
method() {}
213+
}
214+
`,
215+
},
216+
{
217+
code: `
218+
function myFunction() {
219+
/**
220+
* Description.
221+
*/
222+
let value;
223+
}
224+
`,
225+
errors: [
226+
{
227+
line: 3,
228+
message: 'Required 1 line(s) before JSDoc block'
229+
}
230+
],
231+
options: [{ checkBlockStarts: true }],
232+
output: `
233+
function myFunction() {
234+
235+
/**
236+
* Description.
237+
*/
238+
let value;
239+
}
240+
`,
241+
},
242+
{
243+
code: `
244+
const values = [
245+
/**
246+
* Description.
247+
*/
248+
value,
249+
];
250+
`,
251+
errors: [
252+
{
253+
line: 3,
254+
message: 'Required 1 line(s) before JSDoc block'
255+
}
256+
],
257+
options: [{ checkBlockStarts: true }],
258+
output: `
259+
const values = [
260+
261+
/**
262+
* Description.
263+
*/
264+
value,
265+
];
266+
`,
267+
}
164268
],
165269
valid: [
166270
{
@@ -242,5 +346,35 @@ export default {
242346
}
243347
]
244348
},
349+
{
350+
code: `
351+
{
352+
/**
353+
* Description.
354+
*/
355+
let value;
356+
}
357+
`,
358+
},
359+
{
360+
code: `
361+
class MyClass {
362+
/**
363+
* Description.
364+
*/
365+
method() {}
366+
}
367+
`,
368+
},
369+
{
370+
code: `
371+
function myFunction() {
372+
/**
373+
* Description.
374+
*/
375+
let value;
376+
}
377+
`,
378+
}
245379
],
246380
};

0 commit comments

Comments
 (0)