Skip to content

Commit a143226

Browse files
committed
feat: postHyphens option to control spacing after hyphens; fixes #972
1 parent 784e351 commit a143226

File tree

5 files changed

+288
-1
lines changed

5 files changed

+288
-1
lines changed

.README/rules/check-line-alignment.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,7 @@ An object with any of the following keys set to an integer. Affects spacing:
3030
- `postTag` - after the tag (e.g., `* @param `)
3131
- `postType` - after the type (e.g., `* @param {someType} `)
3232
- `postName` - after the name (e.g., `* @param {someType} name `)
33+
- `postHyphens` - after any hyphens in the description (e.g., `* @param {someType} name - A description`)
3334

3435
If a spacing is not defined, it defaults to one.
3536

README.md

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2047,6 +2047,7 @@ An object with any of the following keys set to an integer. Affects spacing:
20472047
- `postTag` - after the tag (e.g., `* @param `)
20482048
- `postType` - after the type (e.g., `* @param {someType} `)
20492049
- `postName` - after the name (e.g., `* @param {someType} name `)
2050+
- `postHyphens` - after any hyphens in the description (e.g., `* @param {someType} name - A description`)
20502051

20512052
If a spacing is not defined, it defaults to one.
20522053

@@ -2438,6 +2439,66 @@ const fn = ( lorem, sit ) => {}
24382439
const fn = ( lorem, sit ) => {}
24392440
// "jsdoc/check-line-alignment": ["error"|"warn", "always"]
24402441
// Message: Expected JSDoc block lines to be aligned.
2442+
2443+
/**
2444+
* Function description.
2445+
*
2446+
* @param {string} lorem - Description.
2447+
* @param {int} sit - Description multi words.
2448+
*/
2449+
const fn = ( lorem, sit ) => {}
2450+
// "jsdoc/check-line-alignment": ["error"|"warn", "never"]
2451+
// Message: Expected JSDoc block lines to not be aligned.
2452+
2453+
/**
2454+
* Function description.
2455+
*
2456+
* @param {string} lorem - Description.
2457+
* @param {int} sit - Description multi words.
2458+
*/
2459+
const fn = ( lorem, sit ) => {}
2460+
// "jsdoc/check-line-alignment": ["error"|"warn", "never",{"customSpacings":{"postHyphen":2}}]
2461+
// Message: Expected JSDoc block lines to not be aligned.
2462+
2463+
/**
2464+
* Function description.
2465+
*
2466+
* @param {string} lorem - Description.
2467+
* @param {int} sit - Description multi words.
2468+
*/
2469+
const fn = ( lorem, sit ) => {}
2470+
// "jsdoc/check-line-alignment": ["error"|"warn", "never",{"customSpacings":{"postHyphen":2}}]
2471+
// Message: Expected JSDoc block lines to not be aligned.
2472+
2473+
/**
2474+
* Function description.
2475+
*
2476+
* @param {string} lorem - Description.
2477+
* @param {int} sit - Description multi words.
2478+
*/
2479+
const fn = ( lorem, sit ) => {}
2480+
// "jsdoc/check-line-alignment": ["error"|"warn", "always",{"customSpacings":{"postHyphen":2}}]
2481+
// Message: Expected JSDoc block lines to be aligned.
2482+
2483+
/**
2484+
* Function description.
2485+
*
2486+
* @param {string} lorem - Description.
2487+
* @param {int} sit - Description multi words.
2488+
*/
2489+
const fn = ( lorem, sit ) => {}
2490+
// "jsdoc/check-line-alignment": ["error"|"warn", "always",{"customSpacings":{"postHyphen":2}}]
2491+
// Message: Expected JSDoc block lines to be aligned.
2492+
2493+
/**
2494+
* Function description.
2495+
*
2496+
* @param {string} lorem - Description.
2497+
* @param {int} sit - Description multi words.
2498+
*/
2499+
const fn = ( lorem, sit ) => {}
2500+
// "jsdoc/check-line-alignment": ["error"|"warn", "never",{"customSpacings":{"postHyphen":2}}]
2501+
// Message: Expected JSDoc block lines to not be aligned.
24412502
````
24422503

