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 #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,
+      }],
+    },
   ],
 };