fix(check-indentation): #334 - ignore content enclosed in "code blocks"

Author: ahwayakchih

.README/rules/check-indentation.md

@@ -2,6 +2,20 @@
 
 Reports invalid padding inside JSDoc block.
 
+Ignores parts enclosed in Markdown's "code block". For example,
+following description is valid:
+
+```js
+/**
+ * Some description:
+ * ```html
+ * <section>
+ *   <title>test</title>
+ * </section>
+ * ```
+ */
+```
+
 #### Options
 
 This rule has an object option.

README.md

@@ -835,6 +835,20 @@ function quux () {}
 
 Reports invalid padding inside JSDoc block.
 
+Ignores parts enclosed in Markdown's "code block". For example,
+following description is valid:
+
+```js
+/**
+ * Some description:
+ * ```html
+ * <section>
+ *   <title>test</title>
+ * </section>
+ * ```
+ */
+```
+
 <a name="eslint-plugin-jsdoc-rules-check-indentation-options-1"></a>
 #### Options
 
@@ -920,6 +934,32 @@ function quux () {
  */
 function quux () {
 
+}
+// Message: There must be no indentation.
+
+/**
+ * foo
+ * ```html
+ * <section>
+ *   <title>test</title>
+ * </section>
+ * ```
+ * @returns
+ *   eeee
+ */
+function quux () {
+
+}
+// Message: There must be no indentation.
+
+/**
+ * foo
+ * ```   aaaa```
+ * @returns
+ *   eeee
+ */
+function quux () {
+
 }
 // Message: There must be no indentation.
 ````
@@ -968,6 +1008,28 @@ function quux () {
 
 }
 // Options: [{"excludeTags":["example","returns"]}]
+
+/**
+ * foo
+ * ```html
+ * <section>
+ *   <title>test</title>
+ * </section>
+ * ```
+ * @returns eeee
+ */
+function quux () {
+
+}
+
+/**
+ * foo
+ * ```   aaaa```
+ * @returns eeee
+ */
+function quux () {
+
+}
 ````
 
 

src/rules/checkIndentation.js

@@ -8,6 +8,14 @@ const maskExcludedContent = (str, excludeTags) => {
   });
 };
 
+const maskCodeBlocks = (str) => {
+  const regContent = /([ \t]+\*)[ \t]```[^\n]*?([\w|\W]*?\n)(?=[ \t]*\*(?:[ \t]*(?:```|@)|\/))/g;
+
+  return str.replace(regContent, (match, margin, code) => {
+    return (new Array(code.match(/\n/g).length + 1)).join(margin + '\n');
+  });
+};
+
 export default iterateJsdoc(({
   sourceCode,
   jsdocNode,
@@ -20,7 +28,8 @@ export default iterateJsdoc(({
   } = options;
 
   const reg = new RegExp(/^(?:\/?\**|[ \t]*)\*[ \t]{2}/gm);
-  const text = excludeTags.length ? maskExcludedContent(sourceCode.getText(jsdocNode), excludeTags) : sourceCode.getText(jsdocNode);
+  const textWithoutCodeBlocks = maskCodeBlocks(sourceCode.getText(jsdocNode));
+  const text = excludeTags.length ? maskExcludedContent(textWithoutCodeBlocks, excludeTags) : textWithoutCodeBlocks;
 
   if (reg.test(text)) {
     const lineBreaks = text.slice(0, reg.lastIndex).match(/\n/g) || [];

test/rules/assertions/checkIndentation.js

@@ -93,6 +93,48 @@ export default {
         },
       ],
     },
+    {
+      code: `
+          /**
+           * foo
+           * \`\`\`html
+           * <section>
+           *   <title>test</title>
+           * </section>
+           * \`\`\`
+           * @returns
+           *   eeee
+           */
+          function quux () {
+
+          }
+      `,
+      errors: [
+        {
+          line: 10,
+          message: 'There must be no indentation.',
+        },
+      ],
+    },
+    {
+      code: `
+          /**
+           * foo
+           * \`\`\`   aaaa\`\`\`
+           * @returns
+           *   eeee
+           */
+          function quux () {
+
+          }
+      `,
+      errors: [
+        {
+          line: 6,
+          message: 'There must be no indentation.',
+        },
+      ],
+    },
   ],
   valid: [
     {
@@ -151,5 +193,33 @@ export default {
         excludeTags: ['example', 'returns'],
       }],
     },
+    {
+      code: `
+          /**
+           * foo
+           * \`\`\`html
+           * <section>
+           *   <title>test</title>
+           * </section>
+           * \`\`\`
+           * @returns eeee
+           */
+          function quux () {
+
+          }
+      `,
+    },
+    {
+      code: `
+          /**
+           * foo
+           * \`\`\`   aaaa\`\`\`
+           * @returns eeee
+           */
+          function quux () {
+
+          }
+      `,
+    },
   ],
 };