Skip to content

Commit ea410c8

Browse files
Planeshifterkgryte
Planeshifter
and
kgryte
authored
build: add ESLint rule to enforce empty lines between requires and code
PR-URL: #5327 Closes: stdlib-js/metr-issue-tracker#42 Co-authored-by: Athan Reines <[email protected]> Reviewed-by: Athan Reines <[email protected]>
1 parent 9c04fbb commit ea410c8

File tree

10 files changed

+822
-2
lines changed

10 files changed

+822
-2
lines changed

‎etc/eslint/rules/stdlib.js

Lines changed: 45 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
1+
/* eslint-disable stdlib/jsdoc-doctest-marker, stdlib/jsdoc-doctest, stdlib/jsdoc-example-require-spacing, stdlib/jsdoc-no-tabs */
2+
13
/**
24
* @license Apache-2.0
35
*
@@ -16,8 +18,6 @@
1618
* limitations under the License.
1719
*/
1820

19-
/* eslint-disable stdlib/jsdoc-doctest-marker, stdlib/jsdoc-doctest */
20-
2121
'use strict';
2222

2323
/**
@@ -838,6 +838,49 @@ rules[ 'stdlib/jsdoc-emphasis-marker' ] = [ 'error', '_' ];
838838
*/
839839
rules[ 'stdlib/jsdoc-empty-line-before-example' ] = 'error';
840840

