-
-
Notifications
You must be signed in to change notification settings - Fork 153
/
requireReturns.js
106 lines (95 loc) · 2.88 KB
/
requireReturns.js
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
import iterateJsdoc from '../iterateJsdoc';
import warnRemovedSettings from '../warnRemovedSettings';
/**
* We can skip checking for a return value, in case the documentation is inherited
* or the method is either a constructor or an abstract method.
*
* In either of these cases the return value is optional or not defined.
*
* @param {*} utils
* a reference to the utils which are used to probe if a tag is present or not.
* @returns {boolean}
* true in case deep checking can be skipped; otherwise false.
*/
const canSkip = (utils) => {
return utils.hasATag([
// inheritdoc implies that all documentation is inherited
// see https://jsdoc.app/tags-inheritdoc.html
//
// Abstract methods are by definition incomplete,
// so it is not an error if it declares a return value but does not implement it.
'abstract',
'virtual',
// Constructors do not have a return value by definition (https://jsdoc.app/tags-class.html)
// So we can bail out here, too.
'class',
'constructor',
// Return type is specified by type in @type
'type',
// This seems to imply a class as well
'interface'
]) ||
utils.isConstructor() ||
// Though ESLint avoided getters: https://github.com/eslint/eslint/blob/master/lib/rules/valid-jsdoc.js#L435
// ... getters seem that they should, unlike setters, always return:
utils.isSetter() ||
utils.avoidDocs();
};
export default iterateJsdoc(({
report,
utils,
context
}) => {
warnRemovedSettings(context, 'require-returns');
// A preflight check. We do not need to run a deep check
// in case the @returns comment is optional or undefined.
if (canSkip(utils)) {
return;
}
const {
forceRequireReturn = false,
forceReturnsWithAsync = false
} = context.options[0] || {};
const tagName = utils.getPreferredTagName({tagName: 'returns'});
if (!tagName) {
return;
}
const tags = utils.getTags(tagName);
if (tags.length > 1) {
report(`Found more than one @${tagName} declaration.`);
}
// In case the code returns something, we expect a return value in JSDoc.
const [tag] = tags;
const missingReturnTag = typeof tag === 'undefined' || tag === null;
if (missingReturnTag &&
((utils.isAsync() && !utils.hasReturnValue(true) ? forceReturnsWithAsync : utils.hasReturnValue()) || forceRequireReturn)
) {
report(`Missing JSDoc @${tagName} declaration.`);
}
}, {
meta: {
schema: [
{
additionalProperties: false,
properties: {
exemptedBy: {
items: {
type: 'string'
},
type: 'array'
},
forceRequireReturn: {
default: false,
type: 'boolean'
},
forceReturnsWithAsync: {
default: false,
type: 'boolean'
}
},
type: 'object'
}
],
type: 'suggestion'
}
});