fix(check-indentation): excludeTags option, add tests, default on

Instead of rather specific `excludeExamples` option, we now have more
generic `excludeTags` option. It takes an array of tag names to exclude
from `check-indentation`, and defaults to `['example']`.

Added test suggested by @golopot:
#388 (comment)

Author: ahwayakchih

.README/rules/check-indentation.md

@@ -6,15 +6,18 @@ Reports invalid padding inside JSDoc block.
 
 This rule has an object option.
 
-##### `excludeExamples`
+##### `excludeTags`
 
-This boolean property allows to "hide" example code from reports.
+Array of tags (e.g., `['example', 'description']`) whose content will be
+"hidden" from the `check-indentation` rule. Defaults to `['example']`.
 
 By default, whole JSDoc block is checked for invalid padding.
-That includes example blocks too, which may get in the way of adding full,
-readable examples of code without ending up with multiple linting issues.
+That would include `@example` blocks too, which would get in the way
+of adding full, readable examples of code without ending up with multiple
+linting issues.
 
-When enabled, following code will lint without any padding issue:
+When disabled (by passing `excludeTags: []` option), following code will
+lint *with* padding issue:
 
 ```js
 /**
@@ -29,6 +32,6 @@ When enabled, following code will lint without any padding issue:
 |---|---|
 |Context|everywhere|
 |Tags|N/A|
-|Options| `excludeExamples` |
+|Options| `excludeTags` |
 
 <!-- assertions checkIndentation -->

README.md

@@ -840,16 +840,19 @@ Reports invalid padding inside JSDoc block.
 
 This rule has an object option.
 
-<a name="eslint-plugin-jsdoc-rules-check-indentation-options-1-excludeexamples"></a>
-##### <code>excludeExamples</code>
+<a name="eslint-plugin-jsdoc-rules-check-indentation-options-1-excludetags"></a>
+##### <code>excludeTags</code>
 
-This boolean property allows to "hide" example code from reports.
+Array of tags (e.g., `['example', 'description']`) whose content will be
+"hidden" from the `check-indentation` rule. Defaults to `['example']`.
 
 By default, whole JSDoc block is checked for invalid padding.
-That includes example blocks too, which may get in the way of adding full,
-readable examples of code without ending up with multiple linting issues.
+That would include `@example` blocks too, which would get in the way
+of adding full, readable examples of code without ending up with multiple
+linting issues.
 
-When enabled, following code will lint without any padding issue:
+When disabled (by passing `excludeTags: []` option), following code will
+lint *with* padding issue:
 
 ```js
 /**
@@ -864,7 +867,7 @@ When enabled, following code will lint without any padding issue:
 |---|---|
 |Context|everywhere|
 |Tags|N/A|
-|Options| `excludeExamples` |
+|Options| `excludeTags` |
 
 The following patterns are considered problems:
 
@@ -903,6 +906,20 @@ class Moo {}
  */
 function quux () {
 
+}
+// Options: [{"excludeTags":[]}]
+// Message: There must be no indentation.
+
+/**
+ * foo
+ *
+ * @example
+ *   aaaa
+ * @returns
+ *   eeee
+ */
+function quux () {
+
 }
 // Message: There must be no indentation.
 ````
@@ -936,7 +953,21 @@ function quux () {
 function quux () {
 
 }
-// Options: [{"excludeExamples":true}]
+
+/**
+ * foo
+ *
+ * @example
+ * anArray.filter((a) => {
+ *   return a.b;
+ * });
+ * @returns
+ *   eeee
+ */
+function quux () {
+
+}
+// Options: [{"excludeTags":["example","returns"]}]
 ````
 
 

src/rules/checkIndentation.js

@@ -1,7 +1,7 @@
 import iterateJsdoc from '../iterateJsdoc';
 
-const maskExamples = (str) => {
-  const regExamples = /([ \t]+\*)[ \t]@example(?=[ \n])([\w|\W]*?\n)(?=[ \t]*\*(?:[ \t]*@|\/))/g;
+const maskExamples = (str, excludeTags) => {
+  const regExamples = new RegExp(`([ \\t]+\\*)[ \\t]@(?:${excludeTags.join('|')})(?=[ \\n])([\\w|\\W]*?\\n)(?=[ \\t]*\\*(?:[ \\t]*@|\\/))`,'g');
 
   return str.replace(regExamples, (match, margin, code) => {
     return (new Array(code.match(/\n/g).length + 1)).join(margin + '\n');
@@ -16,11 +16,11 @@ export default iterateJsdoc(({
 }) => {
   const options = context.options[0] || {};
   const {
-    excludeExamples = false,
+    excludeTags = ['example'],
   } = options;
 
   const reg = new RegExp(/^(?:\/?\**|[ \t]*)\*[ \t]{2}/gm);
-  const text = excludeExamples ? maskExamples(sourceCode.getText(jsdocNode)) : sourceCode.getText(jsdocNode);
+  const text = excludeTags.length ? maskExamples(sourceCode.getText(jsdocNode), excludeTags) : sourceCode.getText(jsdocNode);
 
   if (reg.test(text)) {
     const lineBreaks = text.slice(0, reg.lastIndex).match(/\n/g) || [];
@@ -34,9 +34,11 @@ export default iterateJsdoc(({
     schema: [{
       additionalProperties: false,
       properties: {
-        excludeExamples: {
-          default: false,
-          type: 'boolean',
+        excludeTags: {
+          items: {
+            type: 'string',
+          },
+          type: 'array',
         },
       },
       type: 'object',

test/rules/assertions/checkIndentation.js

@@ -68,6 +68,30 @@ export default {
           message: 'There must be no indentation.',
         },
       ],
+      options: [{
+        excludeTags: [],
+      }],
+    },
+    {
+      code: `
+          /**
+           * foo
+           *
+           * @example
+           *   aaaa
+           * @returns
+           *   eeee
+           */
+          function quux () {
+
+          }
+      `,
+      errors: [
+        {
+          line: 8,
+          message: 'There must be no indentation.',
+        },
+      ],
     },
   ],
   valid: [
@@ -104,10 +128,27 @@ export default {
            */
           function quux () {
 
+          }
+      `,
+    },
+    {
+      code: `
+          /**
+           * foo
+           *
+           * @example
+           * anArray.filter((a) => {
+           *   return a.b;
+           * });
+           * @returns
+           *   eeee
+           */
+          function quux () {
+
           }
       `,
       options: [{
-        excludeExamples: true,
+        excludeTags: ['example', 'returns'],
       }],
     },
   ],