841+
/**
842+
* Enforce empty lines between requires and code in JSDoc examples.
843+
*
844+
* @name jsdoc-example-require-spacing
845+
* @memberof rules
846+
* @type {string}
847+
* @default 'error'
848+
*
849+
* @example
850+
* // Bad...
851+
*
852+
* /**
853+
* * Fréchet distribution constructor.
854+
* *
855+
* * @module @stdlib/stats/base/dists/frechet/ctor
856+
* *
857+
* * @example
858+
* * var Frechet = require( '@stdlib/stats/base/dists/frechet/ctor' );
859+
* * var frechet = new Frechet( 1.0, 1.0, 0.5 );
860+
* *
861+
* * var y = frechet.cdf( 0.8 );
862+
* * // returns ~0.036
863+
* *\/
864+
*
865+
* @example
866+
* // Good...
867+
*
868+
* /**
869+
* * Fréchet distribution constructor.
870+
* *
871+
* * @module @stdlib/stats/base/dists/frechet/ctor
872+
* *
873+
* * @example
874+
* * var Frechet = require( '@stdlib/stats/base/dists/frechet/ctor' );
875+
* *
876+
* * var frechet = new Frechet( 1.0, 1.0, 0.5 );
877+
* *
878+
* * var y = frechet.cdf( 0.8 );
879+
* * // returns ~0.036
880+
* *\/
881+
*/
882+
rules[ 'stdlib/jsdoc-example-require-spacing' ] = 'error';
883+
841884
/**
842885
* Require `\`` be used as the fenced code marker.
843886
*

‎lib/node_modules/@stdlib/_tools/eslint/rules/jsdoc-example-require-spacing/README.md

Lines changed: 159 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,159 @@
1+
<!--
2+
3+
@license Apache-2.0
4+
5+
Copyright (c) 2025 The Stdlib Authors.
6+
7+
Licensed under the Apache License, Version 2.0 (the "License");
8+
you may not use this file except in compliance with the License.
9+
You may obtain a copy of the License at
10+
11+
http://www.apache.org/licenses/LICENSE-2.0
12+
13+
Unless required by applicable law or agreed to in writing, software
14+
distributed under the License is distributed on an "AS IS" BASIS,
15+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16+
See the License for the specific language governing permissions and
17+
limitations under the License.
18+
19+
-->
20+
21+
# jsdoc-example-require-spacing
22+
23+
> [ESLint rule][eslint-rules] to enforce empty lines between `require` statements and code in JSDoc examples.
24+
25+
<section class="intro">
26+
27+
</section>
28+
29+
<!-- /.intro -->
30+
31+
<section class="usage">
32+
33+
## Usage
34+
35+
```javascript
36+
var rule = require( '@stdlib/_tools/eslint/rules/jsdoc-example-require-spacing' );
37+
```
38+
39+
#### rule
40+
41+
[ESLint rule][eslint-rules] to enforce empty lines between `require` statements and code in JSDoc examples.
42+
43+
**Bad**:
44+
45+
<!-- eslint stdlib/jsdoc-example-require-spacing: "off", @cspell/spellchecker: "off" -->
46+
47+
```javascript
48+
/**
49+
* Fréchet distribution constructor.
50+
*
51+
* @module @stdlib/stats/base/dists/frechet/ctor
52+
*
53+
* @example
54+
* var Frechet = require( '@stdlib/stats/base/dists/frechet/ctor' );
55+
* var frechet = new Frechet( 1.0, 1.0, 0.5 );
56+
*
57+
* var y = frechet.cdf( 0.8 );
58+
* // returns ~0.036
59+
*/
60+
```
61+
62+
**Good**:
63+
64+
<!-- eslint @cspell/spellchecker: "off" -->
65+
66+
```javascript
67+
/**
68+
* Fréchet distribution constructor.
69+
*
70+
* @module @stdlib/stats/base/dists/frechet/ctor
71+
*
72+
* @example
73+
* var Frechet = require( '@stdlib/stats/base/dists/frechet/ctor' );
74+
*
75+
* var frechet = new Frechet( 1.0, 1.0, 0.5 );
76+
*
77+
* var y = frechet.cdf( 0.8 );
78+
* // returns ~0.036
79+
*/
80+
```
81+
82+
</section>
83+
84+
<!-- /.usage -->
85+
86+
<section class="examples">
87+
88+
## Examples
89+
90+
<!-- eslint no-undef: "error" -->
91+
92+
```javascript
93+
var Linter = require( 'eslint' ).Linter;
94+
var rule = require( '@stdlib/_tools/eslint/rules/jsdoc-example-require-spacing' );
95+
96+
var linter = new Linter();
97+
var result;
98+
var code;
99+
100+
code = [
101+
'/**',
102+
'* Fréchet distribution constructor.',
103+
'*',
104+
'* @module @stdlib/stats/base/dists/frechet/ctor',
105+
'*',
106+
'* @example',
107+
'* var Frechet = require( \'@stdlib/stats/base/dists/frechet/ctor\' );',
108+
'* var frechet = new Frechet( 1.0, 1.0, 0.5 );',
109+
'*',
110+
'* var y = frechet.cdf( 0.8 );',
111+
'* // returns ~0.036',
112+
'*/',
113+
'function Frechet() {}'
114+
].join( '\n' );
115+
116+
linter.defineRule( 'jsdoc-example-require-spacing', rule );
117+
118+
result = linter.verify( code, {
119+
'rules': {
120+
'jsdoc-example-require-spacing': 'error'
121+
}
122+
});
123+
/* returns
124+
[
125+
{
126+
'ruleId': 'jsdoc-example-require-spacing',
127+
'severity': 2,
128+
'message': 'Missing empty line between require statement and code',
129+
'line': 13,
130+
'column': 1,
131+
'nodeType': 'FunctionDeclaration',
132+
'endLine': 13,
133+
'endColumn': 21
134+
}
135+
]
136+
*/
137+
```
138+
139+
</section>
140+
141+
<!-- /.examples -->
142+
143+
<!-- Section for related `stdlib` packages. Do not manually edit this section, as it is automatically populated. -->
144+
145+
<section class="related">
146+
147+
</section>
148+
149+
<!-- /.related -->
150+
151+
<!-- Section for all links. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
152+
153+
<section class="links">
154+
155+
[eslint-rules]: https://eslint.org/docs/developer-guide/working-with-rules
156+
157+
</section>
158+
159+
<!-- /.links -->

‎lib/node_modules/@stdlib/_tools/eslint/rules/jsdoc-example-require-spacing/examples/index.js

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
/**
2+
* @license Apache-2.0
3+
*
4+
* Copyright (c) 2025 The Stdlib Authors.
5+
*
6+
* Licensed under the Apache License, Version 2.0 (the "License");
7+
* you may not use this file except in compliance with the License.
8+
* You may obtain a copy of the License at
9+
*
10+
* http://www.apache.org/licenses/LICENSE-2.0
11+
*
12+
* Unless required by applicable law or agreed to in writing, software
13+
* distributed under the License is distributed on an "AS IS" BASIS,
14+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15+
* See the License for the specific language governing permissions and
16+
* limitations under the License.
17+
*/
18+
19+
'use strict';
20+
21+
var Linter = require( 'eslint' ).Linter;
22+
var rule = require( './../lib' );
23+
24+
var linter = new Linter();
25+
26+
// Valid example with empty line after require:
27+
var valid = [
28+
'/**',
29+
'* Fréchet distribution constructor.',
30+
'*',
31+
'* @example',
32+
'* var Frechet = require( \'@stdlib/stats/base/dists/frechet/ctor\' );',
33+
'*',
34+
'* var frechet = new Frechet( 1.0, 1.0, 0.5 );',
35+
'*',
36+
'* var y = frechet.cdf( 0.8 );',
37+
'* // returns ~0.036',
38+
'*/',
39+
'function Frechet() {}'
40+
].join( '\n' );
41+
42+
// Invalid example without empty line after require:
43+
var invalid = [
44+
'/**',
45+
'* Fréchet distribution constructor.',
46+
'*',
47+
'* @example',
48+
'* var Frechet = require( \'@stdlib/stats/base/dists/frechet/ctor\' );',
49+
'* var frechet = new Frechet( 1.0, 1.0, 0.5 );',
50+
'*',
51+
'* var y = frechet.cdf( 0.8 );',
52+
'* // returns ~0.036',
53+
'*/',
54+
'function Frechet() {}'
55+
].join( '\n' );
56+
57+
// Register the rule:
58+
linter.defineRule( 'jsdoc-example-require-spacing', rule );
59+
60+
// Lint the valid example:
61+
var validResult = linter.verify( valid, {
62+
'rules': {
63+
'jsdoc-example-require-spacing': 'error'
64+
}
65+
});
66+
console.log( 'Valid example - Number of errors: %d', validResult.length );
67+
68+
// Lint the invalid example:
69+
var invalidResult = linter.verify( invalid, {
70+
'rules': {
71+
'jsdoc-example-require-spacing': 'error'
72+
}
73+
});
74+
console.log( 'Invalid example - Number of errors: %d', invalidResult.length );
75+
console.log( 'Error message: %s', invalidResult[ 0 ].message );

‎lib/node_modules/@stdlib/_tools/eslint/rules/jsdoc-example-require-spacing/lib/index.js

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
/**
2+
* @license Apache-2.0
3+
*
4+
* Copyright (c) 2025 The Stdlib Authors.
5+
*
6+
* Licensed under the Apache License, Version 2.0 (the "License");
7+
* you may not use this file except in compliance with the License.
8+
* You may obtain a copy of the License at
9+
*
10+
* http://www.apache.org/licenses/LICENSE-2.0
11+
*
12+
* Unless required by applicable law or agreed to in writing, software
13+
* distributed under the License is distributed on an "AS IS" BASIS,
14+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15+
* See the License for the specific language governing permissions and
16+
* limitations under the License.
17+
*/
18+
19+
'use strict';
20+
21+
// MODULES //
22+
23+
var rule = require( './main.js' );
24+
25+
26+
// MAIN //
27+
28+
/**
29+
* ESLint rule to enforce empty lines between `require` statements and code in JSDoc examples.
30+
*
31+
* @module @stdlib/_tools/eslint/rules/jsdoc-example-require-spacing
32+
*
33+
* @example
34+
* var rule = require( '@stdlib/_tools/eslint/rules/jsdoc-example-require-spacing' );
35+
*
36+
* var config = {
37+
* 'rules': {
38+
* 'stdlib/jsdoc-example-require-spacing': 'error'
39+
* }
40+
* };
41+
*/
42+
43+
// EXPORTS //
44+
45+
module.exports = rule;

0 commit comments

Comments
 (0)