Useful JSDoc rules (JSCS and Others)

[simonepri]

I have read the issue discussing about the gaps between ESLint and JSCS but I haven't found nothing about the JSDoc rules.
I'm not using JSCS but they seems really useful.

ESLint now supports only these 2 rules:
https://eslint.org/docs/rules/require-jsdoc
https://eslint.org/docs/rules/valid-jsdoc

I've created a table to show some gaps between ESLint and JSCS.

JSCS Rule	ESLint Rule	External Rules	Status
checkAnnotations	valid-jsdoc Allows to set the prefer option, but does not report an error for non-existing annotations		⚠️
checkParamExistence	valid-jsdoc		✅
checkParamNames	valid-jsdoc		✅
requireParamTypes	valid-jsdoc		✅
checkRedundantParams			❌
checkReturnTypes			❌
checkRedundantReturns			❌
requireReturnTypes	valid-jsdoc		✅
checkTypes	valid-jsdoc Allows to set the preferType option, but does not have defaults		⚠️
checkRedundantAccess			❌
leadingUnderscoreAccess			❌
enforceExistence	require-jsdoc		✅
requireHyphenBeforeDescription		jsdoc/require-hyphen-before-param-description rule can be merged inside ESLint	⚠️
requireNewlineAfterDescription		jsdoc/newline-after-description rule can be merged inside ESLint	⚠️
disallowNewlineAfterDescription		jsdoc/newline-after-description rule can be merged inside ESLint	⚠️
requireDescriptionCompleteSentence		jsdoc/require-description-complete-sentence rule can be merged inside ESLint	⚠️
requireParamDescription	valid-jsdoc		✅
requireReturnDescription	valid-jsdoc		✅

[simonepri]

Possible defaults for preferType can be either:

"preferType": {
  "array": "Array",
  "Boolean": "boolean",
  "date": "Date",
  "Number": "number",
  "object": "Object",
  "regex": "RegExp",
  "String": "string"
}

or

"preferType": {
  "array": "Array",
  "boolean": "Boolean",
  "date": "Date",
  "number": "Number",
  "object": "Object",
  "regex": "RegExp",
  "string": "String"
}

[ilyavolodin]

@simonepri Thanks for the list. Have you looked at https://github.com/gajus/eslint-plugin-jsdoc ? Our goal with JSCS migration is not to have every single JSCS rule in ESLint, but to have a way of migrating out of JSCS. We specifically decided to drop some of the JSCS rules, because they were not generic enough (for example JSCS had a rule specifically for jQuery usage, ESLint doesn't allow framework specific rules).

[simonepri]

Hi @ilyavolodin!
Yes, actually the link you provided is the same you can find in the "External Rules" column if you click on one of them. The issue is more about the ESLint's support for JSDoc more than an issue about the JSCS migration. I just mention it because I found it has some nice rules for JSDoc.

Anyway, looking at the table, for example, are these three rules:
require-hyphen-before-param-description
require-description-complete-sentence
newline-after-description
not generic enough as you told?

There are lots of rules inside ESLint like:
brace-style, comma-style, multiline-comment-style, and so on
that deals with the "style" of a particular part of the code style and I believe that the JSDoc should have his spot too.

It may make sense for you to have a new rule inside ESLint called jsdoc-style that enable users to deal with formatting rules for the JSDocs?
If so, I'm welcome to contribute to do so. But I prefer to discuss it here, before actually doing a PR.

Thanks!

[ilyavolodin]

I personally have a mixed feelings about adding more JSDoc rules to the core. On one hand - they are useful, and I use them myself. On the other - JSDoc is not part of ECMAScript spec at all, and is a convention that's built on top of JS. More than that, there doesn't even seems to be an agreement on the convention itself. Doctrine that ESLint uses, doesn't follow the same rules as Google's JSDoc parser. From my perspective, I would like to see those rules added, but maybe to eslint-plug-jsdoc instead of the core.

[simonepri]

I perfectly understand your point of view.
Actually I agree with the fact that an external plugin may seem a great choice.

But question arises naturally.
If that's your feeling, why there are those rules about JSDoc inside ESLint?

It does not makes too sense for me to have some rules inside ESLint and others inside a plugin.

My thought (maybe wrong) when I first saw those rules was:
"Mhh...cool they have rules for JSDoc let's enable them!"
"Umh..they are pretty limited."
"Ok, let's search for a plugin."
"Mhh...this plugin has rules that overlaps with the rules inside the ESLint core...which should I use?"

[ilyavolodin]

Both of the JSDoc rules that we have in the core has been added a long time ago, before ESLint had support for plugins (as far as I remember, at least). There was even a conversation at some point about moving them out into eslint-plugin-jsdoc. Now that we have a policy of not removing existing rules from the core, we wouldn't be able to get rid of them at all (just deprecate them, which feels somewhat useless, when we don't provide a new rule to replace deprecated one). I'm not strongly oppose to adding new JSDoc rules to the core if deemed necessary, but let's see how the rest of the team feels.

[not-an-aardvark]

Thanks for your interest in improving ESLint. Unfortunately, it looks like this issue didn't get consensus from the team, so I'm closing it. We define consensus as having three 👍s from team members, as well as a team member willing to champion the proposal. This is a high bar by design -- we can't realistically accept and maintain every feature request in the long term, so we only accept feature requests which are useful enough that there is consensus among the team that they're worth adding.

Since ESLint is pluggable and can load custom rules at runtime, the lack of consensus among the ESLint team doesn't need to be a blocker for you using this in your project, if you'd find it useful. It just means that you would need to implement the rule yourself, rather than using a bundled rule that is packaged with ESLint.