From ddf041a5adba15adced8c789937b4104b8157481 Mon Sep 17 00:00:00 2001 From: Renatho De Carli Rosa Date: Sun, 16 May 2021 19:11:45 -0300 Subject: [PATCH 1/8] Add comment to identify origin of the code --- src/alignTransform.js | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/src/alignTransform.js b/src/alignTransform.js index 8caf2e033..e371e3f1c 100644 --- a/src/alignTransform.js +++ b/src/alignTransform.js @@ -1,3 +1,9 @@ +/** + * Transform based on https://github.com/syavorsky/comment-parser/blob/master/src/transforms/align.ts + * + * It contains some customizations to align based on the tags, and some custom options. + */ + import { Markers, } from 'comment-parser/lib/primitives'; From ec9619cc48504bd463495076d34f723bf24e05c8 Mon Sep 17 00:00:00 2001 From: Renatho De Carli Rosa Date: Sun, 16 May 2021 19:12:07 -0300 Subject: [PATCH 2/8] Add custom spacings option --- src/alignTransform.js | 22 ++++++++--- src/rules/checkLineAlignment.js | 15 +++++++- test/rules/assertions/checkLineAlignment.js | 41 +++++++++++++++++++++ 3 files changed, 72 insertions(+), 6 deletions(-) diff --git a/src/alignTransform.js b/src/alignTransform.js index e371e3f1c..85962cdce 100644 --- a/src/alignTransform.js +++ b/src/alignTransform.js @@ -64,7 +64,12 @@ const space = (len) => { return ''.padStart(len, ' '); }; -const alignTransform = (tags, indent, preserveMainDescriptionPostDelimiter) => { +const alignTransform = ({ + customSpacings, + tags, + indent, + preserveMainDescriptionPostDelimiter, +}) => { let intoTags = false; let width; @@ -96,17 +101,24 @@ const alignTransform = (tags, indent, preserveMainDescriptionPostDelimiter) => { } } - tokens.postDelimiter = nothingAfter.delim ? '' : ' '; + const spacings = { + postDelimiter: customSpacings?.postDelimiter || 1, + postName: customSpacings?.postName || 1, + postTag: customSpacings?.postTag || 1, + postType: customSpacings?.postType || 1, + }; + + tokens.postDelimiter = nothingAfter.delim ? '' : space(spacings.postDelimiter); if (!nothingAfter.tag) { - tokens.postTag = space(width.tag - tokens.tag.length + 1); + tokens.postTag = space(width.tag - tokens.tag.length + spacings.postTag); } if (!nothingAfter.type) { - tokens.postType = space(width.type - tokens.type.length + 1); + tokens.postType = space(width.type - tokens.type.length + spacings.postType); } if (!nothingAfter.name) { // If post name is empty for all lines (name width 0), don't add post name spacing. - tokens.postName = width.name === 0 ? '' : space(width.name - tokens.name.length + 1); + tokens.postName = width.name === 0 ? '' : space(width.name - tokens.name.length + spacings.postName); } return tokens; diff --git a/src/rules/checkLineAlignment.js b/src/rules/checkLineAlignment.js index 910ea525e..fc053fdae 100644 --- a/src/rules/checkLineAlignment.js +++ b/src/rules/checkLineAlignment.js @@ -97,6 +97,7 @@ const checkNotAlignedPerTag = (utils, tag) => { }; const checkAlignment = ({ + customSpacings, indent, jsdoc, jsdocNode, @@ -105,7 +106,14 @@ const checkAlignment = ({ tags, utils, }) => { - const transform = commentFlow(alignTransform(tags, indent, preserveMainDescriptionPostDelimiter)); + const transform = commentFlow( + alignTransform({ + customSpacings, + indent, + preserveMainDescriptionPostDelimiter, + tags, + }), + ); const transformedJsdoc = transform(jsdoc); const comment = '/*' + jsdocNode.value + '*/'; @@ -133,6 +141,7 @@ export default iterateJsdoc(({ const { tags: applicableTags = ['param', 'arg', 'argument', 'property', 'prop', 'returns', 'return'], preserveMainDescriptionPostDelimiter, + customSpacings, } = context.options[1] || {}; if (context.options[0] === 'always') { @@ -142,6 +151,7 @@ export default iterateJsdoc(({ } checkAlignment({ + customSpacings, indent, jsdoc, jsdocNode, @@ -174,6 +184,9 @@ export default iterateJsdoc(({ { additionalProperties: false, properties: { + customSpacings: { + type: 'object', + }, preserveMainDescriptionPostDelimiter: { default: false, type: 'boolean', diff --git a/test/rules/assertions/checkLineAlignment.js b/test/rules/assertions/checkLineAlignment.js index 5849aa6b1..e4a61a280 100644 --- a/test/rules/assertions/checkLineAlignment.js +++ b/test/rules/assertions/checkLineAlignment.js @@ -917,6 +917,47 @@ export default { const fn = ( lorem, sit ) => {} `, }, + { + code: ` + /** + * Function description + * description with post delimiter. + * + * @param {string} lorem Description. + * @param {int} sit Description multi words. + * + * @return {string} Return description. + */ + const fn = ( lorem, sit ) => {} + `, + errors: [ + { + line: 2, + message: 'Expected JSDoc block lines to be aligned.', + type: 'Block', + }, + ], + options: ['always', { + customSpacings: { + postDelimiter: 2, + postName: 2, + postTag: 2, + postType: 2, + }, + }], + output: ` + /** + * Function description + * description with post delimiter. + * + * @param {string} lorem Description. + * @param {int} sit Description multi words. + * + * @return {string} Return description. + */ + const fn = ( lorem, sit ) => {} + `, + }, ], valid: [ { From 299930f0838168a7691308ce7aba7ea596ef9310 Mon Sep 17 00:00:00 2001 From: Renatho De Carli Rosa Date: Sun, 16 May 2021 19:48:30 -0300 Subject: [PATCH 3/8] Add custom spacings for the alignment --- src/rules/checkLineAlignment.js | 12 ++--- test/rules/assertions/checkLineAlignment.js | 49 +++++++++++++++++---- 2 files changed, 47 insertions(+), 14 deletions(-) diff --git a/src/rules/checkLineAlignment.js b/src/rules/checkLineAlignment.js index fc053fdae..f2a332f53 100644 --- a/src/rules/checkLineAlignment.js +++ b/src/rules/checkLineAlignment.js @@ -8,7 +8,7 @@ const { flow: commentFlow, } = transforms; -const checkNotAlignedPerTag = (utils, tag) => { +const checkNotAlignedPerTag = (utils, tag, customSpacings) => { /* start + delimiter + @@ -61,11 +61,12 @@ const checkNotAlignedPerTag = (utils, tag) => { const contentProp = contentProps[idx]; const contentPropVal = tokens[contentProp]; const spacerPropVal = tokens[spacerProp]; + const spacing = customSpacings?.[spacerProp] || 1; // There will be extra alignment if... - // 1. There is extra whitespace within a single spacer segment OR - return spacerPropVal.length > 1 || + // 1. The spaces doesn't match the space it should have (1 or custom spacing) OR + return spacerPropVal.length !== spacing && spacerPropVal.length !== 0 || // 2. There is a (single) space, no immediate content, and yet another // space is found subsequently (not separated by intervening content) @@ -80,7 +81,8 @@ const checkNotAlignedPerTag = (utils, tag) => { const contentPropVal = tokens[contentProp]; if (contentPropVal) { - tokens[spacerProp] = ' '; + const spacing = customSpacings?.[spacerProp] || 1; + tokens[spacerProp] = ''.padStart(spacing, ' '); followedBySpace(idx, (hasSpace, contentPrp) => { if (hasSpace) { tokens[contentPrp] = ''; @@ -166,7 +168,7 @@ export default iterateJsdoc(({ const foundTags = utils.getPresentTags(applicableTags); foundTags.forEach((tag) => { - checkNotAlignedPerTag(utils, tag); + checkNotAlignedPerTag(utils, tag, customSpacings); }); }, { iterateAllJsdocs: true, diff --git a/test/rules/assertions/checkLineAlignment.js b/test/rules/assertions/checkLineAlignment.js index e4a61a280..89db49139 100644 --- a/test/rules/assertions/checkLineAlignment.js +++ b/test/rules/assertions/checkLineAlignment.js @@ -920,8 +920,7 @@ export default { { code: ` /** - * Function description - * description with post delimiter. + * Function description. * * @param {string} lorem Description. * @param {int} sit Description multi words. @@ -940,20 +939,52 @@ export default { options: ['always', { customSpacings: { postDelimiter: 2, - postName: 2, - postTag: 2, + postTag: 3, postType: 2, }, }], output: ` /** - * Function description - * description with post delimiter. + * Function description. + * + * @param {string} lorem Description. + * @param {int} sit Description multi words. + * + * @return {string} Return description. + */ + const fn = ( lorem, sit ) => {} + `, + }, + { + code: ` + /** + * Function description. * - * @param {string} lorem Description. - * @param {int} sit Description multi words. + * @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: { + postDelimiter: 2, + postTag: 3, + postType: 2, + }, + }], + output: ` + /** + * Function description. * - * @return {string} Return description. + * @param {string} lorem Description. + * @param {int} sit Description multi words. */ const fn = ( lorem, sit ) => {} `, From dc6dc980d9b594f29537848ad545ff5627381e29 Mon Sep 17 00:00:00 2001 From: Renatho De Carli Rosa Date: Mon, 17 May 2021 10:55:18 -0300 Subject: [PATCH 4/8] Update src/rules/checkLineAlignment.js Co-authored-by: Brett Zamir --- src/rules/checkLineAlignment.js | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/rules/checkLineAlignment.js b/src/rules/checkLineAlignment.js index f2a332f53..55df9ff91 100644 --- a/src/rules/checkLineAlignment.js +++ b/src/rules/checkLineAlignment.js @@ -65,7 +65,7 @@ const checkNotAlignedPerTag = (utils, tag, customSpacings) => { // There will be extra alignment if... - // 1. The spaces doesn't match the space it should have (1 or custom spacing) OR + // 1. The spaces don't match the space it should have (1 or custom spacing) OR return spacerPropVal.length !== spacing && spacerPropVal.length !== 0 || // 2. There is a (single) space, no immediate content, and yet another From 4c973f52c8ee1a156bec02a28b7226ea5ee9eb4a Mon Sep 17 00:00:00 2001 From: Renatho De Carli Rosa Date: Mon, 17 May 2021 10:55:59 -0300 Subject: [PATCH 5/8] Update customSpacings properties --- src/rules/checkLineAlignment.js | 16 +++++++++++++++- 1 file changed, 15 insertions(+), 1 deletion(-) diff --git a/src/rules/checkLineAlignment.js b/src/rules/checkLineAlignment.js index 55df9ff91..d7fccce22 100644 --- a/src/rules/checkLineAlignment.js +++ b/src/rules/checkLineAlignment.js @@ -187,7 +187,21 @@ export default iterateJsdoc(({ additionalProperties: false, properties: { customSpacings: { - type: 'object', + additionalProperties: false, + properties: { + postDelimiter: { + type: 'integer', + }, + postName: { + type: 'integer', + }, + postTag: { + type: 'integer', + }, + postType: { + type: 'integer', + }, + }, }, preserveMainDescriptionPostDelimiter: { default: false, From 3d626b0e51bace5e8bc02ca8a56075720c69c86c Mon Sep 17 00:00:00 2001 From: Renatho De Carli Rosa Date: Mon, 17 May 2021 10:59:52 -0300 Subject: [PATCH 6/8] Add more customSpacings tests --- test/rules/assertions/checkLineAlignment.js | 108 ++++++++++++++++++++ 1 file changed, 108 insertions(+) diff --git a/test/rules/assertions/checkLineAlignment.js b/test/rules/assertions/checkLineAlignment.js index 89db49139..438d6f745 100644 --- a/test/rules/assertions/checkLineAlignment.js +++ b/test/rules/assertions/checkLineAlignment.js @@ -955,6 +955,42 @@ export default { const fn = ( lorem, sit ) => {} `, }, + { + code: ` + /** + * Function description. + * + * @param {string} lorem Description. + * @param {int} sit Description multi words. + * + * @return {string} Return description. + */ + const fn = ( lorem, sit ) => {} + `, + errors: [ + { + line: 2, + message: 'Expected JSDoc block lines to be aligned.', + type: 'Block', + }, + ], + options: ['always', { + customSpacings: { + postName: 3, + }, + }], + output: ` + /** + * Function description. + * + * @param {string} lorem Description. + * @param {int} sit Description multi words. + * + * @return {string} Return description. + */ + const fn = ( lorem, sit ) => {} + `, + }, { code: ` /** @@ -989,6 +1025,38 @@ 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', { + customSpacings: { + postName: 3, + }, + }], + output: ` + /** + * Function description. + * + * @param {string} lorem Description. + * @param {int} sit Description multi words. + */ + const fn = ( lorem, sit ) => {} + `, + }, ], valid: [ { @@ -1327,5 +1395,45 @@ export default { preserveMainDescriptionPostDelimiter: true, }], }, + { + code: ` + /** + * Function description. + * + * @param {string} lorem Description. + * @param {int} sit Description multi words. + * + * @return {string} Return description. + */ + const fn = ( lorem, sit ) => {} + `, + options: ['always', { + customSpacings: { + postDelimiter: 2, + postTag: 3, + postType: 2, + }, + }], + }, + { + code: ` + /** + * Function description. + * + * @param {string} lorem Description. + * @param {int} sit Description multi words. + * + * @return {string} Return description. + */ + const fn = ( lorem, sit ) => {} + `, + options: ['never', { + customSpacings: { + postDelimiter: 2, + postTag: 3, + postType: 2, + }, + }], + }, ], }; From 89ba4426d18d956c297ae808fabb1d0c678db4e8 Mon Sep 17 00:00:00 2001 From: Brett Zamir Date: Mon, 17 May 2021 22:29:11 +0800 Subject: [PATCH 7/8] docs: update README --- README.md | 66 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 66 insertions(+) diff --git a/README.md b/README.md index 789da96f7..4d6e722fe 100644 --- a/README.md +++ b/README.md @@ -2264,6 +2264,50 @@ function quux () {} 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. + * + * @return {string} Return description. + */ +const fn = ( lorem, sit ) => {} +// "jsdoc/check-line-alignment": ["error"|"warn", "always",{"customSpacings":{"postDelimiter":2,"postTag":3,"postType":2}}] +// Message: Expected JSDoc block lines to be aligned. + +/** + * Function description. + * + * @param {string} lorem Description. + * @param {int} sit Description multi words. + * + * @return {string} Return description. + */ +const fn = ( lorem, sit ) => {} +// "jsdoc/check-line-alignment": ["error"|"warn", "always",{"customSpacings":{"postName":3}}] +// 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":{"postDelimiter":2,"postTag":3,"postType":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":{"postName":3}}] +// Message: Expected JSDoc block lines to not be aligned. ```` The following patterns are not considered problems: @@ -2489,6 +2533,28 @@ function func(parameter){ */ const fn = ( lorem, sit ) => {} // "jsdoc/check-line-alignment": ["error"|"warn", "always",{"preserveMainDescriptionPostDelimiter":true}] + +/** + * Function description. + * + * @param {string} lorem Description. + * @param {int} sit Description multi words. + * + * @return {string} Return description. + */ +const fn = ( lorem, sit ) => {} +// "jsdoc/check-line-alignment": ["error"|"warn", "always",{"customSpacings":{"postDelimiter":2,"postTag":3,"postType":2}}] + +/** + * Function description. + * + * @param {string} lorem Description. + * @param {int} sit Description multi words. + * + * @return {string} Return description. + */ +const fn = ( lorem, sit ) => {} +// "jsdoc/check-line-alignment": ["error"|"warn", "never",{"customSpacings":{"postDelimiter":2,"postTag":3,"postType":2}}] ```` From ed51b44bc7beca4472d73b9875b4aeecf94204f1 Mon Sep 17 00:00:00 2001 From: Brett Zamir Date: Mon, 17 May 2021 22:35:42 +0800 Subject: [PATCH 8/8] add docs --- .README/rules/check-line-alignment.md | 13 ++++++++++++- README.md | 14 +++++++++++++- 2 files changed, 25 insertions(+), 2 deletions(-) diff --git a/.README/rules/check-line-alignment.md b/.README/rules/check-line-alignment.md index 1ae10ba4b..87a807e8a 100644 --- a/.README/rules/check-line-alignment.md +++ b/.README/rules/check-line-alignment.md @@ -22,10 +22,21 @@ Use this to change the tags which are sought for alignment changes. *Currently* *only works with the "never" option.* Defaults to an array of `['param', 'arg', 'argument', 'property', 'prop', 'returns', 'return']`. +##### `customSpacings` + +An object with any of the following keys set to an integer. Affects spacing: + +- `postDelimiter` - after the asterisk (e.g., `* @param`) +- `postTag` - after the tag (e.g., `* @param `) +- `postType` - after the type (e.g., `* @param {someType} `) +- `postName` - after the name (e.g., `* @param {someType} name `) + +If a spacing is not defined, it defaults to one. + ||| |---|---| |Context|everywhere| -|Options|(a string matching `"always" or "never"` and optional object with `tags`)| +|Options|(a string matching `"always" or "never"` and optional object with `tags` and `customSpacings`)| |Tags|`param`, `property`, `returns` and others added by `tags`| |Aliases|`arg`, `argument`, `prop`, `return`| |Recommended|false| diff --git a/README.md b/README.md index 4d6e722fe..c7a3026f5 100644 --- a/README.md +++ b/README.md @@ -1944,10 +1944,22 @@ Use this to change the tags which are sought for alignment changes. *Currently* *only works with the "never" option.* Defaults to an array of `['param', 'arg', 'argument', 'property', 'prop', 'returns', 'return']`. + +##### customSpacings + +An object with any of the following keys set to an integer. Affects spacing: + +- `postDelimiter` - after the asterisk (e.g., `* @param`) +- `postTag` - after the tag (e.g., `* @param `) +- `postType` - after the type (e.g., `* @param {someType} `) +- `postName` - after the name (e.g., `* @param {someType} name `) + +If a spacing is not defined, it defaults to one. + ||| |---|---| |Context|everywhere| -|Options|(a string matching `"always" or "never"` and optional object with `tags`)| +|Options|(a string matching `"always" or "never"` and optional object with `tags` and `customSpacings`)| |Tags|`param`, `property`, `returns` and others added by `tags`| |Aliases|`arg`, `argument`, `prop`, `return`| |Recommended|false|