Add docs for transform. Closes #1134

2 files changed, 50 insertions, 5 deletions

diff --git a/README.md b/README.md
index 41107ae..80567f4 100644
--- a/README.md
+++ b/README.md
@@ -221,6 +221,7 @@ Some functions are also available in the following forms:
 * [`filter`](#filter), `filterSeries`, `filterLimit`
 * [`reject`](#reject), `rejectSeries`, `rejectLimit`
 * [`reduce`](#reduce), [`reduceRight`](#reduceRight)
+* [`transform`](#transform)
 * [`detect`](#detect), `detectSeries`, `detectLimit`
 * [`sortBy`](#sortBy)
 * [`some`](#some), `someLimit`, `someSeries`
diff --git a/lib/transform.js b/lib/transform.js
index 819cd5d..cdad526 100644
--- a/lib/transform.js
+++ b/lib/transform.js
@@ -4,16 +4,60 @@ import isArray from 'lodash/isArray';
 
 import eachOf from './eachOf';
 
-export default function transform (arr, memo, iteratee, callback) {
+/**
+ * A relative of `reduce`.  Takes an Object or Array, and iterates over each
+ * element in series, each step potentially mutating an `accumulator` value.
+ * The type of the accumulator defaults to the type of collection passed in.
+ *
+ * @name transform
+ * @static
+ * @memberOf async
+ * @category Collection
+ * @param {Array|Object} coll - A collection to iterate over.
+ * @param {*} [accumulator] - The initial state of the transform.  If omitted,
+ * it will default to an empty Object or Array, depending on the type of `coll`
+ * @param {Function} iteratee - A function applied to each item in the
+ * collection that potentially modifies the accumulator. The `iteratee` is
+ * passed a `callback(err)` which accepts an optional error as its first
+ * argument. If an error is passed to the callback, the transform is stopped
+ * and the main `callback` is immediately called with the error.
+ * Invoked with (accumulator, item, key, callback).
+ * @param {Function} [callback] - A callback which is called after all the
+ * `iteratee` functions have finished. Result is the transformed accumulator.
+ * Invoked with (err, result).
+ * @example
+ *
+ * async.transform([1,2,3], function(acc, item, index, callback) {
+ *     // pointless async:
+ *     process.nextTick(function() {
+ *         acc.push(item * 2)
+ *         callback(null)
+ *     });
+ * }, function(err, result) {
+ *     // result is now equal to [2, 4, 6]
+ * });
+ *
+ * @example
+ *
+ * async.transform({a: 1, b: 2, c: 3}, function (obj, val, key, callback) {
+ *     setImmediate(function () {
+ *         obj[key] = val * 2;
+ *         callback();
+ *     })
+ * }, function (err, result) {
+ *     // result is equal to {a: 2, b: 4, c: 6}
+ * })
+ */
+export default function transform (arr, acc, iteratee, callback) {
     if (arguments.length === 3) {
         callback = iteratee;
-        iteratee = memo;
-        memo = isArray(arr) ? [] : {};
+        iteratee = acc;
+        acc = isArray(arr) ? [] : {};
     }
 
     eachOf(arr, function(v, k, cb) {
-        iteratee(memo, v, k, cb);
+        iteratee(acc, v, k, cb);
     }, function(err) {
-        callback(err, memo);
+        callback(err, acc);
     });
 }