search

jscs-dev / jscs-jsdoc

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

Force @return or @returns #167

Open gajus opened 8 years ago

gajus commented 8 years ago

Have a rule that forces user to use either @return tag or @returns.

qfox commented 8 years ago

Does checkAnnotations: { extra: { "returns": null } } to deny @returns would be fine?

qfox commented 8 years ago

I should say that currently you allowing both when you using closure or jsdoc3 tag set: https://github.com/jscs-dev/jscs-jsdoc/blob/1d6e20f588564fa61f8794b9d1301702abdfa4be/lib/tags/jsdoc3.json#L64-L65

But I'm not sure that this is right. Closure compiler uses @return: https://developers.google.com/closure/compiler/docs/js-for-compiler#tag-return — Guess we can safely remove @returns from it. JSDoc3 http://usejsdoc.org/tags-returns.html — supports both.

Ref: https://github.com/jscs-dev/jscs-jsdoc/issues/76

gajus commented 8 years ago

Semantically, @return does not make sense. You don't give a command to the function. You describe what it does. It returns a value.

On Oct 2, 2015, at 22:07, Alexej Yaroshevich notifications@github.com wrote:

I should say that currently you allowing both when you using closure or jsdoc3 tag set: https://github.com/jscs-dev/jscs-jsdoc/blob/1d6e20f588564fa61f8794b9d1301702abdfa4be/lib/tags/jsdoc3.json#L64-L65

But I'm not sure that this is right. Closure compiler uses @return: https://developers.google.com/closure/compiler/docs/js-for-compiler#tag-return — Guess we can safely remove @returns from it. JSDoc3 http://usejsdoc.org/tags-returns.html — supports both.

Ref: #76

— Reply to this email directly or view it on GitHub.

gajus commented 8 years ago

Has any decision been taken regarding this since?

qfox commented 8 years ago

I'd suggest to wait "multi-sets" (when you'll be able to use jsdoc3 with googleclosure addon) and then cleanup tag sets (e.g. remove returns from googleclosure set).

I think we shouldn't remove @return from jsdoc3 according to docs: http://usejsdoc.org/tags-returns.html But there is no @returns in googleclosure: https://developers.google.com/closure/compiler/docs/js-for-compiler ;-)

What you think?

gajus commented 8 years ago

A rather general suggestion is to remove https://github.com/jscs-dev/jscs-jsdoc#checkannotations entirely. This rule is too broad. Instead, allow granular control (allowed, not allowed), case sensitive, control of all the supported tags.