Merge branch 'example-trim-option' into 'master'

Add option to keep unparseable example indent

See merge request !3

jsdoc_parser.js

@@ -218,7 +218,8 @@ function jsdocParser(text, parsers, options) {
             tagString += formatedDescription.replace(/(^|\n)/g, '\n *   ')
             tagString = tagString.slice(0, tagString.length - 6)
           } catch (err) {
-            tagString += '\n' + tag.description.split('\n').map(l => ' *   ' + l.trim()).join('\n')
+            tagString += '\n' + tag.description
+              .split('\n').map(l => ` *   ${options.jsdocKeepUnparseableExampleIndent ? l : l.trim()}`).join('\n')
           }
         }
 
@@ -301,6 +302,12 @@ module.exports = {
       category: 'jsdoc',
       default: false,
       description: 'Should tags, types, names and description be aligned',
+    },
+    jsdocKeepUnparseableExampleIndent: {
+      type: 'boolean',
+      category: 'jsdoc',
+      default: false,
+      description: 'Should unparseable esample (pseudo code or no js code) keep its indentation',
     }
   },
   defaultOptions: {
@@ -309,5 +316,6 @@ module.exports = {
     jsdocDescriptionWithDot: false,
     jsdocDescriptionTag: true,
     jsdocVerticalAlignment: false,
+    jsdocKeepUnparseableExampleIndent: false,
   }
 }

tests/main.js

@@ -325,3 +325,132 @@ test('yields should work like return tag', () => {
   expect(Result4).toEqual(Expected4)
   expect(Result5).toEqual(Expected5)
 })
+
+test('should trim whitespace on unparseable examples - default options', () => {
+  const Result1 = subject(`/**
+ * @example
+ * {
+ *   testArr: [
+ *     1,
+ *     2,
+ *     ...
+ *   ]
+ * }
+ */`)
+  const Expected1 = `/**
+ * @example
+ *   {
+ *   testArr: [
+ *   1,
+ *   2,
+ *   ...
+ *   ]
+ *   }
+ */
+`
+
+  const Result2 = subject(`/**
+ * @example
+ * // sample call:
+ * foo(bar)
+ *
+ * // result
+ * [{
+ *   foo: 1,
+ *   foo: 2,
+ *   ...,
+ *   foo: 9,
+ * }, {
+ *   bar: 1,
+ *   ...,
+ *   bar: 5
+ * }]
+ */`)
+  const Expected2 = `/**
+ * @example
+ *   // sample call:
+ *   foo(bar)
+ *
+ *   // result
+ *   [{
+ *   foo: 1,
+ *   foo: 2,
+ *   ...,
+ *   foo: 9,
+ *   }, {
+ *   bar: 1,
+ *   ...,
+ *   bar: 5
+ *   }]
+ */
+`
+
+  expect(Result1).toEqual(Expected1)
+  expect(Result2).toEqual(Expected2)
+})
+
+test('should keep indent on unparseable examples - if flag set to true', () => {
+  const options = {
+    jsdocKeepUnparseableExampleIndent: true,
+  }
+  const Result1 = subject(`/**
+ * @example
+ * {
+ *   testArr: [
+ *     1,
+ *     2,
+ *     ...
+ *   ]
+ * }
+ */`, options)
+  const Expected1 = `/**
+ * @example
+ *   {
+ *     testArr: [
+ *       1,
+ *       2,
+ *       ...
+ *     ]
+ *   }
+ */
+`
+
+  const Result2 = subject(`/**
+ * @example
+ * // sample call:
+ * foo(bar)
+ *
+ * // result
+ * [{
+ *   foo: 1,
+ *   foo: 2,
+ *   ...,
+ *   foo: 9,
+ * }, {
+ *   bar: 1,
+ *   ...,
+ *   bar: 5
+ * }]
+ */`, options)
+  const Expected2 = `/**
+ * @example
+ *   // sample call:
+ *   foo(bar)
+ *
+ *   // result
+ *   [{
+ *     foo: 1,
+ *     foo: 2,
+ *     ...,
+ *     foo: 9,
+ *   }, {
+ *     bar: 1,
+ *     ...,
+ *     bar: 5
+ *   }]
+ */
+`
+
+  expect(Result1).toEqual(Expected1)
+  expect(Result2).toEqual(Expected2)
+})