Repository navigation
[RFC]: add JSDoc lint rule to enforce whitespace before and after dash #13662
Description
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:
- enforce number of whitespace characters before dash
- enforce number of whitespace characters after dash
- 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
Activity
ujjwalv01 commentedon Jul 26, 2026
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, andjsdoc-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 commentedon Jul 26, 2026
@ujjwalv01 Probably worthwhile seeing what is currently done for other rules. E.g.,
stdlib/etc/eslint/rules/style.js
Line 278 in b06219c
Instead of
dashwe should follow JSDoc documentation and usehyphen(ref: https://jsdoc.app/tags-param). So, in short, a single rulePlaced in https://github.com/stdlib-js/stdlib/tree/develop/lib/node_modules/%40stdlib/_tools/eslint/rules.
ujjwalv01 commentedon Jul 26, 2026
Thanks @kgryte for the clarification and the references! Makes total sense , following official JSDoc terminology and structuring it like
comma-spacingwith{ 'before': true, 'after': true }options is much cleaner.I am starting work on
jsdoc-param-hyphen-spacinginlib/node_modules/@stdlib/_tools/eslint/rules/now and will open a PR once the rule and test suites are ready!