diff --git a/.README/rules/lines-before-block.md b/.README/rules/lines-before-block.md index f453dace..29c8ac63 100644 --- a/.README/rules/lines-before-block.md +++ b/.README/rules/lines-before-block.md @@ -1,10 +1,15 @@ # `lines-before-block` This rule enforces minimum number of newlines before JSDoc comment blocks -(except at the beginning of a file). +(except at the beginning of a block or file). ## Options +### `checkBlockStarts` + +Whether to additionally check the start of blocks, such as classes or functions. +Defaults to `false`. + ### `lines` The minimum number of lines to require. Defaults to 1. @@ -26,7 +31,7 @@ lines before the block will not be added). |Tags|N/A| |Recommended|false| |Settings|| -|Options|`excludedTags`, `ignoreSameLine`, `lines`| +|Options|`checkBlockStarts`, `excludedTags`, `ignoreSameLine`, `lines`| ## Failing examples diff --git a/docs/rules/lines-before-block.md b/docs/rules/lines-before-block.md index f8465d0a..c6668ff4 100644 --- a/docs/rules/lines-before-block.md +++ b/docs/rules/lines-before-block.md @@ -3,12 +3,19 @@ # lines-before-block This rule enforces minimum number of newlines before JSDoc comment blocks -(except at the beginning of a file). +(except at the beginning of a block or file). ## Options + + +### checkBlockStarts + +Whether to additionally check the start of blocks, such as classes or functions. +Defaults to `false`. + ### lines @@ -36,7 +43,7 @@ lines before the block will not be added). |Tags|N/A| |Recommended|false| |Settings|| -|Options|`excludedTags`, `ignoreSameLine`, `lines`| +|Options|`checkBlockStarts`, `excludedTags`, `ignoreSameLine`, `lines`| @@ -87,6 +94,42 @@ someCode; * */ // Message: Required 1 line(s) before JSDoc block + +{ + /** + * Description. + */ + let value; +} +// "jsdoc/lines-before-block": ["error"|"warn", {"checkBlockStarts":true}] +// Message: Required 1 line(s) before JSDoc block + +class MyClass { + /** + * Description. + */ + method() {} +} +// "jsdoc/lines-before-block": ["error"|"warn", {"checkBlockStarts":true}] +// Message: Required 1 line(s) before JSDoc block + +function myFunction() { + /** + * Description. + */ + let value; +} +// "jsdoc/lines-before-block": ["error"|"warn", {"checkBlockStarts":true}] +// Message: Required 1 line(s) before JSDoc block + +const values = [ + /** + * Description. + */ + value, +]; +// "jsdoc/lines-before-block": ["error"|"warn", {"checkBlockStarts":true}] +// Message: Required 1 line(s) before JSDoc block ```` @@ -146,5 +189,26 @@ const a = /** @lends SomeClass */ { someProp: (someVal) }; // "jsdoc/lines-before-block": ["error"|"warn", {"excludedTags":["lends"],"ignoreSameLine":false}] + +{ + /** + * Description. + */ + let value; +} + +class MyClass { + /** + * Description. + */ + method() {} +} + +function myFunction() { + /** + * Description. + */ + let value; +} ```` diff --git a/src/rules/linesBeforeBlock.js b/src/rules/linesBeforeBlock.js index 086193c2..7d9f5952 100644 --- a/src/rules/linesBeforeBlock.js +++ b/src/rules/linesBeforeBlock.js @@ -8,6 +8,7 @@ export default iterateJsdoc(({ utils, }) => { const { + checkBlockStarts, lines = 1, ignoreSameLine = true, excludedTags = ['type'] @@ -19,7 +20,7 @@ export default iterateJsdoc(({ const tokensBefore = sourceCode.getTokensBefore(jsdocNode, {includeComments: true}); const tokenBefore = tokensBefore.slice(-1)[0]; - if (!tokenBefore) { + if (!tokenBefore || (tokenBefore.value === '{' && !checkBlockStarts)) { return; } @@ -80,6 +81,9 @@ export default iterateJsdoc(({ { additionalProperties: false, properties: { + checkBlockStarts: { + type: 'boolean', + }, excludedTags: { type: 'array', items: { diff --git a/test/rules/assertions/linesBeforeBlock.js b/test/rules/assertions/linesBeforeBlock.js index 51132b20..9551a38b 100644 --- a/test/rules/assertions/linesBeforeBlock.js +++ b/test/rules/assertions/linesBeforeBlock.js @@ -161,6 +161,110 @@ export default { */ `, }, + { + code: ` + { + /** + * Description. + */ + let value; + } + `, + errors: [ + { + line: 3, + message: 'Required 1 line(s) before JSDoc block' + } + ], + options: [{ checkBlockStarts: true }], + output: ` + { + + /** + * Description. + */ + let value; + } + `, + }, + { + code: ` + class MyClass { + /** + * Description. + */ + method() {} + } + `, + errors: [ + { + line: 3, + message: 'Required 1 line(s) before JSDoc block' + } + ], + options: [{ checkBlockStarts: true }], + output: ` + class MyClass { + + /** + * Description. + */ + method() {} + } + `, + }, + { + code: ` + function myFunction() { + /** + * Description. + */ + let value; + } + `, + errors: [ + { + line: 3, + message: 'Required 1 line(s) before JSDoc block' + } + ], + options: [{ checkBlockStarts: true }], + output: ` + function myFunction() { + + /** + * Description. + */ + let value; + } + `, + }, + { + code: ` + const values = [ + /** + * Description. + */ + value, + ]; + `, + errors: [ + { + line: 3, + message: 'Required 1 line(s) before JSDoc block' + } + ], + options: [{ checkBlockStarts: true }], + output: ` + const values = [ + + /** + * Description. + */ + value, + ]; + `, + } ], valid: [ { @@ -242,5 +346,35 @@ export default { } ] }, + { + code: ` + { + /** + * Description. + */ + let value; + } + `, + }, + { + code: ` + class MyClass { + /** + * Description. + */ + method() {} + } + `, + }, + { + code: ` + function myFunction() { + /** + * Description. + */ + let value; + } + `, + } ], };