diff --git a/.README/rules/check-line-alignment.md b/.README/rules/check-line-alignment.md index 87a807e8a..657e4a8d6 100644 --- a/.README/rules/check-line-alignment.md +++ b/.README/rules/check-line-alignment.md @@ -30,6 +30,7 @@ An object with any of the following keys set to an integer. Affects spacing: - `postTag` - after the tag (e.g., `* @param `) - `postType` - after the type (e.g., `* @param {someType} `) - `postName` - after the name (e.g., `* @param {someType} name `) +- `postHyphens` - after any hyphens in the description (e.g., `* @param {someType} name - A description`) If a spacing is not defined, it defaults to one. diff --git a/README.md b/README.md index 77d727863..14ec55497 100644 --- a/README.md +++ b/README.md @@ -2047,6 +2047,7 @@ An object with any of the following keys set to an integer. Affects spacing: - `postTag` - after the tag (e.g., `* @param `) - `postType` - after the type (e.g., `* @param {someType} `) - `postName` - after the name (e.g., `* @param {someType} name `) +- `postHyphens` - after any hyphens in the description (e.g., `* @param {someType} name - A description`) If a spacing is not defined, it defaults to one. @@ -2438,6 +2439,66 @@ const fn = ( lorem, sit ) => {} const fn = ( lorem, sit ) => {} // "jsdoc/check-line-alignment": ["error"|"warn", "always"] // Message: Expected JSDoc block lines to be aligned. + +/** + * Function description. + * + * @param {string} lorem - Description. + * @param {int} sit - Description multi words. + */ +const fn = ( lorem, sit ) => {} +// "jsdoc/check-line-alignment": ["error"|"warn", "never"] +// Message: Expected JSDoc block lines to not be aligned. + +/** + * Function description. + * + * @param {string} lorem - Description. + * @param {int} sit - Description multi words. + */ +const fn = ( lorem, sit ) => {} +// "jsdoc/check-line-alignment": ["error"|"warn", "never",{"customSpacings":{"postHyphen":2}}] +// Message: Expected JSDoc block lines to not be aligned. + +/** + * Function description. + * + * @param {string} lorem - Description. + * @param {int} sit - Description multi words. + */ +const fn = ( lorem, sit ) => {} +// "jsdoc/check-line-alignment": ["error"|"warn", "never",{"customSpacings":{"postHyphen":2}}] +// Message: Expected JSDoc block lines to not be aligned. + +/** + * Function description. + * + * @param {string} lorem - Description. + * @param {int} sit - Description multi words. + */ +const fn = ( lorem, sit ) => {} +// "jsdoc/check-line-alignment": ["error"|"warn", "always",{"customSpacings":{"postHyphen":2}}] +// Message: Expected JSDoc block lines to be aligned. + +/** + * Function description. + * + * @param {string} lorem - Description. + * @param {int} sit - Description multi words. + */ +const fn = ( lorem, sit ) => {} +// "jsdoc/check-line-alignment": ["error"|"warn", "always",{"customSpacings":{"postHyphen":2}}] +// Message: Expected JSDoc block lines to be aligned. + +/** + * Function description. + * + * @param {string} lorem - Description. + * @param {int} sit - Description multi words. + */ +const fn = ( lorem, sit ) => {} +// "jsdoc/check-line-alignment": ["error"|"warn", "never",{"customSpacings":{"postHyphen":2}}] +// Message: Expected JSDoc block lines to not be aligned. ```` The following patterns are not considered problems: diff --git a/src/alignTransform.js b/src/alignTransform.js index 7a4c56d65..dbf83e26e 100644 --- a/src/alignTransform.js +++ b/src/alignTransform.js @@ -233,6 +233,12 @@ const alignTransform = ({ }; } + const postHyphenSpacing = customSpacings?.postHyphen ?? 1; + const hyphenSpacing = /^\s*-\s*/u; + tokens.description = tokens.description.replace( + hyphenSpacing, '-' + ''.padStart(postHyphenSpacing, ' '), + ); + // Not align. if (!shouldAlign(tags, index, source)) { return { diff --git a/src/rules/checkLineAlignment.js b/src/rules/checkLineAlignment.js index 7dca839ea..fb20a0632 100644 --- a/src/rules/checkLineAlignment.js +++ b/src/rules/checkLineAlignment.js @@ -64,6 +64,13 @@ const checkNotAlignedPerTag = (utils, tag, customSpacings) => { }); }; + const postHyphenSpacing = customSpacings?.postHyphen ?? 1; + const exactHyphenSpacing = new RegExp(`^\\s*-\\s{${postHyphenSpacing},${postHyphenSpacing}}(?!\\s)`, 'u'); + const hasNoHyphen = !(/^\s*-/u).test(tokens.description); + const hasExactHyphenSpacing = exactHyphenSpacing.test( + tokens.description, + ); + // If checking alignment on multiple lines, need to check other `source` // items // Go through `post*` spacing properties and exit to indicate problem if @@ -82,7 +89,7 @@ const checkNotAlignedPerTag = (utils, tag, customSpacings) => { // 2. There is a (single) space, no immediate content, and yet another // space is found subsequently (not separated by intervening content) spacerPropVal && !contentPropVal && followedBySpace(idx); - }); + }) && (hasNoHyphen || hasExactHyphenSpacing); if (ok) { return; } @@ -108,6 +115,13 @@ const checkNotAlignedPerTag = (utils, tag, customSpacings) => { } } + if (!hasExactHyphenSpacing) { + const hyphenSpacing = /^\s*-\s*/u; + tokens.description = tokens.description.replace( + hyphenSpacing, '-' + ''.padStart(postHyphenSpacing, ' '), + ); + } + utils.setTag(tag, tokens); }; @@ -212,6 +226,9 @@ export default iterateJsdoc(({ postDelimiter: { type: 'integer', }, + postHyphen: { + type: 'integer', + }, postName: { type: 'integer', }, diff --git a/test/rules/assertions/checkLineAlignment.js b/test/rules/assertions/checkLineAlignment.js index e070b9199..83c83b182 100644 --- a/test/rules/assertions/checkLineAlignment.js +++ b/test/rules/assertions/checkLineAlignment.js @@ -1157,6 +1157,208 @@ export default { const fn = ( lorem, sit ) => {} `, }, + { + code: ` + /** + * Function description. + * + * @param {string} lorem - Description. + * @param {int} sit - Description multi words. + */ + const fn = ( lorem, sit ) => {} + `, + errors: [ + { + line: 6, + message: 'Expected JSDoc block lines to not be aligned.', + type: 'Block', + }, + ], + options: [ + 'never', + ], + output: ` + /** + * Function description. + * + * @param {string} lorem - Description. + * @param {int} sit - Description multi words. + */ + const fn = ( lorem, sit ) => {} + `, + }, + { + code: ` + /** + * Function description. + * + * @param {string} lorem - Description. + * @param {int} sit - Description multi words. + */ + const fn = ( lorem, sit ) => {} + `, + errors: [ + { + line: 6, + message: 'Expected JSDoc block lines to not be aligned.', + type: 'Block', + }, + ], + options: [ + 'never', + { + customSpacings: { + postHyphen: 2, + }, + }, + ], + output: ` + /** + * Function description. + * + * @param {string} lorem - Description. + * @param {int} sit - Description multi words. + */ + const fn = ( lorem, sit ) => {} + `, + }, + { + code: ` + /** + * Function description. + * + * @param {string} lorem - Description. + * @param {int} sit - Description multi words. + */ + const fn = ( lorem, sit ) => {} + `, + errors: [ + { + line: 5, + message: 'Expected JSDoc block lines to not be aligned.', + type: 'Block', + }, + ], + options: [ + 'never', + { + customSpacings: { + postHyphen: 2, + }, + }, + ], + output: ` + /** + * Function description. + * + * @param {string} lorem - Description. + * @param {int} sit - Description multi words. + */ + const fn = ( lorem, sit ) => {} + `, + }, + { + code: ` + /** + * Function description. + * + * @param {string} lorem - Description. + * @param {int} sit - Description multi words. + */ + const fn = ( lorem, sit ) => {} + `, + errors: [ + { + line: 2, + message: 'Expected JSDoc block lines to be aligned.', + type: 'Block', + }, + ], + options: [ + 'always', { + customSpacings: { + postHyphen: 2, + }, + }, + ], + output: ` + /** + * Function description. + * + * @param {string} lorem - Description. + * @param {int} sit - Description multi words. + */ + const fn = ( lorem, sit ) => {} + `, + }, + { + code: ` + /** + * Function description. + * + * @param {string} lorem - Description. + * @param {int} sit - Description multi words. + */ + const fn = ( lorem, sit ) => {} + `, + errors: [ + { + line: 2, + message: 'Expected JSDoc block lines to be aligned.', + type: 'Block', + }, + ], + options: [ + 'always', { + customSpacings: { + postHyphen: 2, + }, + }, + ], + output: ` + /** + * Function description. + * + * @param {string} lorem - Description. + * @param {int} sit - Description multi words. + */ + const fn = ( lorem, sit ) => {} + `, + }, + { + code: ` + /** + * Function description. + * + * @param {string} lorem - Description. + * @param {int} sit - Description multi words. + */ + const fn = ( lorem, sit ) => {} + `, + errors: [ + { + line: 5, + message: 'Expected JSDoc block lines to not be aligned.', + type: 'Block', + }, + ], + options: [ + 'never', { + customSpacings: { + postHyphen: 2, + }, + }, + ], + output: ` + /** + * Function description. + * + * @param {string} lorem - Description. + * @param {int} sit - Description multi words. + */ + const fn = ( lorem, sit ) => {} + `, + }, ], valid: [ {