feat(check-examples): add paddedIndent option

gajus · Jul 13, 2019 · 4c11c39 · 4c11c39
1 parent cea3560
commit 4c11c39
Show file tree

Hide file tree

Showing 3 changed files with 52 additions and 0 deletions.
diff --git a/.README/rules/check-examples.md b/.README/rules/check-examples.md
@@ -37,6 +37,24 @@ If neither is in use, all examples will be matched. Note also that even if
 `captionRequired` is not set, any initial `<caption>` will be stripped out
 before doing the regex matching.
 
+#### `paddedIndent`
+
+This integer property allows one to add a fixed amount of whitespace at the
+beginning of the second or later lines of the example to be stripped so as
+to avoid linting issues with the decorative whitespace. For example, if set
+to a value of `4`, the initial whitespace below will not trigger `indent`
+rule errors as the extra 4 spaces on each subsequent line will be stripped
+out before evaluation.
+
+```js
+/**
+ * @example
+ *     anArray.filter((a) => {
+ *      return a.b;
+ *     });
+ */
+```
+
 #### `reportUnusedDisableDirectives`
 
 If not set to `false`, `reportUnusedDisableDirectives` will report disabled

diff --git a/src/rules/checkExamples.js b/src/rules/checkExamples.js
@@ -29,6 +29,7 @@ export default iterateJsdoc(({
     noDefaultExampleRules = false,
     eslintrcForExamples = true,
     matchingFileName: filename = null,
+    paddedIndent = 0,
     baseConfig = {},
     configFile,
     allowInlineConfig = true,
@@ -150,6 +151,10 @@ export default iterateJsdoc(({
 
     let messages;
 
+    if (paddedIndent) {
+      source = source.replace(new RegExp(`(^|\n) {${paddedIndent}}(?!$)`, 'g'), '\n');
+    }
+
     if (filename) {
       const config = cli.getConfigForFile(filename);
 
@@ -258,6 +263,10 @@ export default iterateJsdoc(({
             default: false,
             type: 'boolean'
           },
+          paddedIndent: {
+            default: 0,
+            type: 'integer'
+          },
           rejectExampleCodeRegex: {
             type: 'string'
           },

diff --git a/test/rules/assertions/checkExamples.js b/test/rules/assertions/checkExamples.js
@@ -328,6 +328,31 @@ export default {
       code: `
           /**
            * @example const i = 5;
+           *   quux2()
+           */
+          function quux2 () {
+
+          }
+      `,
+      errors: [
+        {
+          message: '@example warning (id-length): Identifier name \'i\' is too short (< 2).'
+        },
+        {
+          message: '@example error (semi): Missing semicolon.'
+        }
+      ],
+      options: [
+        {
+          paddedIndent: 2
+        }
+      ]
+    },
+    {
+      code: `
+          /**
+           * @example
+           * const i = 5;
            * quux2()
            */
           function quux2 () {