Skip to content

Commit

Permalink
feat(check-line-alignment): add disableWrapIndent` option
Browse files Browse the repository at this point in the history
  • Loading branch information
davidmurdoch authored and brettz9 committed Feb 14, 2024
1 parent e9a9b74 commit 37df54d
Show file tree
Hide file tree
Showing 5 changed files with 80 additions and 6 deletions.
6 changes: 5 additions & 1 deletion .README/rules/check-line-alignment.md
Original file line number Diff line number Diff line change
Expand Up @@ -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|
Expand Down
27 changes: 26 additions & 1 deletion docs/rules/check-line-alignment.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down Expand Up @@ -72,14 +73,20 @@ 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).

<a name="user-content-check-line-alignment-options-disablewrapindent"></a>
<a name="check-line-alignment-options-disablewrapindent"></a>
### <code>disableWrapIndent</code>

Disables `wrapIndent`; existing wrap indentation is preserved without changes.

<a name="user-content-check-line-alignment-context-and-settings"></a>
<a name="check-line-alignment-context-and-settings"></a>
## 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|
Expand Down Expand Up @@ -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":" "}]
````

8 changes: 5 additions & 3 deletions src/alignTransform.js
Original file line number Diff line number Diff line change
Expand Up @@ -151,6 +151,7 @@ const space = (len) => {
* indent: string,
* preserveMainDescriptionPostDelimiter: boolean,
* wrapIndent: string,
* disableWrapIndent: boolean,
* }} cfg
* @returns {(
* block: import('comment-parser').Block
Expand All @@ -162,6 +163,7 @@ const alignTransform = ({
indent,
preserveMainDescriptionPostDelimiter,
wrapIndent,
disableWrapIndent,
}) => {
let intoTags = false;
/** @type {Width} */
Expand Down Expand Up @@ -314,7 +316,7 @@ const alignTransform = ({
// Not align.
if (shouldAlign(tags, index, source)) {
alignTokens(tokens, typelessInfo);
if (indentTag) {
if (!disableWrapIndent && indentTag) {
tokens.postDelimiter += wrapIndent;
}
}
Expand All @@ -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;
}

Expand Down
10 changes: 9 additions & 1 deletion src/rules/checkLineAlignment.js
Original file line number Diff line number Diff line change
Expand Up @@ -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 = ({
Expand All @@ -181,6 +182,7 @@ const checkAlignment = ({
tags,
utils,
wrapIndent,
disableWrapIndent,
}) => {
const transform = commentFlow(
alignTransform({
Expand All @@ -189,6 +191,7 @@ const checkAlignment = ({
preserveMainDescriptionPostDelimiter,
tags,
wrapIndent,
disableWrapIndent,
}),
);
const transformedJsdoc = transform(jsdoc);
Expand Down Expand Up @@ -228,6 +231,7 @@ export default iterateJsdoc(({
preserveMainDescriptionPostDelimiter,
customSpacings,
wrapIndent = '',
disableWrapIndent = false,
} = context.options[1] || {};

if (context.options[0] === 'always') {
Expand All @@ -253,6 +257,7 @@ export default iterateJsdoc(({
tags: applicableTags,
utils,
wrapIndent,
disableWrapIndent,
});

return;
Expand Down Expand Up @@ -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,
}, () => {
Expand Down Expand Up @@ -355,6 +360,9 @@ export default iterateJsdoc(({
wrapIndent: {
type: 'string',
},
disableWrapIndent: {
type: 'boolean',
},
},
type: 'object',
},
Expand Down
35 changes: 35 additions & 0 deletions test/rules/assertions/checkLineAlignment.js
Original file line number Diff line number Diff line change
Expand Up @@ -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: ' ',
},
],
},
],
};

0 comments on commit 37df54d

Please sign in to comment.