Skip to content

Commit 75c21e7

Browse files
brettz9brettz9
committed
feat(no-lines-after-blocks): add rule; fixes #1211
Prevents lines intervening between functions or other structures and JSDoc blocks
1 parent f72ac1a commit 75c21e7

File tree

11 files changed

+774
-1
lines changed

11 files changed

+774
-1
lines changed

‎.README/rules/no-lines-after-blocks.md‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
# `no-lines-after-blocks`
2+
3+
Reports extra lines between functions (and other language structures) and their
4+
JSDoc blocks.
5+
6+
Standalone comments such as `@typedef` and `@callback` will not be reported even
7+
if they are followed by a language structure.
8+
9+
## Fixer
10+
11+
Removes extra lines between functions (and other language structures) and their
12+
JSDoc blocks. Uses the `maxLines` setting to determine whether to remove lines.
13+
14+
## Options
15+
16+
{"gitdown": "options"}
17+
18+
|||
19+
|---|---|
20+
|Context|everywhere|
21+
|Tags|N/A|
22+
|Recommended|false|
23+
|Settings|`maxLines`, `minLines`|
24+
|Options|`contexts`, `enableFixer`, `exemptedBy`, `overrideDefaultExemptions`, `preferMinLines`|
25+
26+
## Failing examples
27+
28+
<!-- assertions-failing noLinesAfterBlocks -->
29+
30+
## Passing examples
31+
32+
<!-- assertions-passing noLinesAfterBlocks -->

