search

jscs-dev / jscs-jsdoc

JsDoc validation rules for jscs
MIT License
99 stars 35 forks source link

New rule: Check param existence #138

Closed jdlrobson closed 9 years ago

jdlrobson commented 9 years ago

This rule reports errors when a parameter is undocumented or missing an @inheritdoc statement

If @inheritdoc is present it assumes that the function inherited from is documented correctly. This seems useful for ensuring a developer has documented everything they should have in a function signature.

This patch is not quite mergeable - I need to write some tests but would you welcome a patch for this?

jdlrobson commented 9 years ago

(As stated I need to work on this a bit more, but I figured I'd send a pull request to identify whether any other teams would benefit from this before investing the effort :-))

We've been using it for some time and it has proved handy.

qfox commented 9 years ago

Thanks for contribution. Would be nice to have this in checker. ;-)

:+1: from me

jdlrobson commented 9 years ago

Does checkParamExistence make sense as a rule name or is there a better name I should use? I will work to get this in mergeable form :)

qfox commented 9 years ago

There is a huge conflicting rule checkParamNames. Can you take a look at it? Looks like it should skip checking if there are @inheritdoc or some other tags you use here.

jdlrobson commented 9 years ago

Should I merge checkParamNames with checkParamExistence or is it better to have them separate? I can't think of a reason where you wouldn't want to check both..

qfox commented 9 years ago

Not sure. checkParamNames already weighs a lot. I'd go to ignore this logic somehow in checkParamNames (just to prevent false reports), and left checkParamExistence as is. But you're right so guess better to merge them into one rule.

piotr-cz commented 9 years ago

What is the reason of not supporting @inheritdoc in the jsdoc3 annotation type, when it's available in jsduck5 annotation type?

qfox commented 9 years ago

@piotr-cz http://usejsdoc.org/tags-inheritdoc.html — just need to add. ;-) #142

jdlrobson commented 9 years ago

Apologies this is taking me so long. I tried recently but am a bit rusty in this repository and couldn't get npm test to run in my local dev environment and didn't have the time to debug. I will try again as soon as I have a moment.

qfox commented 9 years ago

Personally I'll try to find some time next weekend to merge all PRs, but there is another strange issue with bundled to jscs version. I'm not sure how much time it takes.

But if you have some troubles with npm test — just tell me, I'm almost always ready to help ;-) Btw, there is a chat at gitter.im: https://gitter.im/jscs-dev/node-jscs

jdlrobson commented 9 years ago

okay pushed. I wasn't able to see the issues with checkParamNames option but these rules might want to be merged in future. I've given you loads of test cases so hopefully that will give you confidence in my patch! It's good to be contributing again! :)