feat(no-blank-blocks): add new rule; fixes #1042

Author: brettz9

.README/README.md

@@ -608,6 +608,7 @@ selector).
 {"gitdown": "include", "file": "./rules/multiline-blocks.md"}
 {"gitdown": "include", "file": "./rules/no-bad-blocks.md"}
 {"gitdown": "include", "file": "./rules/no-blank-block-descriptions.md"}
+{"gitdown": "include", "file": "./rules/no-blank-blocks.md"}
 {"gitdown": "include", "file": "./rules/no-defaults.md"}
 {"gitdown": "include", "file": "./rules/no-missing-syntax.md"}
 {"gitdown": "include", "file": "./rules/no-multi-asterisks.md"}

.README/rules/no-blank-blocks.md

@@ -0,0 +1,19 @@
+### `no-blank-blocks`
+
+Reports and optionally removes blocks with whitespace only.
+
+#### Options
+
+##### `enableFixer`
+
+Whether or not to auto-remove the blank block. Defaults to `false`.
+
+|||
+|---|---|
+|Context|everywhere|
+|Tags|N/A|
+|Recommended|false|
+|Settings||
+|Options|`enableFixer`|
+
+<!-- assertions noBlankBlocks -->

README.md

@@ -17,6 +17,7 @@ import matchName from './rules/matchName';
 import multilineBlocks from './rules/multilineBlocks';
 import noBadBlocks from './rules/noBadBlocks';
 import noBlankBlockDescriptions from './rules/noBlankBlockDescriptions';
+import noBlankBlocks from './rules/noBlankBlocks';
 import noDefaults from './rules/noDefaults';
 import noMissingSyntax from './rules/noMissingSyntax';
 import noMultiAsterisks from './rules/noMultiAsterisks';
@@ -72,6 +73,7 @@ const index = {
     'multiline-blocks': multilineBlocks,
     'no-bad-blocks': noBadBlocks,
     'no-blank-block-descriptions': noBlankBlockDescriptions,
+    'no-blank-blocks': noBlankBlocks,
     'no-defaults': noDefaults,
     'no-missing-syntax': noMissingSyntax,
     'no-multi-asterisks': noMultiAsterisks,
@@ -132,6 +134,7 @@ const createRecommendedRuleset = (warnOrError) => {
       'jsdoc/multiline-blocks': warnOrError,
       'jsdoc/no-bad-blocks': 'off',
       'jsdoc/no-blank-block-descriptions': 'off',
+      'jsdoc/no-blank-blocks': 'off',
       'jsdoc/no-defaults': 'off',
       'jsdoc/no-missing-syntax': 'off',
       'jsdoc/no-multi-asterisks': warnOrError,

src/index.js

@@ -0,0 +1,53 @@
+import iterateJsdoc from '../iterateJsdoc';
+
+export default iterateJsdoc(({
+  context,
+  jsdoc,
+  utils,
+}) => {
+  if (jsdoc.tags.length) {
+    return;
+  }
+
+  const {
+    description,
+    lastDescriptionLine,
+  } = utils.getDescription();
+  if (description.trim()) {
+    return;
+  }
+
+  const {
+    enableFixer,
+  } = context.options[0] || {};
+
+  utils.reportJSDoc(
+    'No empty blocks',
+    {
+      line: lastDescriptionLine,
+    },
+    enableFixer ? () => {
+      jsdoc.source.splice(0, jsdoc.source.length);
+    } : null,
+  );
+}, {
+  iterateAllJsdocs: true,
+  meta: {
+    docs: {
+      description: 'Removes empty blocks with nothing but possibly line breaks',
+      url: 'https://github.com/gajus/eslint-plugin-jsdoc#eslint-plugin-jsdoc-rules-no-blank-blocks',
+    },
+    fixable: 'code',
+    schema: [
+      {
+        additionalProperties: false,
+        properties: {
+          enableFixer: {
+            type: 'boolean',
+          },
+        },
+      },
+    ],
+    type: 'suggestion',
+  },
+});

src/rules/noBlankBlocks.js

@@ -0,0 +1,136 @@
+export default {
+  invalid: [
+    {
+      code: `
+        /** */
+      `,
+      errors: [
+        {
+          line: 2,
+          message: 'No empty blocks',
+        },
+      ],
+      options: [
+        {
+          enableFixer: true,
+        },
+      ],
+      output: `
+      `,
+    },
+    {
+      code: `
+        /**
+         */
+      `,
+      errors: [
+        {
+          line: 2,
+          message: 'No empty blocks',
+        },
+      ],
+      options: [
+        {
+          enableFixer: true,
+        },
+      ],
+      output: `
+      `,
+    },
+    {
+      code: `
+        /**
+         *
+         */
+      `,
+      errors: [
+        {
+          line: 3,
+          message: 'No empty blocks',
+        },
+      ],
+      options: [
+        {
+          enableFixer: true,
+        },
+      ],
+      output: `
+      `,
+    },
+    {
+      code: `
+        /**
+         *
+         *
+         */
+      `,
+      errors: [
+        {
+          line: 4,
+          message: 'No empty blocks',
+        },
+      ],
+      options: [
+        {
+          enableFixer: true,
+        },
+      ],
+      output: `
+      `,
+    },
+    {
+      code: `
+        /**
+         *
+         *
+         */
+      `,
+      errors: [
+        {
+          line: 4,
+          message: 'No empty blocks',
+        },
+      ],
+      options: [
+        {
+          enableFixer: false,
+        },
+      ],
+    },
+    {
+      code: `
+        /**
+         *
+         *
+         */
+      `,
+      errors: [
+        {
+          line: 4,
+          message: 'No empty blocks',
+        },
+      ],
+    },
+  ],
+  valid: [
+    {
+      code: `
+        /** @tag */
+      `,
+    },
+    {
+      code: `
+        /**
+         * Text
+         */
+      `,
+    },
+    {
+      code: `
+        /**
+         * @tag
+         */
+      `,
+    },
+  ],
+};

test/rules/assertions/noBlankBlocks.js

@@ -18,6 +18,7 @@
   "multiline-blocks",
   "no-bad-blocks",
   "no-blank-block-descriptions",
+  "no-blank-blocks",
   "no-defaults",
   "no-missing-syntax",
   "no-multi-asterisks",