diff --git a/.README/rules/check-line-alignment.md b/.README/rules/check-line-alignment.md index f5859d0d0..a45c0ce18 100644 --- a/.README/rules/check-line-alignment.md +++ b/.README/rules/check-line-alignment.md @@ -49,12 +49,16 @@ main description. If `false` or unset, will be set to a single space. The indent that will be applied for tag text after the first line. Default to the empty string (no indent). +### `disableWrapIndent` + +Disables `wrapIndent`; existing wrap indentation is preserved without changes. + ## Context and settings ||| |---|---| |Context|everywhere| -|Options|string ("always", "never", "any") followed by object with `customSpacings`, `preserveMainDescriptionPostDelimiter`, `tags`, `wrapIndent`| +|Options|string ("always", "never", "any") followed by object with `customSpacings`, `preserveMainDescriptionPostDelimiter`, `tags`, `wrapIndent`, `disableWrapIndent`| |Tags|`param`, `property`, `returns` and others added by `tags`| |Aliases|`arg`, `argument`, `prop`, `return`| |Recommended|false| diff --git a/docs/rules/check-line-alignment.md b/docs/rules/check-line-alignment.md index 0d55e9a0f..ffdf16f50 100644 --- a/docs/rules/check-line-alignment.md +++ b/docs/rules/check-line-alignment.md @@ -8,6 +8,7 @@ * [`customSpacings`](#user-content-check-line-alignment-options-customspacings) * [`preserveMainDescriptionPostDelimiter`](#user-content-check-line-alignment-options-preservemaindescriptionpostdelimiter) * [`wrapIndent`](#user-content-check-line-alignment-options-wrapindent) + * [`disableWrapIndent`](#user-content-check-line-alignment-options-disablewrapindent) * [Context and settings](#user-content-check-line-alignment-context-and-settings) * [Failing examples](#user-content-check-line-alignment-failing-examples) * [Passing examples](#user-content-check-line-alignment-passing-examples) @@ -72,6 +73,12 @@ main description. If `false` or unset, will be set to a single space. The indent that will be applied for tag text after the first line. Default to the empty string (no indent). + + +### disableWrapIndent + +Disables `wrapIndent`; existing wrap indentation is preserved without changes. + ## Context and settings @@ -79,7 +86,7 @@ Default to the empty string (no indent). ||| |---|---| |Context|everywhere| -|Options|string ("always", "never", "any") followed by object with `customSpacings`, `preserveMainDescriptionPostDelimiter`, `tags`, `wrapIndent`| +|Options|string ("always", "never", "any") followed by object with `customSpacings`, `preserveMainDescriptionPostDelimiter`, `tags`, `wrapIndent`, `disableWrapIndent`| |Tags|`param`, `property`, `returns` and others added by `tags`| |Aliases|`arg`, `argument`, `prop`, `return`| |Recommended|false| @@ -998,5 +1005,23 @@ function quux () {} * @returns {number} -1 if world transform has negative scale, 1 otherwise. */ // "jsdoc/check-line-alignment": ["error"|"warn", "never"] + +/** + * @param {string} lorem Description + * with multiple lines preserving existing indentation when wrapIndent is disabled. + */ +function quux () { +} +// "jsdoc/check-line-alignment": ["error"|"warn", "any",{"disableWrapIndent":true}] + +/** + * Function description with disableWrapIndent true, but wrapIndent defined. + * Preserves existing indentation regardless of wrapIndent value. + * + * @param {string} lorem Description + * with multiple lines. + */ +const fn = ( lorem ) => {} +// "jsdoc/check-line-alignment": ["error"|"warn", "any",{"disableWrapIndent":true,"wrapIndent":" "}] ```` diff --git a/src/alignTransform.js b/src/alignTransform.js index c12cb7eb3..46871e7d5 100644 --- a/src/alignTransform.js +++ b/src/alignTransform.js @@ -151,6 +151,7 @@ const space = (len) => { * indent: string, * preserveMainDescriptionPostDelimiter: boolean, * wrapIndent: string, + * disableWrapIndent: boolean, * }} cfg * @returns {( * block: import('comment-parser').Block @@ -162,6 +163,7 @@ const alignTransform = ({ indent, preserveMainDescriptionPostDelimiter, wrapIndent, + disableWrapIndent, }) => { let intoTags = false; /** @type {Width} */ @@ -314,7 +316,7 @@ const alignTransform = ({ // Not align. if (shouldAlign(tags, index, source)) { alignTokens(tokens, typelessInfo); - if (indentTag) { + if (!disableWrapIndent && indentTag) { tokens.postDelimiter += wrapIndent; } } @@ -340,10 +342,10 @@ const alignTransform = ({ return rewireSource({ ...fields, source: source.map((line, index) => { - const indentTag = tagIndentMode && !line.tokens.tag && line.tokens.description; + const indentTag = !disableWrapIndent && tagIndentMode && !line.tokens.tag && line.tokens.description; const ret = update(line, index, source, typelessInfo, indentTag); - if (line.tokens.tag) { + if (!disableWrapIndent && line.tokens.tag) { tagIndentMode = true; } diff --git a/src/rules/checkLineAlignment.js b/src/rules/checkLineAlignment.js index b592abd6e..1e9f80203 100644 --- a/src/rules/checkLineAlignment.js +++ b/src/rules/checkLineAlignment.js @@ -169,6 +169,7 @@ const checkNotAlignedPerTag = (utils, tag, customSpacings) => { * @param {string[]} cfg.tags * @param {import('../iterateJsdoc.js').Utils} cfg.utils * @param {string} cfg.wrapIndent + * @param {boolean} cfg.disableWrapIndent * @returns {void} */ const checkAlignment = ({ @@ -181,6 +182,7 @@ const checkAlignment = ({ tags, utils, wrapIndent, + disableWrapIndent, }) => { const transform = commentFlow( alignTransform({ @@ -189,6 +191,7 @@ const checkAlignment = ({ preserveMainDescriptionPostDelimiter, tags, wrapIndent, + disableWrapIndent, }), ); const transformedJsdoc = transform(jsdoc); @@ -228,6 +231,7 @@ export default iterateJsdoc(({ preserveMainDescriptionPostDelimiter, customSpacings, wrapIndent = '', + disableWrapIndent = false, } = context.options[1] || {}; if (context.options[0] === 'always') { @@ -253,6 +257,7 @@ export default iterateJsdoc(({ tags: applicableTags, utils, wrapIndent, + disableWrapIndent, }); return; @@ -293,7 +298,7 @@ export default iterateJsdoc(({ } // Don't include a single separating space/tab - if (tokens.postDelimiter.slice(1) !== wrapIndent) { + if (!disableWrapIndent && tokens.postDelimiter.slice(1) !== wrapIndent) { utils.reportJSDoc('Expected wrap indent', { line: tag.source[0].number + idx, }, () => { @@ -355,6 +360,9 @@ export default iterateJsdoc(({ wrapIndent: { type: 'string', }, + disableWrapIndent: { + type: 'boolean', + }, }, type: 'object', }, diff --git a/test/rules/assertions/checkLineAlignment.js b/test/rules/assertions/checkLineAlignment.js index 40adbd9e7..960193cbc 100644 --- a/test/rules/assertions/checkLineAlignment.js +++ b/test/rules/assertions/checkLineAlignment.js @@ -2182,5 +2182,40 @@ export default { 'never', ], }, + { + code: ` + /** + * @param {string} lorem Description + * with multiple lines preserving existing indentation when wrapIndent is disabled. + */ + function quux () { + } + `, + options: [ + 'any', + { + disableWrapIndent: true, + }, + ], + }, + { + code: ` + /** + * Function description with disableWrapIndent true, but wrapIndent defined. + * Preserves existing indentation regardless of wrapIndent value. + * + * @param {string} lorem Description + * with multiple lines. + */ + const fn = ( lorem ) => {} + `, + options: [ + 'any', + { + disableWrapIndent: true, + wrapIndent: ' ', + }, + ], + }, ], };