Request new rule: 'require-hyphen-before-returns-description'

[dperolio]

Motivation

A new rule called 'require-hyphen-before-returns-description'

Current behavior

Doesn't currently exist, but it could be added as a new rule or maybe as an enhancer to 'require-hyphen-before-param-description'

Desired behavior

'require-hyphen-before-returns-description' would act similar to 'require-hyphen-before-param-description' in that it checks if there is a hyphen before the @returns description.

[brettz9]

While I'm not personally opposed to this, I think the hyphen's use with @param is to offset things visually more between the param name and description.

/**
 * @param {optionalType} someName - The description
 */

vs.

/**
 * @param {optionalType} someName The description
 */

With @returns, there is only the @returns tag, and an optional curly-bracket-enclosed type, so I think it is always going to be visually distinct without the hyphen:

/**
 * @returns {optionalType} The description
 */

/**
 * @returns The description
 */

[dperolio]

Yeah, I understand the logic; I just find including a hyphen before the @returns description, when also including a hyphen before the @params description looks much better / more readable to me personally. I'm not saying it should be enabled by default or anything, but it would be nice to have as an option.

[thernstig]

I'd say the opposite should be checked i.e. that it does not contain a dash. IntelliSense, in at least VS Code which is one of the mostly used editors, renders the dash which makes it look "wrong". Like @brettz9 points out, the dash is there as a delimiter for identifier names.

Example of IntelliSense 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]

Closing in favor of #628 as I think the default does make more sense to restrict hyphens. However, I think as with require-hyphen-before-param-description, we can have a non-default option to do the opposite (i.e., to require hyphens with @returns) as requested in this current issue. So, feel free to subscribe there @dperolio .

@thernstig : Though it is indeed helpful to know how tools interact, one tool making it look awkward doesn't of course mean that should affect all projects (which may use a number of other tools or no additional tools at all), especially if jsdoc doesn't forbid it.