‎README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -453,6 +453,7 @@ non-default-recommended fixer).
453453
||:wrench:| [no-blank-block-descriptions](./docs/rules/no-blank-block-descriptions.md#readme) | If tags are present, this rule will prevent empty lines in the block description. If no tags are present, this rule will prevent extra empty lines in the block description. |
454454
||:wrench:| [no-blank-blocks](./docs/rules/no-blank-blocks.md#readme) | Removes empty blocks with nothing but possibly line breaks |
455455
|:heavy_check_mark:|:wrench:| [no-defaults](./docs/rules/no-defaults.md#readme) | This rule reports defaults being used on the relevant portion of `@param` or `@default`. |
456+
||:wrench:| [no-lines-after-blocks](./docs/rules/no-lines-after-blocks.md#readme) | Reports extra lines between functions (and other language structures) and their JSDoc blocks. |
456457
||| [no-missing-syntax](./docs/rules/no-missing-syntax.md#readme) | Reports when certain comment structures are always expected. |
457458
|:heavy_check_mark:|:wrench:| [no-multi-asterisks](./docs/rules/no-multi-asterisks.md#readme) | Prevents use of multiple asterisks at the beginning of lines. |
458459
||| [no-restricted-syntax](./docs/rules/no-restricted-syntax.md#readme) | Reports when certain comment structures are present. |

‎docs/rules/no-lines-after-blocks.md‎

Lines changed: 181 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,181 @@
1+
<a name="user-content-no-lines-after-blocks"></a>
2+
<a name="no-lines-after-blocks"></a>
3+
# <code>no-lines-after-blocks</code>
4+
5+
Reports extra lines between functions (and other language structures) and their
6+
JSDoc blocks.
7+
8+
Standalone comments such as `@typedef` and `@callback` will not be reported even
9+
if they are followed by a language structure.
10+
11+
<a name="user-content-no-lines-after-blocks-fixer"></a>
12+
<a name="no-lines-after-blocks-fixer"></a>
13+
## Fixer
14+
15+
Removes extra lines between functions (and other language structures) and their
16+
JSDoc blocks. Uses the `maxLines` setting to determine whether to remove lines.
17+
18+
<a name="user-content-no-lines-after-blocks-options"></a>
19+
<a name="no-lines-after-blocks-options"></a>
20+
## Options
21+
22+
A single options object has the following properties.
23+
24+
<a name="user-content-no-lines-after-blocks-options-contexts"></a>
25+
<a name="no-lines-after-blocks-options-contexts"></a>
26+
### <code>contexts</code>
27+
28+
Set this to an array of strings representing the AST context (or an object with
29+
`context` and `comment` properties) where you wish the rule to be applied.
30+
31+
`context` defaults to `any` and `comment` defaults to no specific comment context.
32+
33+
Overrides the default contexts (`ArrowFunctionExpression`, `FunctionDeclaration`,
34+
`FunctionExpression`). Setting to `"any"` may be problematic if you have
35+
JSDoc-style comments at the top of your files.
36+
37+
See the ["AST and Selectors"](#user-content-eslint-plugin-jsdoc-advanced-ast-and-selectors)
38+
section of our Advanced docs for more on the expected format.
39+
<a name="user-content-no-lines-after-blocks-options-enablefixer"></a>
40+
<a name="no-lines-after-blocks-options-enablefixer"></a>
41+
### <code>enableFixer</code>
42+
43+
Whether to enable the fixer to remove line breaks
44+
<a name="user-content-no-lines-after-blocks-options-exemptedby"></a>
45+
<a name="no-lines-after-blocks-options-exemptedby"></a>
46+
### <code>exemptedBy</code>
47+
48+
Tag names to be added to those which will exempt reporting for a block. Defaults to:
49+
50+
- 'callback'
51+
- 'copyright'
52+
- 'exports'
53+
- 'interface'
54+
- 'event'
55+
- 'external'
56+
- 'file'
57+
- 'fileoverview'
58+
- 'host'
59+
- 'import'
60+
- 'license'
61+
- 'module'
62+
- 'namespace'
63+
- 'overview'
64+
- 'typedef'
65+
66+
<a name="user-content-no-lines-after-blocks-options-overridedefaultexemptions"></a>
67+
<a name="no-lines-after-blocks-options-overridedefaultexemptions"></a>
68+
### <code>overrideDefaultExemptions</code>
69+
70+
Determines whether `exemptedBy` will override the default values. Defaults to `false`.
71+
<a name="user-content-no-lines-after-blocks-options-preferminlines"></a>
72+
<a name="no-lines-after-blocks-options-preferminlines"></a>
73+
### <code>preferMinLines</code>
74+
75+
Whether to use the setting `minLines` as the basis for fixing lines going past `maxLines`
76+
77+
78+
|||
79+
|---|---|
80+
|Context|everywhere|
81+
|Tags|N/A|
82+
|Recommended|false|
83+
|Settings|`maxLines`, `minLines`|
84+
|Options|`contexts`, `enableFixer`, `exemptedBy`, `overrideDefaultExemptions`, `preferMinLines`|
85+
86+
<a name="user-content-no-lines-after-blocks-failing-examples"></a>
87+
<a name="no-lines-after-blocks-failing-examples"></a>
88+
## Failing examples
89+
90+
The following patterns are considered problems:
91+
92+
````ts
93+
/** This is a description of some function!*/
94+
95+
96+
97+
98+
99+
100+
function someFunction() {}
101+
// Message: There should be no extra lines above structures with JSDoc blocks
102+
103+
/** This is a description of some function!*/
104+
105+
function someFunction() {}
106+
// "jsdoc/no-lines-after-blocks": ["error"|"warn", {"enableFixer":false}]
107+
// Message: There should be no extra lines above structures with JSDoc blocks
108+
109+
/** This is a description of some function!*/
110+
111+
112+
function someFunction() {}
113+
// Settings: {"jsdoc":{"maxLines":2}}
114+
// Message: There should be no extra lines above structures with JSDoc blocks
115+
116+
/** This is a description of some function!*/
117+
118+
119+
function someFunction() {}
120+
// Settings: {"jsdoc":{"maxLines":2,"minLines":1}}
121+
// "jsdoc/no-lines-after-blocks": ["error"|"warn", {"preferMinLines":true}]
122+
// Message: There should be no extra lines above structures with JSDoc blocks
123+
124+
/** @typedef SomeType */
125+
126+
function someFunction() {}
127+
// "jsdoc/no-lines-after-blocks": ["error"|"warn", {"exemptedBy":["function"],"overrideDefaultExemptions":true}]
128+
// Message: There should be no extra lines above structures with JSDoc blocks
129+
````
130+
131+
132+
133+
<a name="user-content-no-lines-after-blocks-passing-examples"></a>
134+
<a name="no-lines-after-blocks-passing-examples"></a>
135+
## Passing examples
136+
137+
The following patterns are not considered problems:
138+
139+
````ts
140+
function someFunction() {}
141+
142+
/** JSDoc */ function someFunction() {}
143+
144+
/** This is a description of some function! */
145+
// extra comment
146+
function someFunction() {}
147+
148+
/** Standalone comment (e.g. a type definition) */
149+
150+
/** The actual description */
151+
function someFunction() {}
152+
153+
/* Regular block comment */
154+
155+
function someFunction() {}
156+
157+
// Regular line comment
158+
159+
function someFunction() {}
160+
161+
/** This is a description of some function!*/
162+
163+
function someFunction() {}
164+
// Settings: {"jsdoc":{"maxLines":2}}
165+
166+
/** @typedef {string} SomeType */
167+
168+
function someFunction() {}
169+
170+
/** @function SomeType */
171+
172+
function someFunction() {}
173+
// "jsdoc/no-lines-after-blocks": ["error"|"warn", {"exemptedBy":["function"]}]
174+
175+
/**
176+
* JSDoc block at top of file without import declaration context.
177+
*/
178+
179+
import {sth} from 'sth';
180+
````
181+

‎docs/rules/no-lines-before-blocks.md‎

Lines changed: 115 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,115 @@
1+
<a name="user-content-no-lines-before-blocks"></a>
2+
<a name="no-lines-before-blocks"></a>
3+
# <code>no-lines-before-blocks</code>
4+
5+
Reports extra lines between functions (and other language structures) and their
6+
JSDoc blocks.
7+
8+
<a name="user-content-no-lines-before-blocks-fixer"></a>
9+
<a name="no-lines-before-blocks-fixer"></a>
10+
## Fixer
11+
12+
Removes extra lines between functions (and other language structures) and their
13+
JSDoc blocks. Uses the `maxLines` setting to determine whether to remove lines.
14+
15+
<a name="user-content-no-lines-before-blocks-options"></a>
16+
<a name="no-lines-before-blocks-options"></a>
17+
## Options
18+
19+
A single options object has the following properties.
20+
21+
<a name="user-content-no-lines-before-blocks-options-enablefixer"></a>
22+
<a name="no-lines-before-blocks-options-enablefixer"></a>
23+
### <code>enableFixer</code>
24+
25+
Whether to enable the fixer to remove line breaks
26+
<a name="user-content-no-lines-before-blocks-options-preferminlines"></a>
27+
<a name="no-lines-before-blocks-options-preferminlines"></a>
28+
### <code>preferMinLines</code>
29+
30+
Whether to use the setting `minLines` as the basis for fixing lines going past `maxLines`
31+
32+
33+
|||
34+
|---|---|
35+
|Context|everywhere|
36+
|Tags|N/A|
37+
|Recommended|true|
38+
|Settings|`maxLines`, `minLines`|
39+
|Options|`enableFixer`, `preferMinLines`|
40+
41+
<a name="user-content-no-lines-before-blocks-failing-examples"></a>
42+
<a name="no-lines-before-blocks-failing-examples"></a>
43+
## Failing examples
44+
45+
The following patterns are considered problems:
46+
47+
````ts
48+
/** This is a description of some function!*/
49+
50+
51+
52+
53+
54+
55+
function someFunction() {}
56+
// Message: There should be no extra lines above structures with JSDoc blocks
57+
58+
/** This is a description of some function!*/
59+
60+
function someFunction() {}
61+
// "jsdoc/no-lines-before-blocks": ["error"|"warn", {"enableFixer":false}]
62+
// Message: There should be no extra lines above structures with JSDoc blocks
63+
64+
/** This is a description of some function!*/
65+
66+
67+
function someFunction() {}
68+
// Settings: {"jsdoc":{"maxLines":2}}
69+
// Message: There should be no extra lines above structures with JSDoc blocks
70+
71+
/** This is a description of some function!*/
72+
73+
74+
function someFunction() {}
75+
// Settings: {"jsdoc":{"maxLines":2,"minLines":1}}
76+
// "jsdoc/no-lines-before-blocks": ["error"|"warn", {"preferMinLines":true}]
77+
// Message: There should be no extra lines above structures with JSDoc blocks
78+
````
79+
80+
81+
82+
<a name="user-content-no-lines-before-blocks-passing-examples"></a>
83+
<a name="no-lines-before-blocks-passing-examples"></a>
84+
## Passing examples
85+
86+
The following patterns are not considered problems:
87+
88+
````ts
89+
function someFunction() {}
90+
91+
/** JSDoc */ function someFunction() {}
92+
93+
/** This is a description of some function! */
94+
// extra comment
95+
function someFunction() {}
96+
97+
/** Standalone comment (e.g. a type definition) */
98+
99+
/** The actual description */
100+
function someFunction() {}
101+
102+
/* Regular block comment */
103+
104+
function someFunction() {}
105+
106+
// Regular line comment
107+
108+
function someFunction() {}
109+
110+
/** This is a description of some function!*/
111+
112+
function someFunction() {}
113+
// Settings: {"jsdoc":{"maxLines":2}}
114+
````
115+

‎src/index-cjs.js‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,7 @@ import noBadBlocks from './rules/noBadBlocks.js';
3232
import noBlankBlockDescriptions from './rules/noBlankBlockDescriptions.js';
3333
import noBlankBlocks from './rules/noBlankBlocks.js';
3434
import noDefaults from './rules/noDefaults.js';
35+
import noLinesAfterBlocks from './rules/noLinesAfterBlocks.js';
3536
import noMissingSyntax from './rules/noMissingSyntax.js';
3637
import noMultiAsterisks from './rules/noMultiAsterisks.js';
3738
import noRestrictedSyntax from './rules/noRestrictedSyntax.js';
@@ -112,6 +113,7 @@ index.rules = {
112113
'no-blank-block-descriptions': noBlankBlockDescriptions,
113114
'no-blank-blocks': noBlankBlocks,
114115
'no-defaults': noDefaults,
116+
'no-lines-after-blocks': noLinesAfterBlocks,
115117
'no-missing-syntax': noMissingSyntax,
116118
'no-multi-asterisks': noMultiAsterisks,
117119
'no-restricted-syntax': noRestrictedSyntax,
@@ -296,6 +298,7 @@ const createRecommendedRuleset = (warnOrError, flatName) => {
296298
'jsdoc/no-blank-block-descriptions': 'off',
297299
'jsdoc/no-blank-blocks': 'off',
298300
'jsdoc/no-defaults': warnOrError,
301+
'jsdoc/no-lines-after-blocks': 'off',
299302
'jsdoc/no-missing-syntax': 'off',
300303
'jsdoc/no-multi-asterisks': warnOrError,
301304
'jsdoc/no-restricted-syntax': 'off',

‎src/index.js‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -38,6 +38,7 @@ import noBadBlocks from './rules/noBadBlocks.js';
3838
import noBlankBlockDescriptions from './rules/noBlankBlockDescriptions.js';
3939
import noBlankBlocks from './rules/noBlankBlocks.js';
4040
import noDefaults from './rules/noDefaults.js';
41+
import noLinesAfterBlocks from './rules/noLinesAfterBlocks.js';
4142
import noMissingSyntax from './rules/noMissingSyntax.js';
4243
import noMultiAsterisks from './rules/noMultiAsterisks.js';
4344
import noRestrictedSyntax from './rules/noRestrictedSyntax.js';
@@ -118,6 +119,7 @@ index.rules = {
118119
'no-blank-block-descriptions': noBlankBlockDescriptions,
119120
'no-blank-blocks': noBlankBlocks,
120121
'no-defaults': noDefaults,
122+
'no-lines-after-blocks': noLinesAfterBlocks,
121123
'no-missing-syntax': noMissingSyntax,
122124
'no-multi-asterisks': noMultiAsterisks,
123125
'no-restricted-syntax': noRestrictedSyntax,
@@ -302,6 +304,7 @@ const createRecommendedRuleset = (warnOrError, flatName) => {
302304
'jsdoc/no-blank-block-descriptions': 'off',
303305
'jsdoc/no-blank-blocks': 'off',
304306
'jsdoc/no-defaults': warnOrError,
307+
'jsdoc/no-lines-after-blocks': 'off',
305308
'jsdoc/no-missing-syntax': 'off',
306309
'jsdoc/no-multi-asterisks': warnOrError,
307310
'jsdoc/no-restricted-syntax': 'off',

0 commit comments

Comments
 (0)