Requesting new rule: no-hyphen-before-returns-description

[thernstig]

Motivation

A new rule called no-hyphen-before-returns-description

Current behavior

Doesn't exist currently.

Desired behavior

It would warn and hopefully auto-fix if there is a hyphen in the returns description.

Alternatives considered

#623 is requesting the opposite, that a hyphen should exist before the description in a returns statement. However, IntelliSense, in at least VS Code which is one of the mostly used editors, renders the dash which makes it look "wrong". The dash is there in e.g. @param as a delimiter for identifier names, but JSDoc does not show it as part of @returns, see https://jsdoc.app/tags-returns.html.

Example of VS Code IntelliSense (code completion) for the following function:

/**
 * Some test function.
 *
 * @param {boolean} cool - If this is cool or not
 *
 * @returns {string} Current coolness.
 */
function coolness(cool) {
  return cool ? 'Very cool' : 'Not cool at all';
}

With dash

Without dash

[brettz9]

I agree with this, but as per #623, let's implement with a non-default option which requires hyphens. Besides jsdoc not being against such an option, the support should also be trivial to add on top.

[thernstig]

@brettz9 Do you mean the option should be hyphens, even though JSDoc does not use it in any examples? I understand JSDoc does not forbid it, but it seems unconventional to use a hyphen for @returns.

[brettz9]

Yes, I mean that in addition to a "never" option (which should be the default), there should be an "always" option which requires hyphens with @returns. We have a number of rules like this, and we allow people to customize things the way they wish. Since it is trivial to allow, and there is a desire for it, I see no good reason not to support it, albeit as the non-default. JSDoc does not rigidly define its own styling rules, and in this case, there is nothing prohibiting such a usage. (Even where JSDoc defines some parsing expectations, like how tag names are non-whitespace, they are very lenient.)

[brettz9]

I had forgotten that this support is already available by using the require-hyphen-before-param-description rule with the tags option.

So as per the example in the docs, you could set:

'require-hyphen-before-param-description': ['error', 'always', {
          tags: {
            returns: 'never',
          },
        }
]

In place of returns, you could use * in place of returns if you wanted all non-@param tags (if not used elsewhere within the tags option object) to prevent hyphens.

By leveraging this rule, one does currently require have to commit to @param always having or never having hyphens. Feel free to file a separate issue if you need it to be non-committal for @param.

Closing, though feel free to comment further as needed.