24432504
The following patterns are not considered problems:

src/alignTransform.js

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -233,6 +233,12 @@ const alignTransform = ({
233233
};
234234
}
235235

236+
const postHyphenSpacing = customSpacings?.postHyphen ?? 1;
237+
const hyphenSpacing = /^\s*-\s*/u;
238+
tokens.description = tokens.description.replace(
239+
hyphenSpacing, '-' + ''.padStart(postHyphenSpacing, ' '),
240+
);
241+
236242
// Not align.
237243
if (!shouldAlign(tags, index, source)) {
238244
return {

src/rules/checkLineAlignment.js

Lines changed: 18 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -64,6 +64,13 @@ const checkNotAlignedPerTag = (utils, tag, customSpacings) => {
6464
});
6565
};
6666

67+
const postHyphenSpacing = customSpacings?.postHyphen ?? 1;
68+
const exactHyphenSpacing = new RegExp(`^\\s*-\\s{${postHyphenSpacing},${postHyphenSpacing}}(?!\\s)`, 'u');
69+
const hasNoHyphen = !(/^\s*-/u).test(tokens.description);
70+
const hasExactHyphenSpacing = exactHyphenSpacing.test(
71+
tokens.description,
72+
);
73+
6774
// If checking alignment on multiple lines, need to check other `source`
6875
// items
6976
// Go through `post*` spacing properties and exit to indicate problem if
@@ -82,7 +89,7 @@ const checkNotAlignedPerTag = (utils, tag, customSpacings) => {
8289
// 2. There is a (single) space, no immediate content, and yet another
8390
// space is found subsequently (not separated by intervening content)
8491
spacerPropVal && !contentPropVal && followedBySpace(idx);
85-
});
92+
}) && (hasNoHyphen || hasExactHyphenSpacing);
8693
if (ok) {
8794
return;
8895
}
@@ -108,6 +115,13 @@ const checkNotAlignedPerTag = (utils, tag, customSpacings) => {
108115
}
109116
}
110117

118+
if (!hasExactHyphenSpacing) {
119+
const hyphenSpacing = /^\s*-\s*/u;
120+
tokens.description = tokens.description.replace(
121+
hyphenSpacing, '-' + ''.padStart(postHyphenSpacing, ' '),
122+
);
123+
}
124+
111125
utils.setTag(tag, tokens);
112126
};
113127

