Skip to content

Commit 20b7235

Browse files
PlaneshifterPlaneshifter
committed
feat: add doctest-annotation-spacing ESLint rule
This rule enforces spacing in return annotations in single-line comments (`// returns` and `// =>`). It validates: - Exactly 1 space between `//` and the annotation keyword - Configurable spacing after the keyword (default: 1 space) --- type: pre_commit_static_analysis_report description: Results of running static analysis checks when committing changes. report: - task: lint_filenames status: passed - task: lint_editorconfig status: passed - task: lint_markdown status: passed - task: lint_package_json status: passed - task: lint_repl_help status: na - task: lint_javascript_src status: passed - task: lint_javascript_cli status: na - task: lint_javascript_examples status: passed - task: lint_javascript_tests status: passed - task: lint_javascript_benchmarks status: na - task: lint_python status: na - task: lint_r status: na - task: lint_c_src status: na - task: lint_c_examples status: na - task: lint_c_benchmarks status: na - task: lint_c_tests_fixtures status: na - task: lint_shell status: na - task: lint_typescript_declarations status: passed - task: lint_typescript_tests status: na - task: lint_license_headers status: passed ---
1 parent e7fbc24 commit 20b7235

9 files changed

Lines changed: 1019 additions & 0 deletions

File tree

‎lib/node_modules/@stdlib/_tools/eslint/rules/doctest-annotation-spacing/README.md‎

Lines changed: 182 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,182 @@
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+
# doctest-annotation-spacing
22+
23+
> [ESLint rule][eslint-rules] to enforce spacing in return annotations in single-line comments.
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/doctest-annotation-spacing' );
37+
```
38+
39+
#### rule
40+
41+
[ESLint rule][eslint-rules] to enforce spacing in return annotations in single-line comments. The rule checks `// returns` and `// =>` annotations (including `// e.g., returns` and `// e.g., =>` variants) and ensures:
42+
43+
- Exactly 1 space between `//` and the annotation keyword
44+
- The configured number of spaces after the annotation keyword (default: 1)
45+
46+
**Bad** (too many spaces after `returns`):
47+
48+
```text
49+
var v = 3.14;
50+
// returns 3.14
51+
```
52+
53+
**Bad** (no space before `=>`):
54+
55+
```text
56+
console.log( 'beep' );
57+
//=> 'beep'
58+
```
59+
60+
**Bad** (too many spaces before `returns`):
61+
62+
```text
63+
var x = true;
64+
// returns true
65+
```
66+
67+
**Good**:
68+
69+
```javascript
70+
var v = 3.14;
71+
// returns 3.14
72+
73+
console.log( 'beep' );
74+
// => 'beep'
75+
```
76+
77+
## Options
78+
79+
The rule accepts an options object with the following property:
80+
81+
- **numSpaces**: number of spaces required after the annotation keyword. Default: `1`.
82+
83+
```javascript
84+
// With numSpaces: 2, the following would be valid:
85+
var v = 3.14;
86+
// returns 3.14
87+
```
88+
89+
Note: The spacing before the annotation keyword is always enforced to be exactly 1 space and is not configurable.
90+
91+
</section>
92+
93+
<!-- /.usage -->
94+
95+
<section class="notes">
96+
97+
## Notes
98+
99+
- This rule only applies to single-line comments (starting with `//`). Multi-line comments (`/* ... */`) are ignored.
100+
101+
- The rule matches the following patterns:
102+
103+
- `// returns`
104+
- `// =>`
105+
- `// e.g., returns`
106+
- `// e.g., =>`
107+
108+
- The rule enforces two spacing requirements:
109+
110+
- Exactly 1 space after `//` (not configurable)
111+
- Configurable spacing after the keyword (default: 1 space)
112+
113+
</section>
114+
115+
<!-- /.notes -->
116+
117+
<section class="examples">
118+
119+
## Examples
120+
121+
<!-- eslint no-undef: "error" -->
122+
123+
```javascript
124+
var Linter = require( 'eslint' ).Linter;
125+
var rule = require( '@stdlib/_tools/eslint/rules/doctest-annotation-spacing' );
126+
127+
var linter = new Linter();
128+
var result;
129+
var code;
130+
131+
code = [
132+
'var v = foo();',
133+
'// returns \'beep\'',
134+
'',
135+
'console.log( bar() );',
136+
'// => \'boop\''
137+
].join( '\n' );
138+
139+
linter.defineRule( 'doctest-annotation-spacing', rule );
140+
141+
result = linter.verify( code, {
142+
'rules': {
143+
'doctest-annotation-spacing': 'error'
144+
}
145+
});
146+
/* returns
147+
[
148+
{
149+
'ruleId': 'doctest-annotation-spacing',
150+
'severity': 2,
151+
'message': 'Return annotation `returns` should be followed by 1 space(s). Found 13 space(s).',
152+
'line': 2,
153+
'column': 1,
154+
'nodeType': null,
155+
'endLine': 2,
156+
'endColumn': 31
157+
}
158+
]
159+
*/
160+
```
161+
162+
</section>
163+
164+
<!-- /.examples -->
165+
166+
<!-- Section for related `stdlib` packages. Do not manually edit this section, as it is automatically populated. -->
167+
168+
<section class="related">
169+
170+
</section>
171+
172+
<!-- /.related -->
173+
174+
<!-- Section for all links. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
175+
176+
<section class="links">
177+
178+
[eslint-rules]: https://eslint.org/docs/developer-guide/working-with-rules
179+
180+
</section>
181+
182+
<!-- /.links -->

‎lib/node_modules/@stdlib/_tools/eslint/rules/doctest-annotation-spacing/examples/index.js‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
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+
var result;
26+
var code;
27+
28+
code = [
29+
'var v = foo();',
30+
'// returns \'beep\'',
31+
'',
32+
'console.log( bar() );',
33+
'// => \'boop\''
34+
].join( '\n' );
35+
36+
linter.defineRule( 'doctest-annotation-spacing', rule );
37+
38+
result = linter.verify( code, {
39+
'rules': {
40+
'doctest-annotation-spacing': 'error'
41+
}
42+
});
43+
console.log( result );
44+
/* =>
45+
[
46+
{
47+
'ruleId': 'doctest-annotation-spacing',
48+
'severity': 2,
49+
'message': 'Return annotation `returns` should be followed by 1 space(s). Found 13 space(s).',
50+
'line': 2,
51+
'column': 1,
52+
'nodeType': null,
53+
'endLine': 2,
54+
'endColumn': 31
55+
}
56+
]
57+
*/

‎lib/node_modules/@stdlib/_tools/eslint/rules/doctest-annotation-spacing/lib/defaults.json‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
{
2+
"numSpaces": 1
3+
}

‎lib/node_modules/@stdlib/_tools/eslint/rules/doctest-annotation-spacing/lib/index.js‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
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+
/**
22+
* ESLint rule to enforce spacing after return annotations in single-line comments.
23+
*
24+
* @module @stdlib/_tools/eslint/rules/doctest-annotation-spacing
25+
*
26+
* @example
27+
* var rule = require( '@stdlib/_tools/eslint/rules/doctest-annotation-spacing' );
28+
*
29+
* console.log( rule );
30+
*/
31+
32+
// MODULES //
33+
34+
var main = require( './main.js' );
35+
36+
37+
// EXPORTS //
38+
39+
module.exports = main;

0 commit comments

Comments
 (0)