fp docs - Remove notes about mutation in description.

lib/doc/apply-fp-mapping/description.js

@@ -0,0 +1,39 @@
+var _ = require('lodash'),
+    j = require('jscodeshift'),
+    Entry = require('docdown/lib/entry'),
+    common = require('./common');
+
+var baseGetDesc = Entry.prototype.getDesc;
+
+var lineBreaksRegex = /<br\/?>\n?$/g;
+
+/**
+ * Return the `description` of the entry, only without the possible note about mutation.
+ *
+ * @returns {Function} Updated description.
+ */
+function getReorderedExample() {
+  var lines = baseGetDesc.call(this).split('\n');
+
+  var indexOfLine = _.findIndex(lines, function(line) {
+    return _.includes(line, 'mutate');
+  });
+
+  if (indexOfLine === -1) {
+    return lines.join('\n');
+  }
+
+  var linesToDelete = 1;
+  while (indexOfLine + linesToDelete < lines.length &&
+         !lines[indexOfLine + linesToDelete].startsWith('<br')) {
+    linesToDelete++;
+  }
+  lines.splice(indexOfLine, linesToDelete);
+
+  while (_.last(lines).startsWith('<br')) {
+    lines = _.initial(lines);
+  }
+  return lines.join('\n');
+}
+
+module.exports = getReorderedExample;

lib/doc/apply-fp-mapping/index.js

@@ -1,4 +1,5 @@
 var Entry = require('docdown/lib/entry'),
+    getUpdatedDesc = require('./description'),
     getReorderedParams = require('./parameters'),
     getReorderedExample = require('./example');
 
@@ -6,6 +7,7 @@ var Entry = require('docdown/lib/entry'),
  * Updates `docdown` `Entry`'s prototype so that parameters/arguments are reordered according to `mapping`.
  */
 module.exports = function applyFPMapping(mapping) {
+  Entry.prototype.getDesc = getUpdatedDesc;
   Entry.prototype.getParams = getReorderedParams(mapping);
   Entry.prototype.getExample = getReorderedExample(mapping);
 };

test/test-fp-doc.js

@@ -38,6 +38,10 @@
 
   /*--------------------------------------------------------------------------*/
 
+  function toCommentLine(line) {
+    return ' * ' + line;
+  }
+
   function toEntry(name, paramLines, exampleLines, attachedToPrototype) {
     var start = [
       '/**',
@@ -55,9 +59,7 @@
     var params = paramLines.map(function(line) {
       return ' * @param ' + line;
     });
-    var example = (exampleLines || []).map(function(line) {
+    var example = (exampleLines || []).map(toCommentLine);
-      return ' * ' + line;
-    });
 
     return [].concat(start, staticLine, params, [' * @example'], example, end).join('\n');
   }
@@ -498,6 +500,76 @@
     });
   }());
 
+  /*--------------------------------------------------------------------------*/
+
+  QUnit.module('getDesc');
+
+  (function() {
+    function toSourceWithDescription(name, description) {
+      var start = [
+        '/**',
+        ' * '
+      ];
+
+      var end = [
+        ' * @static',
+        ' * ',
+        ' */',
+        'function ' + name + '(a, b, c) {',
+        '',
+        '}'
+      ];
+
+      var descriptionLines = description.map(toCommentLine);
+      return [].concat(start, descriptionLines, end).join('\n');
+    }
+
+    QUnit.test('should remove notes about mutators arguments and remove default values', function(assert) {
+      assert.expect(1);
+
+      var example = toSourceWithDescription('pullAt', [
+        'Removes elements from `array` corresponding to `indexes` and returns an',
+        'array of removed elements.',
+        '',
+        '**Note:** Unlike `_.at`, this method mutates `array`.',
+        ''
+      ]);
+
+      var entry = new Entry(example, example);
+
+      var actual = entry.getDesc();
+
+      assert.equal(actual, [
+        'Removes elements from `array` corresponding to `indexes` and returns an',
+        'array of removed elements.'
+      ].join('\n'));
+    });
+
+    QUnit.test('should remove following related lines', function(assert) {
+      assert.expect(1);
+
+      var example = toSourceWithDescription('assign', [
+        'Assigns own enumerable properties of source objects to the destination',
+        'object. Source objects are applied from left to right. Subsequent sources',
+        'overwrite property assignments of previous sources.',
+        '',
+        '**Note:** This method mutates `object` and is loosely based on',
+        '[`Object.assign`](https://mdn.io/Object/assign).',
+        ''
+      ]);
+
+      var entry = new Entry(example, example);
+
+      var actual = entry.getDesc();
+
+      assert.equal(actual, [
+        'Assigns own enumerable properties of source objects to the destination',
+        'object. Source objects are applied from left to right. Subsequent sources',
+        'overwrite property assignments of previous sources.',
+      ].join('\n'));
+    });
+  }());
+
   QUnit.config.asyncRetries = 10;
   QUnit.config.hidepassed = true;