Skip to content

feat: postHyphens option to control spacing after hyphens #974

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
brettz9 merged 1 commit into from
Feb 3, 2023
Merged

feat: postHyphens option to control spacing after hyphens #974

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .README/rules/check-line-alignment.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
61 changes: 61 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down Expand Up @@ -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:
Expand Down
6 changes: 6 additions & 0 deletions src/alignTransform.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 {
Expand Down
19 changes: 18 additions & 1 deletion src/rules/checkLineAlignment.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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;
}
Expand All @@ -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);
};

Expand Down Expand Up @@ -212,6 +226,9 @@ export default iterateJsdoc(({
postDelimiter: {
type: 'integer',
},
postHyphen: {
type: 'integer',
},
postName: {
type: 'integer',
},
Expand Down
202 changes: 202 additions & 0 deletions test/rules/assertions/checkLineAlignment.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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: [
{
Expand Down