Skip to content

Commit ee16a2c

Browse files
qfoxqfox
committed
Merge pull request #73 from zxqfox/feature/check-param-names-dotted-check
checkParamNames: also check dotted names consistency
2 parents fcae367 + aafb312 commit ee16a2c

File tree

2 files changed

+100
-25
lines changed

2 files changed

+100
-25
lines changed

‎lib/rules/validate-jsdoc/check-param-names.js

Lines changed: 23 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,7 @@ function validateCheckParamNames(node, err) {
2727
});
2828
var outOfOrder = {};
2929
var skipped = 0;
30+
var lastRootParamTag;
3031

3132
node.jsdoc.iterateByType(['param', 'arg', 'argument'],
3233
/**
@@ -37,17 +38,29 @@ function validateCheckParamNames(node, err) {
3738
function(tag, i) {
3839
// checking validity
3940
if (!tag.name) {
40-
return err('missing param name', tag.loc);
41+
return err('Missing param name', tag.loc);
4142
}
4243

43-
var param = node.params[i - skipped];
44-
if (!param) {
45-
// skip if no param
44+
var dotPosition = tag.name.value.indexOf('.');
45+
if (dotPosition !== -1) {
46+
var dottedRootParam = tag.name.value.substr(0, dotPosition);
47+
if (dotPosition === 0 || !(dottedRootParam = tag.name.value.substr(0, dotPosition))) {
48+
err('Invalid param name', tag.name.loc);
49+
} else if (!lastRootParamTag) {
50+
err('Inconsistent param found', tag.name.loc);
51+
} else if (lastRootParamTag.name.value !== dottedRootParam) {
52+
err('Expected `' + lastRootParamTag.name.value + '` but got `' + dottedRootParam + '`',
53+
tag.name.loc);
54+
}
55+
skipped++;
4656
return;
4757
}
4858

49-
if (tag.name.value.indexOf('.') !== -1) {
50-
skipped++;
59+
lastRootParamTag = tag;
60+
61+
var param = node.params[i - skipped];
62+
if (!param) {
63+
// skip if no param
5164
return;
5265
}
5366

@@ -56,15 +69,15 @@ function validateCheckParamNames(node, err) {
5669
if (tag.name.value !== param.name && !outOfOrder[tag.name.value]) {
5770
if (paramsByName[tag.name.value] && paramTagsByName[param.name]) {
5871
outOfOrder[tag.name.value] = outOfOrder[param.name] = true;
59-
msg = 'parameters ' + tag.name.value + ' and ' + param.name + ' are out of order';
72+
msg = 'Parameters ' + tag.name.value + ' and ' + param.name + ' are out of order';
6073
} else if (paramsByName[tag.name.value]) {
6174
outOfOrder[tag.name.value] = true;
62-
msg = 'parameter ' + tag.name.value + ' is out of order';
75+
msg = 'Parameter ' + tag.name.value + ' is out of order';
6376
} else {
64-
msg = 'expected ' + param.name + ' but got ' + tag.name.value;
77+
msg = 'Expected ' + param.name + ' but got ' + tag.name.value;
6578
}
6679

67-
return err(msg, tag.name.loc || node.jsdoc.loc.start);
80+
return err(msg, tag.name.loc);
6881
}
6982
});
7083
}

‎test/lib/rules/validate-jsdoc/check-param-names.js

Lines changed: 77 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -146,7 +146,7 @@ describe('lib/rules/validate-jsdoc/check-param-names', function() {
146146
},
147147
errors: [
148148
{
149-
message: 'parameters xxx and yyy are out of order',
149+
message: 'Parameters xxx and yyy are out of order',
150150
column: 10,
151151
line: 2,
152152
rule: "jsDoc",
@@ -168,14 +168,14 @@ describe('lib/rules/validate-jsdoc/check-param-names', function() {
168168
},
169169
errors: [
170170
{
171-
message: 'parameters xxx and zzz are out of order',
171+
message: 'Parameters xxx and zzz are out of order',
172172
column: 14,
173173
line: 3,
174174
rule: "jsDoc",
175175
filename: "input"
176176
},
177177
{
178-
message: 'parameters yyy and xxx are out of order',
178+
message: 'Parameters yyy and xxx are out of order',
179179
column: 14,
180180
line: 4,
181181
rule: "jsDoc",
@@ -195,8 +195,8 @@ describe('lib/rules/validate-jsdoc/check-param-names', function() {
195195
};
196196
},
197197
errors: [
198-
{message: 'parameter xxx is out of order', column: 14, line: 3, rule: "jsDoc", filename: "input"},
199-
{message: 'expected xxx but got yyy', column: 14, line: 4, rule: "jsDoc", filename: "input"}
198+
{message: 'Parameter xxx is out of order', column: 14, line: 3, rule: "jsDoc", filename: "input"},
199+
{message: 'Expected xxx but got yyy', column: 14, line: 4, rule: "jsDoc", filename: "input"}
200200
]
201201
}, {
202202
it: 'should report out of order and expected v2',
@@ -211,8 +211,8 @@ describe('lib/rules/validate-jsdoc/check-param-names', function() {
211211
};
212212
},
213213
errors: [
214-
{message: 'expected yyy but got xxx', column: 14, line: 3, rule: "jsDoc", filename: "input"},
215-
{message: 'parameter yyy is out of order', column: 14, line: 4, rule: "jsDoc", filename: "input"}
214+
{message: 'Expected yyy but got xxx', column: 14, line: 3, rule: "jsDoc", filename: "input"},
215+
{message: 'Parameter yyy is out of order', column: 14, line: 4, rule: "jsDoc", filename: "input"}
216216
]
217217
}, {
218218
it: 'should not report out of order but expected',
@@ -227,10 +227,27 @@ describe('lib/rules/validate-jsdoc/check-param-names', function() {
227227
};
228228
},
229229
errors: [
230-
{message: 'expected zzz but got xxx', column: 14, line: 3, rule: "jsDoc", filename: "input"}
230+
{message: 'Expected zzz but got xxx', column: 14, line: 3, rule: "jsDoc", filename: "input"}
231231
]
232-
233232
}, {
233+
it: 'should not report wrong order',
234+
code: function() {
235+
/**
236+
* @param {string|Array.<string>} types
237+
* @param {function(this: DocComment, DocTag): DocComment} fn
238+
*/
239+
function iterateByTypes(types, fn) {}
240+
}
241+
}
242+
// jscs:enable
243+
/* jshint ignore:end */
244+
]);
245+
246+
// ticked and chevroned param names
247+
checker.cases([
248+
/* jshint ignore:start */
249+
/* jscs:disable */
250+
{
234251
it: 'should not report simple ticked param',
235252
code: function() {
236253
/**
@@ -256,7 +273,16 @@ describe('lib/rules/validate-jsdoc/check-param-names', function() {
256273
*/
257274
function methodThree(required, optional) {}
258275
}
259-
}, {
276+
}
277+
// jscs:enable
278+
/* jshint ignore:end */
279+
]);
280+
281+
// dotted param names
282+
checker.cases([
283+
/* jshint ignore:start */
284+
/* jscs:disable */
285+
{
260286
it: 'should not report dotted param names',
261287
code: function() {
262288
/**
@@ -270,14 +296,50 @@ describe('lib/rules/validate-jsdoc/check-param-names', function() {
270296
function yeah(mod, props, staticProps) {}
271297
}
272298
}, {
273-
it: 'should not report wrong order',
299+
it: 'should report inconsistency of separated dotted params',
274300
code: function() {
275301
/**
276-
* @param {string|Array.<string>} types
277-
* @param {function(this: DocComment, DocTag): DocComment} fn
302+
* @param {Object} options
303+
* @param {String} definetelyNotOptions.cdir
304+
* @param {Boolean} otherOptions.noLog
278305
*/
279-
function iterateByTypes(types, fn) {}
280-
}
306+
module.exports.createMiddleware = function(options) { /* ... */ };
307+
},
308+
errors: [
309+
{
310+
"column": 19,
311+
"filename": "input",
312+
"line": 3,
313+
"message": "Expected `options` but got `definetelyNotOptions`",
314+
"rule": "jsDoc"
315+
},
316+
{
317+
"column": 20,
318+
"filename": "input",
319+
"line": 4,
320+
"message": "Expected `options` but got `otherOptions`",
321+
"rule": "jsDoc"
322+
}
323+
]
324+
}, {
325+
it: 'should report unjoined params',
326+
code: function() {
327+
/**
328+
* @param {String} options.cdir
329+
*/
330+
module.exports.createMiddleware = function() { /* ... */ };
331+
},
332+
errors: { "message": "Inconsistent param found" }
333+
}, {
334+
it: 'should not report params',
335+
code: function() {
336+
/**
337+
* @param {Object} options
338+
* @param {String} options.cdir
339+
*/
340+
module.exports.createMiddleware = function() { /* ... */ };
341+
},
342+
errors: []
281343
}
282344
/* jscs: enable */
283345
/* jshint ignore:end */

0 commit comments

Comments
 (0)