Skip to content

Commit

Permalink
feat(multiline-blocks): add noFinalLineText option; fixes #738
Browse files Browse the repository at this point in the history
  • Loading branch information
@brettz9
brettz9 committed May 17, 2021
1 parent 1932b5b commit 03d3f40
Show file tree
Hide file tree
Showing 5 changed files with 153 additions and 6 deletions.
11 changes: 10 additions & 1 deletion .README/rules/multiline-blocks.md
View file
Expand Up @@ -7,6 +7,8 @@ Note that if you set `noSingleLineBlocks` and `noMultilineBlocks` to `true`
and configure them in a certain manner, you might effectively be prohibiting
all jsdoc blocks!

Also allows for preventing text at the very beginning or very end of blocks.

#### Options

A single options object with the following properties.
Expand All @@ -18,6 +20,13 @@ space will be reported. (Text after a newline is not reported.)

`noMultilineBlocks` will have priority over this rule if it applies.

##### `noFinalLineText` (defaults to `true`)

For multiline blocks, any non-whitespace text preceding the `*/` on the final
line will be reported. (Text preceding a newline is not reported.)

`noMultilineBlocks` will have priority over this rule if it applies.

##### `noSingleLineBlocks` (defaults to `false`)

If this is `true`, any single line blocks will be reported, except those which
Expand Down Expand Up @@ -79,6 +88,6 @@ cannot be reliably added after the tag either).
|Tags|Any (though `singleLineTags` and `multilineTags` control the application)|
|Recommended|true|
|Settings||
|Options|`noZeroLineText`, `noSingleLineBlocks`, `singleLineTags`, `noMultilineBlocks`, `minimumLengthForMultiline`, `multilineTags`, `allowMultipleTags`|
|Options|`noZeroLineText`, `noSingleLineBlocks`, `singleLineTags`, `noMultilineBlocks`, `minimumLengthForMultiline`, `multilineTags`, `allowMultipleTags`, `noFinalLineText`|

<!-- assertions multilineBlocks -->
33 changes: 32 additions & 1 deletion README.md
View file
Expand Up @@ -7138,6 +7138,8 @@ Note that if you set `noSingleLineBlocks` and `noMultilineBlocks` to `true`
and configure them in a certain manner, you might effectively be prohibiting
all jsdoc blocks!
Also allows for preventing text at the very beginning or very end of blocks.
<a name="eslint-plugin-jsdoc-rules-multiline-blocks-options-12"></a>
#### Options
Expand All @@ -7151,6 +7153,14 @@ space will be reported. (Text after a newline is not reported.)
`noMultilineBlocks` will have priority over this rule if it applies.
<a name="eslint-plugin-jsdoc-rules-multiline-blocks-options-12-nofinallinetext-defaults-to-true"></a>
##### <code>noFinalLineText</code> (defaults to <code>true</code>)
For multiline blocks, any non-whitespace text preceding the `*/` on the final
line will be reported. (Text preceding a newline is not reported.)
`noMultilineBlocks` will have priority over this rule if it applies.
<a name="eslint-plugin-jsdoc-rules-multiline-blocks-options-12-nosinglelineblocks-defaults-to-false"></a>
##### <code>noSingleLineBlocks</code> (defaults to <code>false</code>)
Expand Down Expand Up @@ -7218,7 +7228,7 @@ cannot be reliably added after the tag either).
|Tags|Any (though `singleLineTags` and `multilineTags` control the application)|
|Recommended|true|
|Settings||
|Options|`noZeroLineText`, `noSingleLineBlocks`, `singleLineTags`, `noMultilineBlocks`, `minimumLengthForMultiline`, `multilineTags`, `allowMultipleTags`|
|Options|`noZeroLineText`, `noSingleLineBlocks`, `singleLineTags`, `noMultilineBlocks`, `minimumLengthForMultiline`, `multilineTags`, `allowMultipleTags`, `noFinalLineText`|
The following patterns are considered problems:
Expand Down Expand Up @@ -7367,6 +7377,16 @@ The following patterns are considered problems:
* line. */
// "jsdoc/multiline-blocks": ["error"|"warn", {"multilineTags":[],"noMultilineBlocks":true}]
// Message: Multiline jsdoc blocks are prohibited by your configuration.
/**
* @someTag {aType} with Description */
// "jsdoc/multiline-blocks": ["error"|"warn", {"noFinalLineBlocks":true}]
// Message: Should have no text on the final line (before the `*/`).
/**
* Description */
// "jsdoc/multiline-blocks": ["error"|"warn", {"noFinalLineBlocks":true}]
// Message: Should have no text on the final line (before the `*/`).
````
The following patterns are not considered problems:
Expand Down Expand Up @@ -7469,6 +7489,9 @@ The following patterns are not considered problems:
* @oneTag
*/
// "jsdoc/multiline-blocks": ["error"|"warn", {"allowMultipleTags":false,"multilineTags":["oneTag"],"noMultilineBlocks":true}]
/** @someTag with Description */
// "jsdoc/multiline-blocks": ["error"|"warn", {"noFinalLineBlocks":true}]
````
Expand Down Expand Up @@ -8293,6 +8316,14 @@ The following patterns are considered problems:

/** abc * */
// Message: Should be no multiple asterisks on end lines.

/**
* Preserve user's whitespace when fixing (though one may also
* use an align rule)
*
* */
// "jsdoc/no-multi-asterisks": ["error"|"warn", {"preventAtEnd":true}]
// Message: Should be no multiple asterisks on end lines.
````

The following patterns are not considered problems:
Expand Down
48 changes: 44 additions & 4 deletions src/rules/multilineBlocks.js
View file
Expand Up @@ -8,6 +8,7 @@ export default iterateJsdoc(({
}) => {
const {
allowMultipleTags = true,
noFinalLineText = true,
noZeroLineText = true,
noSingleLineBlocks = false,
singleLineTags = ['lends', 'type'],
Expand Down Expand Up @@ -96,7 +97,7 @@ export default iterateJsdoc(({
return;
}

const checkZeroLineText = () => {
const lineChecks = () => {
if (
noZeroLineText &&
(tag || description)
Expand All @@ -111,6 +112,42 @@ export default iterateJsdoc(({
'Should have no text on the "0th" line (after the `/**`).',
null, fixer,
);

return;
}

const finalLine = jsdoc.source[jsdoc.source.length - 1];
const finalLineTokens = finalLine.tokens;
if (
noFinalLineText &&
finalLineTokens.description.trim()
) {
const fixer = () => {
const line = {...finalLineTokens};
line.description = line.description.trimEnd();

const {delimiter} = line;

[
'delimiter',
'postDelimiter',
'tag',
'type',
'postType',
'postTag',
'name',
'postName',
'description',
].forEach((prop) => {
finalLineTokens[prop] = '';
});

utils.addLine(jsdoc.source.length - 1, {...line, delimiter, end: ''});
};
utils.reportJSDoc(
'Should have no text on the final line (before the `*/`).',
null, fixer,
);
}
};

Expand All @@ -119,13 +156,13 @@ export default iterateJsdoc(({
jsdoc.tags.length &&
(multilineTags.includes('*') || utils.hasATag(multilineTags))
) {
checkZeroLineText();
lineChecks();

return;
}

if (jsdoc.description.length >= minimumLengthForMultiline) {
checkZeroLineText();
lineChecks();

return;
}
Expand Down Expand Up @@ -222,7 +259,7 @@ export default iterateJsdoc(({
}
}

checkZeroLineText();
lineChecks();
}, {
iterateAllJsdocs: true,
meta: {
Expand Down Expand Up @@ -254,6 +291,9 @@ export default iterateJsdoc(({
},
],
},
noFinalLineText: {
type: 'boolean',
},
noMultilineBlocks: {
type: 'boolean',
},
Expand Down
44 changes: 44 additions & 0 deletions test/rules/assertions/multilineBlocks.js
View file
Expand Up @@ -467,6 +467,42 @@ export default {
/** @lends This can be safely fixed to a single line. */
`,
},
{
code: `
/**
* @someTag {aType} with Description */
`,
errors: [{
line: 2,
message: 'Should have no text on the final line (before the `*/`).',
}],
options: [{
noFinalLineBlocks: true,
}],
output: `
/**
* @someTag {aType} with Description
*/
`,
},
{
code: `
/**
* Description */
`,
errors: [{
line: 2,
message: 'Should have no text on the final line (before the `*/`).',
}],
options: [{
noFinalLineBlocks: true,
}],
output: `
/**
* Description
*/
`,
},
],
valid: [
{
Expand Down Expand Up @@ -685,5 +721,13 @@ export default {
noMultilineBlocks: true,
}],
},
{
code: `
/** @someTag with Description */
`,
options: [{
noFinalLineBlocks: true,
}],
},
],
};
23 changes: 23 additions & 0 deletions test/rules/assertions/noMultiAsterisks.js
View file
Expand Up @@ -215,6 +215,29 @@ export default {
/** abc */
`,
},
{
code: `
/**
* Preserve user's whitespace when fixing (though one may also
* use an align rule)
*
* */
`,
errors: [{
line: 6,
message: 'Should be no multiple asterisks on end lines.',
}],
options: [{
preventAtEnd: true,
}],
output: `
/**
* Preserve user's whitespace when fixing (though one may also
* use an align rule)
*
*/
`,
},
],
valid: [
{
Expand Down

0 comments on commit 03d3f40

Please sign in to comment.