@@ -212,6 +226,9 @@ export default iterateJsdoc(({
212226
postDelimiter: {
213227
type: 'integer',
214228
},
229+
postHyphen: {
230+
type: 'integer',
231+
},
215232
postName: {
216233
type: 'integer',
217234
},

test/rules/assertions/checkLineAlignment.js

Lines changed: 202 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1157,6 +1157,208 @@ export default {
11571157
const fn = ( lorem, sit ) => {}
11581158
`,
11591159
},
1160+
{
1161+
code: `
1162+
/**
1163+
* Function description.
1164+
*
1165+
* @param {string} lorem - Description.
1166+
* @param {int} sit - Description multi words.
1167+
*/
1168+
const fn = ( lorem, sit ) => {}
1169+
`,
1170+
errors: [
1171+
{
1172+
line: 6,
1173+
message: 'Expected JSDoc block lines to not be aligned.',
1174+
type: 'Block',
1175+
},
1176+
],
1177+
options: [
1178+
'never',
1179+
],
1180+
output: `
1181+
/**
1182+
* Function description.
1183+
*
1184+
* @param {string} lorem - Description.
1185+
* @param {int} sit - Description multi words.
1186+
*/
1187+
const fn = ( lorem, sit ) => {}
1188+
`,
1189+
},
1190+
{
1191+
code: `
1192+
/**
1193+
* Function description.
1194+
*
1195+
* @param {string} lorem - Description.
1196+
* @param {int} sit - Description multi words.
1197+
*/
1198+
const fn = ( lorem, sit ) => {}
1199+
`,
1200+
errors: [
1201+
{
1202+
line: 6,
1203+
message: 'Expected JSDoc block lines to not be aligned.',
1204+
type: 'Block',
1205+
},
1206+
],
1207+
options: [
1208+
'never',
1209+
{
1210+
customSpacings: {
1211+
postHyphen: 2,
1212+
},
1213+
},
1214+
],
1215+
output: `
1216+
/**
1217+
* Function description.
1218+
*
1219+
* @param {string} lorem - Description.
1220+
* @param {int} sit - Description multi words.
1221+
*/
1222+
const fn = ( lorem, sit ) => {}
1223+
`,
1224+
},
1225+
{
1226+
code: `
1227+
/**
1228+
* Function description.
1229+
*
1230+
* @param {string} lorem - Description.
1231+
* @param {int} sit - Description multi words.
1232+
*/
1233+
const fn = ( lorem, sit ) => {}
1234+
`,
1235+
errors: [
1236+
{
1237+
line: 5,
1238+
message: 'Expected JSDoc block lines to not be aligned.',
1239+
type: 'Block',
1240+
},
1241+
],
1242+
options: [
1243+
'never',
1244+
{
1245+
customSpacings: {
1246+
postHyphen: 2,
1247+
},
1248+
},
1249+
],
1250+
output: `
1251+
/**
1252+
* Function description.
1253+
*
1254+
* @param {string} lorem - Description.
1255+
* @param {int} sit - Description multi words.
1256+
*/
1257+
const fn = ( lorem, sit ) => {}
1258+
`,
1259+
},
1260+
{
1261+
code: `
1262+
/**
1263+
* Function description.
1264+
*
1265+
* @param {string} lorem - Description.
1266+
* @param {int} sit - Description multi words.
1267+
*/
1268+
const fn = ( lorem, sit ) => {}
1269+
`,
1270+
errors: [
1271+
{
1272+
line: 2,
1273+
message: 'Expected JSDoc block lines to be aligned.',
1274+
type: 'Block',
1275+
},
1276+
],
1277+
options: [
1278+
'always', {
1279+
customSpacings: {
1280+
postHyphen: 2,
1281+
},
1282+
},
1283+
],
1284+
output: `
1285+
/**
1286+
* Function description.
1287+
*
1288+
* @param {string} lorem - Description.
1289+
* @param {int} sit - Description multi words.
1290+
*/
1291+
const fn = ( lorem, sit ) => {}
1292+
`,
1293+
},
1294+
{
1295+
code: `
1296+
/**
1297+
* Function description.
1298+
*
1299+
* @param {string} lorem - Description.
1300+
* @param {int} sit - Description multi words.
1301+
*/
1302+
const fn = ( lorem, sit ) => {}
1303+
`,
1304+
errors: [
1305+
{
1306+
line: 2,
1307+
message: 'Expected JSDoc block lines to be aligned.',
1308+
type: 'Block',
1309+
},
1310+
],
1311+
options: [
1312+
'always', {
1313+
customSpacings: {
1314+
postHyphen: 2,
1315+
},
1316+
},
1317+
],
1318+
output: `
1319+
/**
1320+
* Function description.
1321+
*
1322+
* @param {string} lorem - Description.
1323+
* @param {int} sit - Description multi words.
1324+
*/
1325+
const fn = ( lorem, sit ) => {}
1326+
`,
1327+
},
1328+
{
1329+
code: `
1330+
/**
1331+
* Function description.
1332+
*
1333+
* @param {string} lorem - Description.
1334+
* @param {int} sit - Description multi words.
1335+
*/
1336+
const fn = ( lorem, sit ) => {}
1337+
`,
1338+
errors: [
1339+
{
1340+
line: 5,
1341+
message: 'Expected JSDoc block lines to not be aligned.',
1342+
type: 'Block',
1343+
},
1344+
],
1345+
options: [
1346+
'never', {
1347+
customSpacings: {
1348+
postHyphen: 2,
1349+
},
1350+
},
1351+
],
1352+
output: `
1353+
/**
1354+
* Function description.
1355+
*
1356+
* @param {string} lorem - Description.
1357+
* @param {int} sit - Description multi words.
1358+
*/
1359+
const fn = ( lorem, sit ) => {}
1360+
`,
1361+
},
11601362
],
11611363
valid: [
11621364
{

0 commit comments

Comments
 (0)