require-param: Why require-param rule reports about function name?

[yeonjuan]

Maybe I’m wrong..but I think require param checks more(beyond it's responsibility)
Because I think, this rule should check only presence of @param.
but it also report about the function parameter name.

in require-param test

// first
/**
 * @param foo
 */
function quux (foo) {
}
// valid

// second
/**
 * @param
 */
function quux (foo) {
}
// invalid (Messege: Missing JSDoc @param "foo" declaration.)

I think the second test case is valid, because the presence of jsdocParamName( ex: foo) should be checked by 'require-param-name' rule

So,,, I think, It would be better if the report only check presence of param

ex) There are 3 parameters in function , but only 1 in jsdoc

Am I misunderstand about this rule's responsibility?
Thanks for reading, Please reply at your convenience.

[brettz9]

On the one hand, I would tend to agree that your proposed change makes sense as far as naming, especially as it would be consistent with how require-returns works.

However, I'm not sure how useful it is to report, or even fix to add empty @params, when one would presumably also always want a matching name.

Here is the current behavior of some of the related rules:

1. require-param: Iterates real function params to ensure a corresponding jsdoc param of the same name exists
2. require-param-name: Iterates jsdoc params and ensures they have a name (does not check whether they match actual function params)
3. check-param-names: Iterates jsdoc params and besides reporting jsdoc dupes, checks against actual function params to report if any real function params are missing or differently named (also does some object property param checking)

So currently, require-param is the only rule which ensures that if there are more arguments in the actual function, they will be reported as missing. While check-param-names could perhaps take that over, perhaps some users might only want the rule to check the jsdoc's they have added and not insist on documenting all real params.

I think the utility of require-param-name is that it doesn't impose requiring the param, but ensures that if a param tag exists, that it has a name. Perhaps some projects wouldn't want this rule to check the real function names because perhaps some projects might only document say the second param, and if they haven't gotten around to documenting the first or third params, they may only want to be bothered if there is a problem in those docs which they have added. So checking the real params index-by-index wouldn't work here, unless it were to only check that some param with that name existed and that any jsdoc params weren't in a different order.

[yeonjuan]

@brettz9 Ok. thanks for comments

[yeonjuan]

@brettz9 I have a question about #336.
Then, can i get more informations about how should the fixer work?
([Adding only tag] is enough?)

[brettz9]

@yeonjuan : I've updated #336 to indicate that I've suggested the fixer should also add the param name for any missing in the function signature.

I'll go ahead and close, but feel free to comment further.