fix(check-indentation): ignore example code blocks

This adds an `excludeExamples` option, defaulting to `true`.
When enabled (or not configured) it will mask all `@example` tags
and their content before testing indentation.
That prevents errors about indentation inside example code
blocks and keeps correct line numbers when reporting indentation error
found elsewhere.

It should fix gajus#334.

Author: ahwayakchih

README.md

@@ -866,6 +866,20 @@ function quux () {
  */
 class Moo {}
 // Message: There must be no indentation.
+
+/**
+ * foo
+ *
+ * @example
+ * function xFoo () {
+ *   return 'foo';
+ * }
+ */
+function quux () {
+
+}
+// Options: ["excludeExamples":false}]
+// Message: There must be no indentation.
 ````
 
 The following patterns are not considered problems:
@@ -885,6 +899,19 @@ function quux () {
 function quux () {
 
 }
+
+/**
+ * foo
+ *
+ * @example
+ * function xFoo () {
+ *   return 'foo';
+ * }
+ */
+function quux () {
+
+}
+// Options: ["excludeExamples":true}]
 ````
 
 

src/rules/checkIndentation.js

@@ -1,12 +1,25 @@
 import iterateJsdoc from '../iterateJsdoc';
 
+const maskExamples = (str) => {
+  const regExamples = /([ \t]+\*)[ \t]@example(?=[ \n])([\w|\W]*?\n)(?=[ \t]*\*(?:[ \t]*@|\/))/g;
+  return str.replace(regExamples, function hideCode (m, margin, code) {
+    return (new Array(code.match(/\n/g).length + 1)).join(margin + '\n');
+  });
+};
+
 export default iterateJsdoc(({
   sourceCode,
   jsdocNode,
   report,
+  context,
 }) => {
+  const options = context.options[0] || {};
+  const {
+    excludeExamples = true
+  } = options;
+
   const reg = new RegExp(/^(?:\/?\**|[ \t]*)\*[ \t]{2}/gm);
-  const text = sourceCode.getText(jsdocNode);
+  const text = excludeExamples ? maskExamples(sourceCode.getText(jsdocNode)) : sourceCode.getText(jsdocNode);
 
   if (reg.test(text)) {
     const lineBreaks = text.slice(0, reg.lastIndex).match(/\n/g) || [];
@@ -17,6 +30,16 @@ export default iterateJsdoc(({
 }, {
   iterateAllJsdocs: true,
   meta: {
+    schema: [{
+      additionalProperties: false,
+      properties: {
+        excludeExamples: {
+          default: true,
+          type: 'boolean'
+        },
+      },
+      type: 'object'
+    }],
     type: 'layout',
   },
 });

test/rules/assertions/checkIndentation.js

@@ -48,6 +48,30 @@ export default {
         },
       ],
     },
+    {
+      code: `
+          /**
+           * foo
+           *
+           * @example
+           * function xFoo () {
+           *   return 'foo';
+           * }
+           */
+          function quux () {
+
+          }
+      `,
+      errors: [
+        {
+          line: 7,
+          message: 'There must be no indentation.',
+        },
+      ],
+      options: [{
+        excludeExamples: false,
+      }],
+    },
   ],
   valid: [
     {
@@ -71,5 +95,23 @@ export default {
           }
       `,
     },
+    {
+      code: `
+          /**
+           * foo
+           *
+           * @example
+           * function xFoo () {
+           *   return 'foo';
+           * }
+           */
+          function quux () {
+
+          }
+      `,
+      options: [{
+        excludeExamples: true,
+      }],
+    },
   ],
 };