[RFC]: add JSDoc lint rule to enforce whitespace before and after dash

[kgryte]

Currently, we do not catch when the dash separating a parameter name from a parameter description is bordered by more than one whitespace character. We should enforce only one whitespace character on either side of the dash. So the following is good:

/**
* ...
*
* @param {number} x - input value
* @returns {number} output value
*/

and the following should be disallowed

/**
*
* @param {number} x    -     input value
* @returns {number} output value
*/

In principle, we could have up to three different lint rules:

1. enforce number of whitespace characters before dash
2. enforce number of whitespace characters after dash
3. enforce a specific character (e.g., -) to be used to separate a parameter name from a description

We could also have another lint rule for enforcing that a dash should not separate a @returns annotation from its description. This should likely be its own RFC.

Notes

Ref: #13654

[ujjwalv01]

Hi @kgryte , I would like to work on implementing this JSDoc lint rule for enforcing whitespace around parameter dashes in @stdlib/_tools/eslint/rules.

Before submitting a PR, I had a quick architectural question regarding your note on rule granularity:
Would you prefer this implemented as three separate rules (e.g., jsdoc-param-before-dash-spacing, jsdoc-param-after-dash-spacing, and jsdoc-param-dash-marker), or as a single combined rule (e.g., jsdoc-param-dash-spacing) that checks the separator and enforces single spacing on both sides?

Happy to start drafting the AST/regex validators as soon as you let me know which structure you prefer.

[kgryte]

@ujjwalv01 Probably worthwhile seeing what is currently done for other rules. E.g.,

stdlib/etc/eslint/rules/style.js

Line 278 in b06219c

rules[ 'comma-spacing' ] = [ 'error', {

.

Instead of dash we should follow JSDoc documentation and use hyphen (ref: https://jsdoc.app/tags-param). So, in short, a single rule

jsdoc-param-hyphen-spacing

Placed in https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/_tools/eslint/rules.

[ujjwalv01]

Thanks @kgryte for the clarification and the references! Makes total sense , following official JSDoc terminology and structuring it like comma-spacing with { 'before': true, 'after': true } options is much cleaner.

I am starting work on jsdoc-param-hyphen-spacing in lib/node_modules/@stdlib/_tools/eslint/rules/ now and will open a PR once the rule and test suites are ready!