Skip to content

Commit 987214f

Browse files
authored
feat: split require-returns in two rules and fix bug #142 (#147)
BREAKING CHANGE: * require-returns rule is split into two rules:
2 parents 668941c + a5f5221 commit 987214f

File tree

7 files changed

+128
-4
lines changed

7 files changed

+128
-4
lines changed

.README/README.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,7 @@ This table maps the rules between `eslint-plugin-jsdoc` and `jscs-jsdoc`.
2828
| [`require-param-name`](https://github.com/gajus/eslint-plugin-jsdoc#eslint-plugin-jsdoc-rules-require-param-name) | N/A |
2929
| [`require-param-type`](https://github.com/gajus/eslint-plugin-jsdoc#eslint-plugin-jsdoc-rules-require-param-type) | [`requireParamTypes`](https://github.com/jscs-dev/jscs-jsdoc#requireparamtypes) |
3030
| [`require-returns`](https://github.com/gajus/eslint-plugin-jsdoc#eslint-plugin-jsdoc-rules-require-returns) | [`requireReturn`](https://github.com/jscs-dev/jscs-jsdoc#requirereturn) |
31+
| [`require-returns-check`](https://github.com/gajus/eslint-plugin-jsdoc#eslint-plugin-jsdoc-rules-require-returns-check) | [`requireReturn`](https://github.com/jscs-dev/jscs-jsdoc#requirereturncheck) |
3132
| [`require-returns-description`](https://github.com/gajus/eslint-plugin-jsdoc#eslint-plugin-jsdoc-rules-require-returns-description) | [`requireReturnDescription`](https://github.com/jscs-dev/jscs-jsdoc#requirereturndescription) |
3233
| [`require-returns-type`](https://github.com/gajus/eslint-plugin-jsdoc#eslint-plugin-jsdoc-rules-require-returns-type) | [`requireReturnTypes`](https://github.com/jscs-dev/jscs-jsdoc#requirereturntypes) |
3334
| [`valid-types`](https://github.com/gajus/eslint-plugin-jsdoc#eslint-plugin-jsdoc-rules-valid-types) | N/A |
@@ -85,6 +86,7 @@ Finally, enable all of the rules that you would like to use.
8586
"jsdoc/require-param-name": 1,
8687
"jsdoc/require-param-type": 1,
8788
"jsdoc/require-returns": 1,
89+
"jsdoc/require-returns-check": 1,
8890
"jsdoc/require-returns-description": 1,
8991
"jsdoc/require-returns-type": 1,
9092
"jsdoc/valid-types": 1
@@ -259,5 +261,6 @@ Finally, the following rule pertains to inline disable directives:
259261
{"gitdown": "include", "file": "./rules/require-param.md"}
260262
{"gitdown": "include", "file": "./rules/require-returns-description.md"}
261263
{"gitdown": "include", "file": "./rules/require-returns-type.md"}
264+
{"gitdown": "include", "file": "./rules/require-returns-check.md"}
262265
{"gitdown": "include", "file": "./rules/require-returns.md"}
263266
{"gitdown": "include", "file": "./rules/valid-types.md"}
Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
### `require-returns-check`
2+
3+
Checks if the return expression exists in function body and in the comment.
4+
5+
|||
6+
|---|---|
7+
|Context|`ArrowFunctionExpression`, `FunctionDeclaration`, `FunctionExpression`|
8+
|Tags|`returns`|
9+
10+
<!-- assertions requireReturnsCheck -->

src/index.js

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,7 @@ import requireParam from './rules/requireParam';
1414
import requireParamDescription from './rules/requireParamDescription';
1515
import requireParamType from './rules/requireParamType';
1616
import requireReturns from './rules/requireReturns';
17+
import requireReturnsCheck from './rules/requireReturnsCheck';
1718
import requireReturnsDescription from './rules/requireReturnsDescription';
1819
import requireReturnsType from './rules/requireReturnsType';
1920
import validTypes from './rules/validTypes';
@@ -37,6 +38,7 @@ export default {
3738
'jsdoc/require-param-name': 'warn',
3839
'jsdoc/require-param-type': 'warn',
3940
'jsdoc/require-returns': 'warn',
41+
'jsdoc/require-returns-check': 'warn',
4042
'jsdoc/require-returns-description': 'warn',
4143
'jsdoc/require-returns-type': 'warn',
4244
'jsdoc/valid-types': 'warn'
@@ -59,6 +61,7 @@ export default {
5961
'require-param-name': requireParamName,
6062
'require-param-type': requireParamType,
6163
'require-returns': requireReturns,
64+
'require-returns-check': requireReturnsCheck,
6265
'require-returns-description': requireReturnsDescription,
6366
'require-returns-type': requireReturnsType,
6467
'valid-types': validTypes

src/rules/requireReturns.js

Lines changed: 0 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -17,8 +17,4 @@ export default iterateJsdoc(({
1717
if (JSON.stringify(jsdocTags) === '[]' && sourcecode.indexOf('return') >= 1) {
1818
report('Missing JSDoc @' + targetTagName + ' declaration.');
1919
}
20-
21-
if (JSON.stringify(jsdocTags) !== '[]' && sourcecode.indexOf('return') < 1) {
22-
report('Present JSDoc @' + targetTagName + ' declaration but not available return expression in function.');
23-
}
2420
});

src/rules/requireReturnsCheck.js

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
import _ from 'lodash';
2+
import iterateJsdoc from '../iterateJsdoc';
3+
4+
export default iterateJsdoc(({
5+
jsdoc,
6+
report,
7+
utils
8+
}) => {
9+
const targetTagName = utils.getPreferredTagName('returns');
10+
11+
const jsdocTags = _.filter(jsdoc.tags, {
12+
tag: targetTagName
13+
});
14+
15+
const sourcecode = utils.getFunctionSourceCode();
16+
17+
const voidReturn = jsdocTags.findIndex((vundef) => {
18+
return ['undefined', 'void'].indexOf(vundef.type) !== -1;
19+
}) === -1;
20+
21+
if (JSON.stringify(jsdocTags) !== '[]' && voidReturn && sourcecode.indexOf('return') < 1) {
22+
report('Present JSDoc @' + targetTagName + ' declaration but not available return expression in function.');
23+
}
24+
});
Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
export default {
2+
invalid: [
3+
{
4+
code: `
5+
/**
6+
* @returns
7+
*/
8+
function quux (foo) {
9+
10+
}
11+
`,
12+
errors: [
13+
{
14+
line: 2,
15+
message: 'Present JSDoc @returns declaration but not available return expression in function.'
16+
}
17+
]
18+
},
19+
{
20+
code: `
21+
/**
22+
* @return
23+
*/
24+
function quux (foo) {
25+
26+
}
27+
`,
28+
errors: [
29+
{
30+
line: 2,
31+
message: 'Present JSDoc @return declaration but not available return expression in function.'
32+
}
33+
],
34+
settings: {
35+
jsdoc: {
36+
tagNamePreference: {
37+
returns: 'return'
38+
}
39+
}
40+
}
41+
}
42+
],
43+
valid: [
44+
{
45+
code: `
46+
/**
47+
* @returns Foo.
48+
*/
49+
function quux () {
50+
51+
return foo;
52+
}
53+
`
54+
},
55+
{
56+
code: `
57+
/**
58+
* @returns {void} Foo.
59+
*/
60+
function quux () {
61+
62+
return foo;
63+
}
64+
`
65+
},
66+
{
67+
code: `
68+
/**
69+
* @returns {undefined} Foo.
70+
*/
71+
function quux () {
72+
73+
return foo;
74+
}
75+
`
76+
},
77+
{
78+
code: `
79+
/**
80+
*
81+
*/
82+
function quux () {
83+
}
84+
`
85+
}
86+
]
87+
};

test/rules/index.js

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,7 @@ _.forEach([
2222
'require-param-name',
2323
'require-param-type',
2424
'require-returns',
25+
'require-returns-check',
2526
'require-returns-description',
2627
'require-returns-type',
2728
'valid-types'

0 commit comments

Comments
 (0)