update minified build

1 files changed, 2257 insertions, 57 deletions

diff --git a/dist/async.js b/dist/async.js
index 2062bea..02b0295 100644
--- a/dist/async.js
+++ b/dist/async.js
@@ -362,8 +362,9 @@
     function once(fn) {
         return function () {
             if (fn === null) return;
-            fn.apply(this, arguments);
+            var callFn = fn;
             fn = null;
+            callFn.apply(this, arguments);
         };
     }
 
@@ -801,8 +802,9 @@
     function onlyOnce(fn) {
         return function () {
             if (fn === null) throw new Error("Callback was already called.");
-            fn.apply(this, arguments);
+            var callFn = fn;
             fn = null;
+            callFn.apply(this, arguments);
         };
     }
 
@@ -867,6 +869,24 @@
         });
     }
 
+    /**
+     * The same as `map` but runs a maximum of `limit` async operations at a time.
+     *
+     * @name mapLimit
+     * @static
+     * @memberOf async
+     * @see async.map
+     * @category Collection
+     * @param {Array|Object} coll - A collection to iterate over.
+     * @param {number} limit - The maximum number of async operations at a time.
+     * @param {Function} iteratee - A function to apply to each item in `coll`.
+     * The iteratee is passed a `callback(err, transformed)` which must be called
+     * once it has completed with an error (which can be `null`) and a transformed
+     * item. Invoked with (item, callback).
+     * @param {Function} [callback] - A callback which is called when all `iteratee`
+     * functions have finished, or an error occurs. Results is an array of the
+     * transformed items from the `coll`. Invoked with (err, results).
+     */
     var mapLimit = doParallelLimit(_asyncMap);
 
     function doLimit(fn, limit) {
@@ -875,20 +895,213 @@
         };
     }
 
+    /**
+     * Produces a new collection of values by mapping each value in `coll` through
+     * the `iteratee` function. The `iteratee` is called with an item from `coll`
+     * and a callback for when it has finished processing. Each of these callback
+     * takes 2 arguments: an `error`, and the transformed item from `coll`. If
+     * `iteratee` passes an error to its callback, the main `callback` (for the
+     * `map` function) is immediately called with the error.
+     *
+     * Note, that since this function applies the `iteratee` to each item in
+     * parallel, there is no guarantee that the `iteratee` functions will complete
+     * in order. However, the results array will be in the same order as the
+     * original `coll`.
+     *
+     * @name map
+     * @static
+     * @memberOf async
+     * @category Collection
+     * @param {Array|Object} coll - A collection to iterate over.
+     * @param {Function} iteratee - A function to apply to each item in `coll`.
+     * The iteratee is passed a `callback(err, transformed)` which must be called
+     * once it has completed with an error (which can be `null`) and a
+     * transformed item. Invoked with (item, callback).
+     * @param {Function} [callback] - A callback which is called when all `iteratee`
+     * functions have finished, or an error occurs. Results is an array of the
+     * transformed items from the `coll`. Invoked with (err, results).
+     * @example
+     *
+     * async.map(['file1','file2','file3'], fs.stat, function(err, results) {
+     *     // results is now an array of stats for each file
+     * });
+     */
     var map = doLimit(mapLimit, Infinity);
 
+    /**
+     * Applies the provided arguments to each function in the array, calling
+     * `callback` after all functions have completed. If you only provide the first
+     * argument, then it will return a function which lets you pass in the
+     * arguments as if it were a single function call.
+     *
+     * @name applyEach
+     * @static
+     * @memberOf async
+     * @category Control Flow
+     * @param {Array|Object} fns - A collection of asynchronous functions to all
+     * call with the same arguments
+     * @param {...*} [args] - any number of separate arguments to pass to the
+     * function.
+     * @param {Function} [callback] - the final argument should be the callback,
+     * called when all functions have completed processing.
+     * @returns {Function} - If only the first argument is provided, it will return
+     * a function which lets you pass in the arguments as if it were a single
+     * function call.
+     * @example
+     *
+     * async.applyEach([enableSearch, updateSchema], 'bucket', callback);
+     *
+     * // partial application example:
+     * async.each(
+     *     buckets,
+     *     async.applyEach([enableSearch, updateSchema]),
+     *     callback
+     * );
+     */
     var applyEach = applyEach$1(map);
 
+    /**
+     * The same as `map` but runs only a single async operation at a time.
+     *
+     * @name mapSeries
+     * @static
+     * @memberOf async
+     * @see async.map
+     * @category Collection
+     * @param {Array|Object} coll - A collection to iterate over.
+     * @param {Function} iteratee - A function to apply to each item in `coll`.
+     * The iteratee is passed a `callback(err, transformed)` which must be called
+     * once it has completed with an error (which can be `null`) and a
+     * transformed item. Invoked with (item, callback).
+     * @param {Function} [callback] - A callback which is called when all `iteratee`
+     * functions have finished, or an error occurs. Results is an array of the
+     * transformed items from the `coll`. Invoked with (err, results).
+     */
     var mapSeries = doLimit(mapLimit, 1);
 
+    /**
+     * The same as `applyEach` but runs only a single async operation at a time.
+     *
+     * @name applyEachSeries
+     * @static
+     * @memberOf async
+     * @see async.applyEach
+     * @category Control Flow
+     * @param {Array|Object} fns - A collection of asynchronous functions to all
+     * call with the same arguments
+     * @param {...*} [args] - any number of separate arguments to pass to the
+     * function.
+     * @param {Function} [callback] - the final argument should be the callback,
+     * called when all functions have completed processing.
+     * @returns {Function} - If only the first argument is provided, it will return
+     * a function which lets you pass in the arguments as if it were a single
+     * function call.
+     */
     var applyEachSeries = applyEach$1(mapSeries);
 
+    /**
+     * Creates a continuation function with some arguments already applied.
+     *
+     * Useful as a shorthand when combined with other control flow functions. Any
+     * arguments passed to the returned function are added to the arguments
+     * originally passed to apply.
+     *
+     * @name apply
+     * @static
+     * @memberOf async
+     * @category Util
+     * @param {Function} function - The function you want to eventually apply all
+     * arguments to. Invokes with (arguments...).
+     * @param {...*} arguments... - Any number of arguments to automatically apply
+     * when the continuation is called.
+     * @example
+     *
+     * // using apply
+     * async.parallel([
+     *     async.apply(fs.writeFile, 'testfile1', 'test1'),
+     *     async.apply(fs.writeFile, 'testfile2', 'test2')
+     * ]);
+     *
+     *
+     * // the same process without using apply
+     * async.parallel([
+     *     function(callback) {
+     *         fs.writeFile('testfile1', 'test1', callback);
+     *     },
+     *     function(callback) {
+     *         fs.writeFile('testfile2', 'test2', callback);
+     *     }
+     * ]);
+     *
+     * // It's possible to pass any number of additional arguments when calling the
+     * // continuation:
+     *
+     * node> var fn = async.apply(sys.puts, 'one');
+     * node> fn('two', 'three');
+     * one
+     * two
+     * three
+     */
     var apply$1 = rest(function (fn, args) {
         return rest(function (callArgs) {
             return fn.apply(null, args.concat(callArgs));
         });
     });
 
+    /**
+     * Take a sync function and make it async, passing its return value to a
+     * callback. This is useful for plugging sync functions into a waterfall,
+     * series, or other async functions. Any arguments passed to the generated
+     * function will be passed to the wrapped function (except for the final
+     * callback argument). Errors thrown will be passed to the callback.
+     *
+     * If the function passed to `asyncify` returns a Promise, that promises's
+     * resolved/rejected state will be used to call the callback, rather than simply
+     * the synchronous return value.
+     *
+     * This also means you can asyncify ES2016 `async` functions.
+     *
+     * @name asyncify
+     * @static
+     * @memberOf async
+     * @alias wrapSync
+     * @category Util
+     * @param {Function} func - The synchronous function to convert to an
+     * asynchronous function.
+     * @returns {Function} An asynchronous wrapper of the `func`. To be invoked with
+     * (callback).
+     * @example
+     *
+     * // passing a regular synchronous function
+     * async.waterfall([
+     *     async.apply(fs.readFile, filename, "utf8"),
+     *     async.asyncify(JSON.parse),
+     *     function (data, next) {
+     *         // data is the result of parsing the text.
+     *         // If there was a parsing error, it would have been caught.
+     *     }
+     * ], callback);
+     *
+     * // passing a function returning a promise
+     * async.waterfall([
+     *     async.apply(fs.readFile, filename, "utf8"),
+     *     async.asyncify(function (contents) {
+     *         return db.model.create(contents);
+     *     }),
+     *     function (model, next) {
+     *         // `model` is the instantiated model object.
+     *         // If there was an error, this function would be skipped.
+     *     }
+     * ], callback);
+     *
+     * // es6 example
+     * var q = async.queue(async.asyncify(async function(file) {
+     *     var intermediateStep = await processFile(file);
+     *     return await somePromise(intermediateStep)
+     * }));
+     *
+     * q.push(files);
+     */
     function asyncify(func) {
         return initialParams(function (args, callback) {
             var result;
@@ -2766,6 +2979,83 @@
       return -1;
     }
 
+    /**
+     * Determines the best order for running the functions in `tasks`, based on
+     * their requirements. Each function can optionally depend on other functions
+     * being completed first, and each function is run as soon as its requirements
+     * are satisfied.
+     *
+     * If any of the functions pass an error to their callback, the `auto` sequence
+     * will stop. Further tasks will not execute (so any other functions depending
+     * on it will not run), and the main `callback` is immediately called with the
+     * error.
+     *
+     * Functions also receive an object containing the results of functions which
+     * have completed so far as the first argument, if they have dependencies. If a
+     * task function has no dependencies, it will only be passed a callback.
+     *
+     * @name auto
+     * @static
+     * @memberOf async
+     * @category Control Flow
+     * @param {Object} tasks - An object. Each of its properties is either a
+     * function or an array of requirements, with the function itself the last item
+     * in the array. The object's key of a property serves as the name of the task
+     * defined by that property, i.e. can be used when specifying requirements for
+     * other tasks. The function receives one or two arguments:
+     * * a `results` object, containing the results of the previously executed
+     *   functions, only passed if the task has any dependencies,
+     * * a `callback(err, result)` function, which must be called when finished,
+     *   passing an `error` (which can be `null`) and the result of the function's
+     *   execution.
+     * @param {number} [concurrency=Infinity] - An optional `integer` for
+     * determining the maximum number of tasks that can be run in parallel. By
+     * default, as many as possible.
+     * @param {Function} [callback] - An optional callback which is called when all
+     * the tasks have been completed. It receives the `err` argument if any `tasks`
+     * pass an error to their callback. Results are always returned; however, if an
+     * error occurs, no further `tasks` will be performed, and the results object
+     * will only contain partial results. Invoked with (err, results).
+     * @example
+     *
+     * async.auto({
+     *     // this function will just be passed a callback
+     *     readData: async.apply(fs.readFile, 'data.txt', 'utf-8'),
+     *     showData: ['readData', function(results, cb) {
+     *         // results.readData is the file's contents
+     *         // ...
+     *     }]
+     * }, callback);
+     *
+     * async.auto({
+     *     get_data: function(callback) {
+     *         console.log('in get_data');
+     *         // async code to get some data
+     *         callback(null, 'data', 'converted to array');
+     *     },
+     *     make_folder: function(callback) {
+     *         console.log('in make_folder');
+     *         // async code to create a directory to store a file in
+     *         // this is run at the same time as getting the data
+     *         callback(null, 'folder');
+     *     },
+     *     write_file: ['get_data', 'make_folder', function(results, callback) {
+     *         console.log('in write_file', JSON.stringify(results));
+     *         // once there is some data and the directory exists,
+     *         // write the data to a file in the directory
+     *         callback(null, 'filename');
+     *     }],
+     *     email_link: ['write_file', function(results, callback) {
+     *         console.log('in email_link', JSON.stringify(results));
+     *         // once the file is written let's email a link to it...
+     *         // results.write_file contains the filename returned by write_file.
+     *         callback(null, {'file':results.write_file, 'email':'user@example.com'});
+     *     }]
+     * }, function(err, results) {
+     *     console.log('err = ', err);
+     *     console.log('results = ', results);
+     * });
+     */
     function auto (tasks, concurrency, callback) {
         if (typeof concurrency === 'function') {
             // concurrency is optional, shift the args.
@@ -2790,32 +3080,31 @@
 
         var readyTasks = [];
 
+        // for cycle detection:
+        var readyToCheck = []; // tasks that have been identified as reachable
+        // without the possibility of returning to an ancestor task
+        var uncheckedDependencies = {};
+
         forOwn(tasks, function (task, key) {
             if (!isArray(task)) {
                 // no dependencies
                 enqueueTask(key, [task]);
+                readyToCheck.push(key);
                 return;
             }
 
             var dependencies = task.slice(0, task.length - 1);
             var remainingDependencies = dependencies.length;
-
-            checkForDeadlocks();
-
-            function checkForDeadlocks() {
-                var len = dependencies.length;
-                var dep;
-                while (len--) {
-                    if (!(dep = tasks[dependencies[len]])) {
-                        throw new Error('async.auto task `' + key + '` has non-existent dependency in ' + dependencies.join(', '));
-                    }
-                    if (isArray(dep) && baseIndexOf(dep, key, 0) >= 0) {
-                        throw new Error('async.auto task `' + key + '`Has cyclic dependencies');
-                    }
-                }
+            if (!remainingDependencies) {
+                enqueueTask(key, [task]);
+                readyToCheck.push(key);
             }
+            uncheckedDependencies[key] = remainingDependencies;
 
             arrayEach(dependencies, function (dependencyName) {
+                if (!tasks[dependencyName]) {
+                    throw new Error('async.auto task `' + key + '` has a non-existent dependency in ' + dependencies.join(', '));
+                }
                 addListener(dependencyName, function () {
                     remainingDependencies--;
                     if (remainingDependencies === 0) {
@@ -2825,6 +3114,7 @@
             });
         });
 
+        checkForDeadlocks();
         processQueue();
 
         function enqueueTask(key, task) {
@@ -2892,6 +3182,37 @@
                 taskFn(taskCallback);
             }
         }
+
+        function checkForDeadlocks() {
+            // Kahn's algorithm
+            // https://en.wikipedia.org/wiki/Topological_sorting#Kahn.27s_algorithm
+            // http://connalle.blogspot.com/2013/10/topological-sortingkahn-algorithm.html
+            var currentTask;
+            var counter = 0;
+            while (readyToCheck.length) {
+                currentTask = readyToCheck.pop();
+                counter++;
+                arrayEach(getDependents(currentTask), function (dependent) {
+                    if (! --uncheckedDependencies[dependent]) {
+                        readyToCheck.push(dependent);
+                    }
+                });
+            }
+
+            if (counter !== numTasks) {
+                throw new Error('async.auto cannot execute tasks due to a recursive dependency');
+            }
+        }
+
+        function getDependents(taskName) {
+            var result = [];
+            forOwn(tasks, function (task, key) {
+                if (isArray(task) && baseIndexOf(task, taskName, 0) >= 0) {
+                    result.push(key);
+                }
+            });
+            return result;
+        }
     }
 
     /**
@@ -2919,6 +3240,92 @@
         return func.toString().match(argsRegex)[1].split(/\s*\,\s*/);
     }
 
+    /**
+     * A dependency-injected version of the {@link async.auto} function. Dependent
+     * tasks are specified as parameters to the function, after the usual callback
+     * parameter, with the parameter names matching the names of the tasks it
+     * depends on. This can provide even more readable task graphs which can be
+     * easier to maintain.
+     *
+     * If a final callback is specified, the task results are similarly injected,
+     * specified as named parameters after the initial error parameter.
+     *
+     * The autoInject function is purely syntactic sugar and its semantics are
+     * otherwise equivalent to {@link async.auto}.
+     *
+     * @name autoInject
+     * @static
+     * @memberOf async
+     * @see async.auto
+     * @category Control Flow
+     * @param {Object} tasks - An object, each of whose properties is a function of
+     * the form 'func([dependencies...], callback). The object's key of a property
+     * serves as the name of the task defined by that property, i.e. can be used
+     * when specifying requirements for other tasks.
+     * * The `callback` parameter is a `callback(err, result)` which must be called
+     *   when finished, passing an `error` (which can be `null`) and the result of
+     *   the function's execution. The remaining parameters name other tasks on
+     *   which the task is dependent, and the results from those tasks are the
+     *   arguments of those parameters.
+     * @param {Function} [callback] - An optional callback which is called when all
+     * the tasks have been completed. It receives the `err` argument if any `tasks`
+     * pass an error to their callback. The remaining parameters are task names
+     * whose results you are interested in. This callback will only be called when
+     * all tasks have finished or an error has occurred, and so do not specify
+     * dependencies in the same way as `tasks` do. If an error occurs, no further
+     * `tasks` will be performed, and `results` will only be valid for those tasks
+     * which managed to complete. Invoked with (err, [results...]).
+     * @example
+     *
+     * //  The example from `auto` can be rewritten as follows:
+     * async.autoInject({
+     *     get_data: function(callback) {
+     *         // async code to get some data
+     *         callback(null, 'data', 'converted to array');
+     *     },
+     *     make_folder: function(callback) {
+     *         // async code to create a directory to store a file in
+     *         // this is run at the same time as getting the data
+     *         callback(null, 'folder');
+     *     },
+     *     write_file: function(get_data, make_folder, callback) {
+     *         // once there is some data and the directory exists,
+     *         // write the data to a file in the directory
+     *         callback(null, 'filename');
+     *     },
+     *     email_link: function(write_file, callback) {
+     *         // once the file is written let's email a link to it...
+     *         // write_file contains the filename returned by write_file.
+     *         callback(null, {'file':write_file, 'email':'user@example.com'});
+     *     }
+     * }, function(err, email_link) {
+     *     console.log('err = ', err);
+     *     console.log('email_link = ', email_link);
+     * });
+     *
+     * // If you are using a JS minifier that mangles parameter names, `autoInject`
+     * // will not work with plain functions, since the parameter names will be
+     * // collapsed to a single letter identifier.  To work around this, you can
+     * // explicitly specify the names of the parameters your task function needs
+     * // in an array, similar to Angular.js dependency injection.  The final
+     * // results callback can be provided as an array in the same way.
+     *
+     * // This still has an advantage over plain `auto`, since the results a task
+     * // depends on are still spread into arguments.
+     * async.autoInject({
+     *     //...
+     *     write_file: ['get_data', 'make_folder', function(get_data, make_folder, callback) {
+     *         callback(null, 'filename');
+     *     }],
+     *     email_link: ['write_file', function(write_file, callback) {
+     *         callback(null, {'file':write_file, 'email':'user@example.com'});
+     *     }]
+     *     //...
+     * }, ['email_link', function(err, email_link) {
+     *     console.log('err = ', err);
+     *     console.log('email_link = ', email_link);
+     * }]);
+     */
     function autoInject(tasks, callback) {
         var newTasks = {};
 
@@ -2951,23 +3358,7 @@
             }
         });
 
-        auto(newTasks, function (err, results) {
-            var params;
-            if (isArray(callback)) {
-                params = copyArray(callback);
-                callback = params.pop();
-            } else {
-                params = parseParams(callback);
-                params.shift();
-            }
-
-            params = arrayMap(params, function (name) {
-                return results[name];
-            });
-
-            params.unshift(err);
-            callback.apply(null, params);
-        });
+        auto(newTasks, callback);
     }
 
     var _setImmediate = typeof setImmediate === 'function' && setImmediate;
@@ -3126,16 +3517,169 @@
         return q;
     }
 
+    /**
+     * A cargo of tasks for the worker function to complete. Cargo inherits all of
+     * the same methods and event callbacks as {@link async.queue}.
+     * @typedef {Object} cargo
+     * @property {Function} length - A function returning the number of items
+     * waiting to be processed. Invoke with ().
+     * @property {number} payload - An `integer` for determining how many tasks
+     * should be process per round. This property can be changed after a `cargo` is
+     * created to alter the payload on-the-fly.
+     * @property {Function} push - Adds `task` to the `queue`. The callback is
+     * called once the `worker` has finished processing the task. Instead of a
+     * single task, an array of `tasks` can be submitted. The respective callback is
+     * used for every task in the list. Invoke with (task, [callback]).
+     * @property {Function} saturated - A callback that is called when the
+     * `queue.length()` hits the concurrency and further tasks will be queued.
+     * @property {Function} empty - A callback that is called when the last item
+     * from the `queue` is given to a `worker`.
+     * @property {Function} drain - A callback that is called when the last item
+     * from the `queue` has returned from the `worker`.
+     * @property {Function} idle - a function returning false if there are items
+     * waiting or being processed, or true if not. Invoke with ().
+     * @property {Function} pause - a function that pauses the processing of tasks
+     * until `resume()` is called. Invoke with ().
+     * @property {Function} resume - a function that resumes the processing of
+     * queued tasks when the queue is paused. Invoke with ().
+     * @property {Function} kill - a function that removes the `drain` callback and
+     * empties remaining tasks from the queue forcing it to go idle. Invoke with ().
+     */
+
+    /**
+     * Creates a `cargo` object with the specified payload. Tasks added to the
+     * cargo will be processed altogether (up to the `payload` limit). If the
+     * `worker` is in progress, the task is queued until it becomes available. Once
+     * the `worker` has completed some tasks, each callback of those tasks is
+     * called. Check out [these](https://camo.githubusercontent.com/6bbd36f4cf5b35a0f11a96dcd2e97711ffc2fb37/68747470733a2f2f662e636c6f75642e6769746875622e636f6d2f6173736574732f313637363837312f36383130382f62626330636662302d356632392d313165322d393734662d3333393763363464633835382e676966) [animations](https://camo.githubusercontent.com/f4810e00e1c5f5f8addbe3e9f49064fd5d102699/68747470733a2f2f662e636c6f75642e6769746875622e636f6d2f6173736574732f313637363837312f36383130312f38346339323036362d356632392d313165322d383134662d3964336430323431336266642e676966)
+     * for how `cargo` and `queue` work.
+     *
+     * While [queue](#queue) passes only one task to one of a group of workers
+     * at a time, cargo passes an array of tasks to a single worker, repeating
+     * when the worker is finished.
+     *
+     * @name cargo
+     * @static
+     * @memberOf async
+     * @see async.queue
+     * @category Control Flow
+     * @param {Function} worker - An asynchronous function for processing an array
+     * of queued tasks, which must call its `callback(err)` argument when finished,
+     * with an optional `err` argument. Invoked with (tasks, callback).
+     * @param {number} [payload=Infinity] - An optional `integer` for determining
+     * how many tasks should be processed per round; if omitted, the default is
+     * unlimited.
+     * @returns {cargo} A cargo object to manage the tasks. Callbacks can
+     * attached as certain properties to listen for specific events during the
+     * lifecycle of the cargo and inner queue.
+     * @example
+     *
+     * // create a cargo object with payload 2
+     * var cargo = async.cargo(function(tasks, callback) {
+     *     for (var i=0; i<tasks.length; i++) {
+     *         console.log('hello ' + tasks[i].name);
+     *     }
+     *     callback();
+     * }, 2);
+     *
+     * // add some items
+     * cargo.push({name: 'foo'}, function(err) {
+     *     console.log('finished processing foo');
+     * });
+     * cargo.push({name: 'bar'}, function(err) {
+     *     console.log('finished processing bar');
+     * });
+     * cargo.push({name: 'baz'}, function(err) {
+     *     console.log('finished processing baz');
+     * });
+     */
     function cargo(worker, payload) {
-        return queue(worker, 1, payload);
+      return queue(worker, 1, payload);
     }
 
+    /**
+     * The same as `eachOf` but runs a maximum of `limit` async operations at a
+     * time.
+     *
+     * @name eachOfLimit
+     * @static
+     * @memberOf async
+     * @see async.eachOf
+     * @alias forEachOfLimit
+     * @category Collection
+     * @param {Array|Object} coll - A collection to iterate over.
+     * @param {number} limit - The maximum number of async operations at a time.
+     * @param {Function} iteratee - A function to apply to each
+     * item in `coll`. The `key` is the item's key, or index in the case of an
+     * array. The iteratee is passed a `callback(err)` which must be called once it
+     * has completed. If no error has occurred, the callback should be run without
+     * arguments or with an explicit `null` argument. Invoked with
+     * (item, key, callback).
+     * @param {Function} [callback] - A callback which is called when all
+     * `iteratee` functions have finished, or an error occurs. Invoked with (err).
+     */
     function eachOfLimit(obj, limit, iteratee, cb) {
-        _eachOfLimit(limit)(obj, iteratee, cb);
+      _eachOfLimit(limit)(obj, iteratee, cb);
     }
 
+    /**
+     * The same as `eachOf` but runs only a single async operation at a time.
+     *
+     * @name eachOfSeries
+     * @static
+     * @memberOf async
+     * @see async.eachOf
+     * @alias forEachOfSeries
+     * @category Collection
+     * @param {Array|Object} coll - A collection to iterate over.
+     * @param {Function} iteratee - A function to apply to each item in `coll`. The
+     * `key` is the item's key, or index in the case of an array. The iteratee is
+     * passed a `callback(err)` which must be called once it has completed. If no
+     * error has occurred, the callback should be run without arguments or with an
+     * explicit `null` argument. Invoked with (item, key, callback).
+     * @param {Function} [callback] - A callback which is called when all `iteratee`
+     * functions have finished, or an error occurs. Invoked with (err).
+     */
     var eachOfSeries = doLimit(eachOfLimit, 1);
 
+    /**
+     * Reduces `coll` into a single value using an async `iteratee` to return each
+     * successive step. `memo` is the initial state of the reduction. This function
+     * only operates in series.
+     *
+     * For performance reasons, it may make sense to split a call to this function
+     * into a parallel map, and then use the normal `Array.prototype.reduce` on the
+     * results. This function is for situations where each step in the reduction
+     * needs to be async; if you can get the data before reducing it, then it's
+     * probably a good idea to do so.
+     *
+     * @name reduce
+     * @static
+     * @memberOf async
+     * @alias inject, foldl
+     * @category Collection
+     * @param {Array|Object} coll - A collection to iterate over.
+     * @param {*} memo - The initial state of the reduction.
+     * @param {Function} iteratee - A function applied to each item in the
+     * array to produce the next step in the reduction. The `iteratee` is passed a
+     * `callback(err, reduction)` which accepts an optional error as its first
+     * argument, and the state of the reduction as the second. If an error is
+     * passed to the callback, the reduction is stopped and the main `callback` is
+     * immediately called with the error. Invoked with (memo, item, callback).
+     * @param {Function} [callback] - A callback which is called after all the
+     * `iteratee` functions have finished. Result is the reduced value. Invoked with
+     * (err, result).
+     * @example
+     *
+     * async.reduce([1,2,3], 0, function(memo, item, callback) {
+     *     // pointless async:
+     *     process.nextTick(function() {
+     *         callback(null, memo + item)
+     *     });
+     * }, function(err, result) {
+     *     // result is now equal to the last value of memo, which is 6
+     * });
+     */
     function reduce(arr, memo, iteratee, cb) {
         eachOfSeries(arr, function (x, i, cb) {
             iteratee(memo, x, function (err, v) {
@@ -3147,6 +3691,42 @@
         });
     }
 
+    /**
+     * Version of the compose function that is more natural to read. Each function
+     * consumes the return value of the previous function. It is the equivalent of
+     * {@link async.compose} with the arguments reversed.
+     *
+     * Each function is executed with the `this` binding of the composed function.
+     *
+     * @name seq
+     * @static
+     * @memberOf async
+     * @see async.compose
+     * @category Control Flow
+     * @param {...Function} functions - the asynchronous functions to compose
+     * @example
+     *
+     * // Requires lodash (or underscore), express3 and dresende's orm2.
+     * // Part of an app, that fetches cats of the logged user.
+     * // This example uses `seq` function to avoid overnesting and error
+     * // handling clutter.
+     * app.get('/cats', function(request, response) {
+     *     var User = request.models.User;
+     *     async.seq(
+     *         _.bind(User.get, User),  // 'User.get' has signature (id, callback(err, data))
+     *         function(user, fn) {
+     *             user.getCats(fn);      // 'getCats' has signature (callback(err, data))
+     *         }
+     *     )(req.session.user_id, function (err, cats) {
+     *         if (err) {
+     *             console.error(err);
+     *             response.json({ status: 'error', message: err.message });
+     *         } else {
+     *             response.json({ status: 'ok', message: 'Cats found', data: cats });
+     *         }
+     *     });
+     * });
+     */
     function seq() /* functions... */{
         var fns = arguments;
         return rest(function (args) {
@@ -3171,8 +3751,40 @@
 
     var reverse = Array.prototype.reverse;
 
+    /**
+     * Creates a function which is a composition of the passed asynchronous
+     * functions. Each function consumes the return value of the function that
+     * follows. Composing functions `f()`, `g()`, and `h()` would produce the result
+     * of `f(g(h()))`, only this version uses callbacks to obtain the return values.
+     *
+     * Each function is executed with the `this` binding of the composed function.
+     *
+     * @name compose
+     * @static
+     * @memberOf async
+     * @category Control Flow
+     * @param {...Function} functions - the asynchronous functions to compose
+     * @example
+     *
+     * function add1(n, callback) {
+     *     setTimeout(function () {
+     *         callback(null, n + 1);
+     *     }, 10);
+     * }
+     *
+     * function mul3(n, callback) {
+     *     setTimeout(function () {
+     *         callback(null, n * 3);
+     *     }, 10);
+     * }
+     *
+     * var add1mul3 = async.compose(mul3, add1);
+     * add1mul3(4, function (err, result) {
+     *     // result now equals 15
+     * });
+     */
     function compose() /* functions... */{
-        return seq.apply(null, reverse.call(arguments));
+      return seq.apply(null, reverse.call(arguments));
     }
 
     function concat$1(eachfn, arr, fn, callback) {
@@ -3187,6 +3799,45 @@
         });
     }
 
+    /**
+     * Like `each`, except that it passes the key (or index) as the second argument
+     * to the iteratee.
+     *
+     * @name eachOf
+     * @static
+     * @memberOf async
+     * @alias forEachOf
+     * @category Collection
+     * @param {Array|Object} coll - A collection to iterate over.
+     * @param {Function} iteratee - A function to apply to each
+     * item in `coll`. The `key` is the item's key, or index in the case of an
+     * array. The iteratee is passed a `callback(err)` which must be called once it
+     * has completed. If no error has occurred, the callback should be run without
+     * arguments or with an explicit `null` argument. Invoked with
+     * (item, key, callback).
+     * @param {Function} [callback] - A callback which is called when all
+     * `iteratee` functions have finished, or an error occurs. Invoked with (err).
+     * @example
+     *
+     * var obj = {dev: "/dev.json", test: "/test.json", prod: "/prod.json"};
+     * var configs = {};
+     *
+     * async.forEachOf(obj, function (value, key, callback) {
+     *     fs.readFile(__dirname + value, "utf8", function (err, data) {
+     *         if (err) return callback(err);
+     *         try {
+     *             configs[key] = JSON.parse(data);
+     *         } catch (e) {
+     *             return callback(e);
+     *         }
+     *         callback();
+     *     });
+     * }, function (err) {
+     *     if (err) console.error(err.message);
+     *     // configs is now a map of JSON data
+     *     doSomethingWith(configs);
+     * });
+     */
     var eachOf = doLimit(eachOfLimit, Infinity);
 
     function doParallel(fn) {
@@ -3195,6 +3846,32 @@
         };
     }
 
+    /**
+     * Applies `iteratee` to each item in `coll`, concatenating the results. Returns
+     * the concatenated list. The `iteratee`s are called in parallel, and the
+     * results are concatenated as they return. There is no guarantee that the
+     * results array will be returned in the original order of `coll` passed to the
+     * `iteratee` function.
+     *
+     * @name concat
+     * @static
+     * @memberOf async
+     * @category Collection
+     * @param {Array|Object} coll - A collection to iterate over.
+     * @param {Function} iteratee - A function to apply to each item in `coll`.
+     * The iteratee is passed a `callback(err, results)` which must be called once
+     * it has completed with an error (which can be `null`) and an array of results.
+     * Invoked with (item, callback).
+     * @param {Function} [callback(err)] - A callback which is called after all the
+     * `iteratee` functions have finished, or an error occurs. Results is an array
+     * containing the concatenated results of the `iteratee` function. Invoked with
+     * (err, results).
+     * @example
+     *
+     * async.concat(['dir1','dir2','dir3'], fs.readdir, function(err, files) {
+     *     // files is now a list of filenames that exist in the 3 directories
+     * });
+     */
     var concat = doParallel(concat$1);
 
     function doSeries(fn) {
@@ -3203,8 +3880,67 @@
         };
     }
 
+    /**
+     * The same as `concat` but runs only a single async operation at a time.
+     *
+     * @name concatSeries
+     * @static
+     * @memberOf async
+     * @see async.concat
+     * @category Collection
+     * @param {Array|Object} coll - A collection to iterate over.
+     * @param {Function} iteratee - A function to apply to each item in `coll`.
+     * The iteratee is passed a `callback(err, results)` which must be called once
+     * it has completed with an error (which can be `null`) and an array of results.
+     * Invoked with (item, callback).
+     * @param {Function} [callback(err)] - A callback which is called after all the
+     * `iteratee` functions have finished, or an error occurs. Results is an array
+     * containing the concatenated results of the `iteratee` function. Invoked with
+     * (err, results).
+     */
     var concatSeries = doSeries(concat$1);
 
+    /**
+     * Returns a function that when called, calls-back with the values provided.
+     * Useful as the first function in a `waterfall`, or for plugging values in to
+     * `auto`.
+     *
+     * @name constant
+     * @static
+     * @memberOf async
+     * @category Util
+     * @param {...*} arguments... - Any number of arguments to automatically invoke
+     * callback with.
+     * @returns {Function} Returns a function that when invoked, automatically
+     * invokes the callback with the previous given arguments.
+     * @example
+     *
+     * async.waterfall([
+     *     async.constant(42),
+     *     function (value, next) {
+     *         // value === 42
+     *     },
+     *     //...
+     * ], callback);
+     *
+     * async.waterfall([
+     *     async.constant(filename, "utf8"),
+     *     fs.readFile,
+     *     function (fileData, next) {
+     *         //...
+     *     }
+     *     //...
+     * ], callback);
+     *
+     * async.auto({
+     *     hostname: async.constant("https://server.net/"),
+     *     port: findFreePort,
+     *     launchServer: ["hostname", "port", function (options, cb) {
+     *         startServer(options, cb);
+     *     }],
+     *     //...
+     * }, callback);
+     */
     var constant = rest(function (values) {
         var args = [null].concat(values);
         return initialParams(function (ignoredArgs, callback) {
@@ -3254,10 +3990,84 @@
         return x;
     }
 
+    /**
+     * Returns the first value in `coll` that passes an async truth test. The
+     * `iteratee` is applied in parallel, meaning the first iteratee to return
+     * `true` will fire the detect `callback` with that result. That means the
+     * result might not be the first item in the original `coll` (in terms of order)
+     * that passes the test.
+
+     * If order within the original `coll` is important, then look at
+     * `detectSeries`.
+     *
+     * @name detect
+     * @static
+     * @memberOf async
+     * @alias find
+     * @category Collection
+     * @param {Array|Object} coll - A collection to iterate over.
+     * @param {Function} iteratee - A truth test to apply to each item in `coll`.
+     * The iteratee is passed a `callback(err, truthValue)` which must be called
+     * with a boolean argument once it has completed. Invoked with (item, callback).
+     * @param {Function} [callback] - A callback which is called as soon as any
+     * iteratee returns `true`, or after all the `iteratee` functions have finished.
+     * Result will be the first item in the array that passes the truth test
+     * (iteratee) or the value `undefined` if none passed. Invoked with
+     * (err, result).
+     * @example
+     *
+     * async.detect(['file1','file2','file3'], function(filePath, callback) {
+     *     fs.access(filePath, function(err) {
+     *         callback(null, !err)
+     *     });
+     * }, function(err, result) {
+     *     // result now equals the first file in the list that exists
+     * });
+     */
     var detect = _createTester(eachOf, identity, _findGetResult);
 
+    /**
+     * The same as `detect` but runs a maximum of `limit` async operations at a
+     * time.
+     *
+     * @name detectLimit
+     * @static
+     * @memberOf async
+     * @see async.detect
+     * @alias findLimit
+     * @category Collection
+     * @param {Array|Object} coll - A collection to iterate over.
+     * @param {number} limit - The maximum number of async operations at a time.
+     * @param {Function} iteratee - A truth test to apply to each item in `coll`.
+     * The iteratee is passed a `callback(err, truthValue)` which must be called
+     * with a boolean argument once it has completed. Invoked with (item, callback).
+     * @param {Function} [callback] - A callback which is called as soon as any
+     * iteratee returns `true`, or after all the `iteratee` functions have finished.
+     * Result will be the first item in the array that passes the truth test
+     * (iteratee) or the value `undefined` if none passed. Invoked with
+     * (err, result).
+     */
     var detectLimit = _createTester(eachOfLimit, identity, _findGetResult);
 
+    /**
+     * The same as `detect` but runs only a single async operation at a time.
+     *
+     * @name detectSeries
+     * @static
+     * @memberOf async
+     * @see async.detect
+     * @alias findSeries
+     * @category Collection
+     * @param {Array|Object} coll - A collection to iterate over.
+     * @param {Function} iteratee - A truth test to apply to each item in `coll`.
+     * The iteratee is passed a `callback(err, truthValue)` which must be called
+     * with a boolean argument once it has completed. Invoked with (item, callback).
+     * @param {Function} [callback] - A callback which is called as soon as any
+     * iteratee returns `true`, or after all the `iteratee` functions have finished.
+     * Result will be the first item in the array that passes the truth test
+     * (iteratee) or the value `undefined` if none passed. Invoked with
+     * (err, result).
+     */
     var detectSeries = _createTester(eachOfSeries, identity, _findGetResult);
 
     function consoleFunc(name) {
@@ -3278,8 +4088,72 @@
         });
     }
 
+    /**
+     * Logs the result of an `async` function to the `console` using `console.dir`
+     * to display the properties of the resulting object. Only works in Node.js or
+     * in browsers that support `console.dir` and `console.error` (such as FF and
+     * Chrome). If multiple arguments are returned from the async function,
+     * `console.dir` is called on each argument in order.
+     *
+     * @name log
+     * @static
+     * @memberOf async
+     * @category Util
+     * @param {Function} function - The function you want to eventually apply all
+     * arguments to.
+     * @param {...*} arguments... - Any number of arguments to apply to the function.
+     * @example
+     *
+     * // in a module
+     * var hello = function(name, callback) {
+     *     setTimeout(function() {
+     *         callback(null, {hello: name});
+     *     }, 1000);
+     * };
+     *
+     * // in the node repl
+     * node> async.dir(hello, 'world');
+     * {hello: 'world'}
+     */
     var dir = consoleFunc('dir');
 
+    /**
+     * Like {@link async.whilst}, except the `test` is an asynchronous function that
+     * is passed a callback in the form of `function (err, truth)`. If error is
+     * passed to `test` or `fn`, the main callback is immediately called with the
+     * value of the error.
+     *
+     * @name during
+     * @static
+     * @memberOf async
+     * @see async.whilst
+     * @category Control Flow
+     * @param {Function} test - asynchronous truth test to perform before each
+     * execution of `fn`. Invoked with (callback).
+     * @param {Function} fn - A function which is called each time `test` passes.
+     * The function is passed a `callback(err)`, which must be called once it has
+     * completed with an optional `err` argument. Invoked with (callback).
+     * @param {Function} [callback] - A callback which is called after the test
+     * function has failed and repeated execution of `fn` has stopped. `callback`
+     * will be passed an error and any arguments passed to the final `fn`'s
+     * callback. Invoked with (err, [results]);
+     * @example
+     *
+     * var count = 0;
+     *
+     * async.during(
+     *     function (callback) {
+     *         return callback(null, count < 5);
+     *     },
+     *     function (callback) {
+     *         count++;
+     *         setTimeout(callback, 1000);
+     *     },
+     *     function (err) {
+     *         // 5 seconds have passed
+     *     }
+     * );
+     */
     function during(test, iteratee, cb) {
         cb = cb || noop;
 
@@ -3301,6 +4175,26 @@
         test(check);
     }
 
+    /**
+     * The post-check version of {@link async.during}. To reflect the difference in
+     * the order of operations, the arguments `test` and `fn` are switched.
+     *
+     * Also a version of {@link async.doWhilst} with asynchronous `test` function.
+     * @name doDuring
+     * @static
+     * @memberOf async
+     * @see async.during
+     * @category Control Flow
+     * @param {Function} fn - A function which is called each time `test` passes.
+     * The function is passed a `callback(err)`, which must be called once it has
+     * completed with an optional `err` argument. Invoked with (callback).
+     * @param {Function} test - asynchronous truth test to perform before each
+     * execution of `fn`. Invoked with (callback).
+     * @param {Function} [callback] - A callback which is called after the test
+     * function has failed and repeated execution of `fn` has stopped. `callback`
+     * will be passed an error and any arguments passed to the final `fn`'s
+     * callback. Invoked with (err, [results]);
+     */
     function doDuring(iteratee, test, cb) {
         var calls = 0;
 
@@ -3310,6 +4204,39 @@
         }, iteratee, cb);
     }
 
+    /**
+     * Repeatedly call `fn`, while `test` returns `true`. Calls `callback` when
+     * stopped, or an error occurs.
+     *
+     * @name whilst
+     * @static
+     * @memberOf async
+     * @category Control Flow
+     * @param {Function} test - synchronous truth test to perform before each
+     * execution of `fn`. Invoked with ().
+     * @param {Function} fn - A function which is called each time `test` passes.
+     * The function is passed a `callback(err)`, which must be called once it has
+     * completed with an optional `err` argument. Invoked with (callback).
+     * @param {Function} [callback] - A callback which is called after the test
+     * function has failed and repeated execution of `fn` has stopped. `callback`
+     * will be passed an error and any arguments passed to the final `fn`'s
+     * callback. Invoked with (err, [results]);
+     * @example
+     *
+     * var count = 0;
+     * async.whilst(
+     *     function() { return count < 5; },
+     *     function(callback) {
+     *         count++;
+     *         setTimeout(function() {
+     *             callback(null, count);
+     *         }, 1000);
+     *     },
+     *     function (err, n) {
+     *         // 5 seconds have passed, n = 5
+     *     }
+     * );
+     */
     function whilst(test, iteratee, cb) {
         cb = cb || noop;
         if (!test()) return cb(null);
@@ -3321,6 +4248,27 @@
         iteratee(next);
     }
 
+    /**
+     * The post-check version of {@link async.whilst}. To reflect the difference in
+     * the order of operations, the arguments `test` and `fn` are switched.
+     *
+     * `doWhilst` is to `whilst` as `do while` is to `while` in plain JavaScript.
+     *
+     * @name doWhilst
+     * @static
+     * @memberOf async
+     * @see async.whilst
+     * @category Control Flow
+     * @param {Function} fn - A function which is called each time `test` passes.
+     * The function is passed a `callback(err)`, which must be called once it has
+     * completed with an optional `err` argument. Invoked with (callback).
+     * @param {Function} test - synchronous truth test to perform before each
+     * execution of `fn`. Invoked with ().
+     * @param {Function} [callback] - A callback which is called after the test
+     * function has failed and repeated execution of `fn` has stopped. `callback`
+     * will be passed an error and any arguments passed to the final `fn`'s
+     * callback. Invoked with (err, [results]);
+     */
     function doWhilst(iteratee, test, cb) {
         var calls = 0;
         return whilst(function () {
@@ -3328,6 +4276,25 @@
         }, iteratee, cb);
     }
 
+    /**
+     * Like {@link async.doWhilst}, except the `test` is inverted. Note the
+     * argument ordering differs from `until`.
+     *
+     * @name doUntil
+     * @static
+     * @memberOf async
+     * @see async.doWhilst
+     * @category Control Flow
+     * @param {Function} fn - A function which is called each time `test` fails.
+     * The function is passed a `callback(err)`, which must be called once it has
+     * completed with an optional `err` argument. Invoked with (callback).
+     * @param {Function} test - synchronous truth test to perform before each
+     * execution of `fn`. Invoked with ().
+     * @param {Function} [callback] - A callback which is called after the test
+     * function has passed and repeated execution of `fn` has stopped. `callback`
+     * will be passed an error and any arguments passed to the final `fn`'s
+     * callback. Invoked with (err, [results]);
+     */
     function doUntil(iteratee, test, cb) {
         return doWhilst(iteratee, function () {
             return !test.apply(this, arguments);
@@ -3340,14 +4307,144 @@
         };
     }
 
+    /**
+     * The same as `each` but runs a maximum of `limit` async operations at a time.
+     *
+     * @name eachLimit
+     * @static
+     * @memberOf async
+     * @see async.each
+     * @alias forEachLimit
+     * @category Collection
+     * @param {Array|Object} coll - A colleciton to iterate over.
+     * @param {number} limit - The maximum number of async operations at a time.
+     * @param {Function} iteratee - A function to apply to each item in `coll`. The
+     * iteratee is passed a `callback(err)` which must be called once it has
+     * completed. If no error has occurred, the `callback` should be run without
+     * arguments or with an explicit `null` argument. The array index is not passed
+     * to the iteratee. Invoked with (item, callback). If you need the index, use
+     * `eachOfLimit`.
+     * @param {Function} [callback] - A callback which is called when all
+     * `iteratee` functions have finished, or an error occurs. Invoked with (err).
+     */
     function eachLimit(arr, limit, iteratee, cb) {
-        return _eachOfLimit(limit)(arr, _withoutIndex(iteratee), cb);
+      return _eachOfLimit(limit)(arr, _withoutIndex(iteratee), cb);
     }
 
+    /**
+     * Applies the function `iteratee` to each item in `coll`, in parallel.
+     * The `iteratee` is called with an item from the list, and a callback for when
+     * it has finished. If the `iteratee` passes an error to its `callback`, the
+     * main `callback` (for the `each` function) is immediately called with the
+     * error.
+     *
+     * Note, that since this function applies `iteratee` to each item in parallel,
+     * there is no guarantee that the iteratee functions will complete in order.
+     *
+     * @name each
+     * @static
+     * @memberOf async
+     * @alias forEach
+     * @category Collection
+     * @param {Array|Object} coll - A collection to iterate over.
+     * @param {Function} iteratee - A function to apply to each item
+     * in `coll`. The iteratee is passed a `callback(err)` which must be called once
+     * it has completed. If no error has occurred, the `callback` should be run
+     * without arguments or with an explicit `null` argument. The array index is not
+     * passed to the iteratee. Invoked with (item, callback). If you need the index,
+     * use `eachOf`.
+     * @param {Function} [callback] - A callback which is called when all
+     * `iteratee` functions have finished, or an error occurs. Invoked with (err).
+     * @example
+     *
+     * // assuming openFiles is an array of file names and saveFile is a function
+     * // to save the modified contents of that file:
+     *
+     * async.each(openFiles, saveFile, function(err){
+     *   // if any of the saves produced an error, err would equal that error
+     * });
+     *
+     * // assuming openFiles is an array of file names
+     * async.each(openFiles, function(file, callback) {
+     *
+     *     // Perform operation on file here.
+     *     console.log('Processing file ' + file);
+     *
+     *     if( file.length > 32 ) {
+     *       console.log('This file name is too long');
+     *       callback('File name too long');
+     *     } else {
+     *       // Do work to process file here
+     *       console.log('File processed');
+     *       callback();
+     *     }
+     * }, function(err) {
+     *     // if any of the file processing produced an error, err would equal that error
+     *     if( err ) {
+     *       // One of the iterations produced an error.
+     *       // All processing will now stop.
+     *       console.log('A file failed to process');
+     *     } else {
+     *       console.log('All files have been processed successfully');
+     *     }
+     * });
+     */
     var each = doLimit(eachLimit, Infinity);
 
+    /**
+     * The same as `each` but runs only a single async operation at a time.
+     *
+     * @name eachSeries
+     * @static
+     * @memberOf async
+     * @see async.each
+     * @alias forEachSeries
+     * @category Collection
+     * @param {Array|Object} coll - A collection to iterate over.
+     * @param {Function} iteratee - A function to apply to each
+     * item in `coll`. The iteratee is passed a `callback(err)` which must be called
+     * once it has completed. If no error has occurred, the `callback` should be run
+     * without arguments or with an explicit `null` argument. The array index is
+     * not passed to the iteratee. Invoked with (item, callback). If you need the
+     * index, use `eachOfSeries`.
+     * @param {Function} [callback] - A callback which is called when all
+     * `iteratee` functions have finished, or an error occurs. Invoked with (err).
+     */
     var eachSeries = doLimit(eachLimit, 1);
 
+    /**
+     * Wrap an async function and ensure it calls its callback on a later tick of
+     * the event loop.  If the function already calls its callback on a next tick,
+     * no extra deferral is added. This is useful for preventing stack overflows
+     * (`RangeError: Maximum call stack size exceeded`) and generally keeping
+     * [Zalgo](http://blog.izs.me/post/59142742143/designing-apis-for-asynchrony)
+     * contained.
+     *
+     * @name ensureAsync
+     * @static
+     * @memberOf async
+     * @category Util
+     * @param {Function} fn - an async function, one that expects a node-style
+     * callback as its last argument.
+     * @returns {Function} Returns a wrapped function with the exact same call
+     * signature as the function passed in.
+     * @example
+     *
+     * function sometimesAsync(arg, callback) {
+     *     if (cache[arg]) {
+     *         return callback(null, cache[arg]); // this would be synchronous!!
+     *     } else {
+     *         doSomeIO(arg, callback); // this IO would be asynchronous
+     *     }
+     * }
+     *
+     * // this has a risk of stack overflows if many results are cached in a row
+     * async.mapSeries(args, sometimesAsync, done);
+     *
+     * // this will defer sometimesAsync's callback if necessary,
+     * // preventing stack overflows
+     * async.mapSeries(args, async.ensureAsync(sometimesAsync), done);
+     */
     function ensureAsync(fn) {
         return initialParams(function (args, callback) {
             var sync = true;
@@ -3370,10 +4467,74 @@
         return !v;
     }
 
+    /**
+     * The same as `every` but runs a maximum of `limit` async operations at a time.
+     *
+     * @name everyLimit
+     * @static
+     * @memberOf async
+     * @see async.every
+     * @alias allLimit
+     * @category Collection
+     * @param {Array|Object} coll - A collection to iterate over.
+     * @param {number} limit - The maximum number of async operations at a time.
+     * @param {Function} iteratee - A truth test to apply to each item in the
+     * collection in parallel. The iteratee is passed a `callback(err, truthValue)`
+     * which must be called with a  boolean argument once it has completed. Invoked
+     * with (item, callback).
+     * @param {Function} [callback] - A callback which is called after all the
+     * `iteratee` functions have finished. Result will be either `true` or `false`
+     * depending on the values of the async tests. Invoked with (err, result).
+     */
     var everyLimit = _createTester(eachOfLimit, notId, notId);
 
+    /**
+     * Returns `true` if every element in `coll` satisfies an async test. If any
+     * iteratee call returns `false`, the main `callback` is immediately called.
+     *
+     * @name every
+     * @static
+     * @memberOf async
+     * @alias all
+     * @category Collection
+     * @param {Array|Object} coll - A collection to iterate over.
+     * @param {Function} iteratee - A truth test to apply to each item in the
+     * collection in parallel. The iteratee is passed a `callback(err, truthValue)`
+     * which must be called with a  boolean argument once it has completed. Invoked
+     * with (item, callback).
+     * @param {Function} [callback] - A callback which is called after all the
+     * `iteratee` functions have finished. Result will be either `true` or `false`
+     * depending on the values of the async tests. Invoked with (err, result).
+     * @example
+     *
+     * async.every(['file1','file2','file3'], function(filePath, callback) {
+     *     fs.access(filePath, function(err) {
+     *         callback(null, !err)
+     *     });
+     * }, function(err, result) {
+     *     // if result is true then every file exists
+     * });
+     */
     var every = doLimit(everyLimit, Infinity);
 
+    /**
+     * The same as `every` but runs only a single async operation at a time.
+     *
+     * @name everySeries
+     * @static
+     * @memberOf async
+     * @see async.every
+     * @alias allSeries
+     * @category Collection
+     * @param {Array|Object} coll - A collection to iterate over.
+     * @param {Function} iteratee - A truth test to apply to each item in the
+     * collection in parallel. The iteratee is passed a `callback(err, truthValue)`
+     * which must be called with a  boolean argument once it has completed. Invoked
+     * with (item, callback).
+     * @param {Function} [callback] - A callback which is called after all the
+     * `iteratee` functions have finished. Result will be either `true` or `false`
+     * depending on the values of the async tests. Invoked with (err, result).
+     */
     var everySeries = doLimit(everyLimit, 1);
 
     function _filter(eachfn, arr, iteratee, callback) {
@@ -3400,12 +4561,100 @@
         });
     }
 
+    /**
+     * The same as `filter` but runs a maximum of `limit` async operations at a
+     * time.
+     *
+     * @name filterLimit
+     * @static
+     * @memberOf async
+     * @see async.filter
+     * @alias selectLimit
+     * @category Collection
+     * @param {Array|Object} coll - A collection to iterate over.
+     * @param {number} limit - The maximum number of async operations at a time.
+     * @param {Function} iteratee - A truth test to apply to each item in `coll`.
+     * The `iteratee` is passed a `callback(err, truthValue)`, which must be called
+     * with a boolean argument once it has completed. Invoked with (item, callback).
+     * @param {Function} [callback] - A callback which is called after all the
+     * `iteratee` functions have finished. Invoked with (err, results).
+     */
     var filterLimit = doParallelLimit(_filter);
 
+    /**
+     * Returns a new array of all the values in `coll` which pass an async truth
+     * test. This operation is performed in parallel, but the results array will be
+     * in the same order as the original.
+     *
+     * @name filter
+     * @static
+     * @memberOf async
+     * @alias select
+     * @category Collection
+     * @param {Array|Object} coll - A collection to iterate over.
+     * @param {Function} iteratee - A truth test to apply to each item in `coll`.
+     * The `iteratee` is passed a `callback(err, truthValue)`, which must be called
+     * with a boolean argument once it has completed. Invoked with (item, callback).
+     * @param {Function} [callback] - A callback which is called after all the
+     * `iteratee` functions have finished. Invoked with (err, results).
+     * @example
+     *
+     * async.filter(['file1','file2','file3'], function(filePath, callback) {
+     *     fs.access(filePath, function(err) {
+     *         callback(null, !err)
+     *     });
+     * }, function(err, results) {
+     *     // results now equals an array of the existing files
+     * });
+     */
     var filter = doLimit(filterLimit, Infinity);
 
+    /**
+     * The same as `filter` but runs only a single async operation at a time.
+     *
+     * @name filterSeries
+     * @static
+     * @memberOf async
+     * @see async.filter
+     * @alias selectSeries
+     * @category Collection
+     * @param {Array|Object} coll - A collection to iterate over.
+     * @param {Function} iteratee - A truth test to apply to each item in `coll`.
+     * The `iteratee` is passed a `callback(err, truthValue)`, which must be called
+     * with a boolean argument once it has completed. Invoked with (item, callback).
+     * @param {Function} [callback] - A callback which is called after all the
+     * `iteratee` functions have finished. Invoked with (err, results)
+     */
     var filterSeries = doLimit(filterLimit, 1);
 
+    /**
+     * Calls the asynchronous function `fn` with a callback parameter that allows it
+     * to call itself again, in series, indefinitely.
+
+     * If an error is passed to the
+     * callback then `errback` is called with the error, and execution stops,
+     * otherwise it will never be called.
+     *
+     * @name forever
+     * @static
+     * @memberOf async
+     * @category Control Flow
+     * @param {Function} fn - a function to call repeatedly. Invoked with (next).
+     * @param {Function} [errback] - when `fn` passes an error to it's callback,
+     * this function will be called, and execution stops. Invoked with (err).
+     * @example
+     *
+     * async.forever(
+     *     function(next) {
+     *         // next is suitable for passing to things that need a callback(err [, whatever]);
+     *         // it will result in this function being called again.
+     *     },
+     *     function(err) {
+     *         // if next is called with a value in its first parameter, it will appear
+     *         // in here as 'err', and execution will stop.
+     *     }
+     * );
+     */
     function forever(fn, cb) {
         var done = onlyOnce(cb || noop);
         var task = ensureAsync(fn);
@@ -3417,6 +4666,39 @@
         next();
     }
 
+    /**
+     * Creates an iterator function which calls the next function in the `tasks`
+     * array, returning a continuation to call the next one after that. It's also
+     * possible to “peek” at the next iterator with `iterator.next()`.
+     *
+     * This function is used internally by the `async` module, but can be useful
+     * when you want to manually control the flow of functions in series.
+     *
+     * @name iterator
+     * @static
+     * @memberOf async
+     * @category Control Flow
+     * @param {Array} tasks - An array of functions to run.
+     * @returns The next function to run in the series.
+     * @example
+     *
+     * var iterator = async.iterator([
+     *     function() { sys.p('one'); },
+     *     function() { sys.p('two'); },
+     *     function() { sys.p('three'); }
+     * ]);
+     *
+     * node> var iterator2 = iterator();
+     * 'one'
+     * node> var iterator3 = iterator2();
+     * 'two'
+     * node> iterator3();
+     * 'three'
+     * node> var nextfn = iterator2.next();
+     * node> nextfn();
+     * 'three'
+     */
+
     function iterator$1 (tasks) {
         function makeCallback(index) {
             function fn() {
@@ -3433,12 +4715,73 @@
         return makeCallback(0);
     }
 
+    /**
+     * Logs the result of an `async` function to the `console`. Only works in
+     * Node.js or in browsers that support `console.log` and `console.error` (such
+     * as FF and Chrome). If multiple arguments are returned from the async
+     * function, `console.log` is called on each argument in order.
+     *
+     * @name log
+     * @static
+     * @memberOf async
+     * @category Util
+     * @param {Function} function - The function you want to eventually apply all
+     * arguments to.
+     * @param {...*} arguments... - Any number of arguments to apply to the function.
+     * @example
+     *
+     * // in a module
+     * var hello = function(name, callback) {
+     *     setTimeout(function() {
+     *         callback(null, 'hello ' + name);
+     *     }, 1000);
+     * };
+     *
+     * // in the node repl
+     * node> async.log(hello, 'world');
+     * 'hello world'
+     */
     var log = consoleFunc('log');
 
     function has(obj, key) {
         return key in obj;
     }
 
+    /**
+     * Caches the results of an `async` function. When creating a hash to store
+     * function results against, the callback is omitted from the hash and an
+     * optional hash function can be used.
+     *
+     * If no hash function is specified, the first argument is used as a hash key,
+     * which may work reasonably if it is a string or a data type that converts to a
+     * distinct string. Note that objects and arrays will not behave reasonably.
+     * Neither will cases where the other arguments are significant. In such cases,
+     * specify your own hash function.
+     *
+     * The cache of results is exposed as the `memo` property of the function
+     * returned by `memoize`.
+     *
+     * @name memoize
+     * @static
+     * @memberOf async
+     * @category Util
+     * @param {Function} fn - The function to proxy and cache results from.
+     * @param {Function} hasher - An optional function for generating a custom hash
+     * for storing results. It has all the arguments applied to it apart from the
+     * callback, and must be synchronous.
+     * @example
+     *
+     * var slow_fn = function(name, callback) {
+     *     // do something
+     *     callback(null, result);
+     * };
+     * var fn = async.memoize(slow_fn);
+     *
+     * // fn can now be used as if it were slow_fn
+     * fn('some name', function() {
+     *     // callback
+     * });
+     */
     function memoize$1(fn, hasher) {
         var memo = Object.create(null);
         var queues = Object.create(null);
@@ -3485,18 +4828,221 @@
         });
     }
 
+    /**
+     * The same as `parallel` but runs a maximum of `limit` async operations at a
+     * time.
+     *
+     * @name parallel
+     * @static
+     * @memberOf async
+     * @see async.parallel
+     * @category Control Flow
+     * @param {Array|Collection} tasks - A collection containing functions to run.
+     * Each function is passed a `callback(err, result)` which it must call on
+     * completion with an error `err` (which can be `null`) and an optional `result`
+     * value.
+     * @param {number} limit - The maximum number of async operations at a time.
+     * @param {Function} [callback] - An optional callback to run once all the
+     * functions have completed successfully. This function gets a results array
+     * (or object) containing all the result arguments passed to the task callbacks.
+     * Invoked with (err, results).
+     */
     function parallelLimit(tasks, limit, cb) {
-        return _parallel(_eachOfLimit(limit), tasks, cb);
+      return _parallel(_eachOfLimit(limit), tasks, cb);
     }
 
+    /**
+     * Run the `tasks` collection of functions in parallel, without waiting until
+     * the previous function has completed. If any of the functions pass an error to
+     * its callback, the main `callback` is immediately called with the value of the
+     * error. Once the `tasks` have completed, the results are passed to the final
+     * `callback` as an array.
+     *
+     * **Note:** `parallel` is about kicking-off I/O tasks in parallel, not about
+     * parallel execution of code.  If your tasks do not use any timers or perform
+     * any I/O, they will actually be executed in series.  Any synchronous setup
+     * sections for each task will happen one after the other.  JavaScript remains
+     * single-threaded.
+     *
+     * It is also possible to use an object instead of an array. Each property will
+     * be run as a function and the results will be passed to the final `callback`
+     * as an object instead of an array. This can be a more readable way of handling
+     * results from {@link async.parallel}.
+     *
+     * @name parallel
+     * @static
+     * @memberOf async
+     * @category Control Flow
+     * @param {Array|Object} tasks - A collection containing functions to run.
+     * Each function is passed a `callback(err, result)` which it must call on
+     * completion with an error `err` (which can be `null`) and an optional `result`
+     * value.
+     * @param {Function} [callback] - An optional callback to run once all the
+     * functions have completed successfully. This function gets a results array
+     * (or object) containing all the result arguments passed to the task callbacks.
+     * Invoked with (err, results).
+     * @example
+     * async.parallel([
+     *     function(callback) {
+     *         setTimeout(function() {
+     *             callback(null, 'one');
+     *         }, 200);
+     *     },
+     *     function(callback) {
+     *         setTimeout(function() {
+     *             callback(null, 'two');
+     *         }, 100);
+     *     }
+     * ],
+     * // optional callback
+     * function(err, results) {
+     *     // the results array will equal ['one','two'] even though
+     *     // the second function had a shorter timeout.
+     * });
+     *
+     * // an example using an object instead of an array
+     * async.parallel({
+     *     one: function(callback) {
+     *         setTimeout(function() {
+     *             callback(null, 1);
+     *         }, 200);
+     *     },
+     *     two: function(callback) {
+     *         setTimeout(function() {
+     *             callback(null, 2);
+     *         }, 100);
+     *     }
+     * }, function(err, results) {
+     *     // results is now equals to: {one: 1, two: 2}
+     * });
+     */
     var parallel = doLimit(parallelLimit, Infinity);
 
+    /**
+     * A queue of tasks for the worker function to complete.
+     * @typedef {Object} queue
+     * @property {Function} length - a function returning the number of items
+     * waiting to be processed. Invoke with ().
+     * @property {Function} started - a function returning whether or not any
+     * items have been pushed and processed by the queue. Invoke with ().
+     * @property {Function} running - a function returning the number of items
+     * currently being processed. Invoke with ().
+     * @property {Function} workersList - a function returning the array of items
+     * currently being processed. Invoke with ().
+     * @property {Function} idle - a function returning false if there are items
+     * waiting or being processed, or true if not. Invoke with ().
+     * @property {number} concurrency - an integer for determining how many `worker`
+     * functions should be run in parallel. This property can be changed after a
+     * `queue` is created to alter the concurrency on-the-fly.
+     * @property {Function} push - add a new task to the `queue`. Calls `callback`
+     * once the `worker` has finished processing the task. Instead of a single task,
+     * a `tasks` array can be submitted. The respective callback is used for every
+     * task in the list. Invoke with (task, [callback]),
+     * @property {Function} unshift - add a new task to the front of the `queue`.
+     * Invoke with (task, [callback]).
+     * @property {Function} saturated - a callback that is called when the number of
+     * running workers hits the `concurrency` limit, and further tasks will be
+     * queued.
+     * @property {Function} unsaturated - a callback that is called when the number
+     * of running workers is less than the `concurrency` & `buffer` limits, and
+     * further tasks will not be queued.
+     * @property {number} buffer - A minimum threshold buffer in order to say that
+     * the `queue` is `unsaturated`.
+     * @property {Function} empty - a callback that is called when the last item
+     * from the `queue` is given to a `worker`.
+     * @property {Function} drain - a callback that is called when the last item
+     * from the `queue` has returned from the `worker`.
+     * @property {boolean} paused - a boolean for determining whether the queue is
+     * in a paused state.
+     * @property {Function} pause - a function that pauses the processing of tasks
+     * until `resume()` is called. Invoke with ().
+     * @property {Function} resume - a function that resumes the processing of
+     * queued tasks when the queue is paused. Invoke with ().
+     * @property {Function} kill - a function that removes the `drain` callback and
+     * empties remaining tasks from the queue forcing it to go idle. Invoke with ().
+     */
+
+    /**
+     * Creates a `queue` object with the specified `concurrency`. Tasks added to the
+     * `queue` are processed in parallel (up to the `concurrency` limit). If all
+     * `worker`s are in progress, the task is queued until one becomes available.
+     * Once a `worker` completes a `task`, that `task`'s callback is called.
+     *
+     * @name queue
+     * @static
+     * @memberOf async
+     * @category Control Flow
+     * @param {Function} worker - An asynchronous function for processing a queued
+     * task, which must call its `callback(err)` argument when finished, with an
+     * optional `error` as an argument.  If you want to handle errors from an
+     * individual task, pass a callback to `q.push()`. Invoked with
+     * (task, callback).
+     * @param {number} [concurrency=1] - An `integer` for determining how many
+     * `worker` functions should be run in parallel.  If omitted, the concurrency
+     * defaults to `1`.  If the concurrency is `0`, an error is thrown.
+     * @returns {queue} A queue object to manage the tasks. Callbacks can
+     * attached as certain properties to listen for specific events during the
+     * lifecycle of the queue.
+     * @example
+     *
+     * // create a queue object with concurrency 2
+     * var q = async.queue(function(task, callback) {
+     *     console.log('hello ' + task.name);
+     *     callback();
+     * }, 2);
+     *
+     * // assign a callback
+     * q.drain = function() {
+     *     console.log('all items have been processed');
+     * };
+     *
+     * // add some items to the queue
+     * q.push({name: 'foo'}, function(err) {
+     *     console.log('finished processing foo');
+     * });
+     * q.push({name: 'bar'}, function (err) {
+     *     console.log('finished processing bar');
+     * });
+     *
+     * // add some items to the queue (batch-wise)
+     * q.push([{name: 'baz'},{name: 'bay'},{name: 'bax'}], function(err) {
+     *     console.log('finished processing item');
+     * });
+     *
+     * // add some items to the front of the queue
+     * q.unshift({name: 'bar'}, function (err) {
+     *     console.log('finished processing bar');
+     * });
+     */
     function queue$1 (worker, concurrency) {
-        return queue(function (items, cb) {
-            worker(items[0], cb);
-        }, concurrency, 1);
+      return queue(function (items, cb) {
+        worker(items[0], cb);
+      }, concurrency, 1);
     }
 
+    /**
+     * The same as {@link async.queue} only tasks are assigned a priority and
+     * completed in ascending priority order.
+     *
+     * @name priorityQueue
+     * @static
+     * @memberOf async
+     * @see async.queue
+     * @category Control Flow
+     * @param {Function} worker - An asynchronous function for processing a queued
+     * task, which must call its `callback(err)` argument when finished, with an
+     * optional `error` as an argument.  If you want to handle errors from an
+     * individual task, pass a callback to `q.push()`. Invoked with
+     * (task, callback).
+     * @param {number} concurrency - An `integer` for determining how many `worker`
+     * functions should be run in parallel.  If omitted, the concurrency defaults to
+     * `1`.  If the concurrency is `0`, an error is thrown.
+     * @returns {queue} A priorityQueue object to manage the tasks. There are two
+     * differences between `queue` and `priorityQueue` objects:
+     * * `push(task, priority, [callback])` - `priority` should be a number. If an
+     *   array of `tasks` is given, all tasks will be assigned the same priority.
+     * * The `unshift` method was removed.
+     */
     function priorityQueue (worker, concurrency) {
         function _compareTasks(a, b) {
             return a.priority - b.priority;
@@ -3539,12 +5085,6 @@
 
                 q.tasks.splice(_binarySearch(q.tasks, item, _compareTasks) + 1, 0, item);
 
-                if (q.tasks.length === q.concurrency) {
-                    q.saturated();
-                }
-                if (q.tasks.length <= q.concurrency - q.buffer) {
-                    q.unsaturated();
-                }
                 setImmediate$1(q.process);
             });
         }
@@ -3637,6 +5177,41 @@
         : baseEach(collection, baseIteratee(iteratee));
     }
 
+    /**
+     * Runs the `tasks` array of functions in parallel, without waiting until the
+     * previous function has completed. Once any the `tasks` completed or pass an
+     * error to its callback, the main `callback` is immediately called. It's
+     * equivalent to `Promise.race()`.
+     *
+     * @name race
+     * @static
+     * @memberOf async
+     * @category Control Flow
+     * @param {Array} tasks - An array containing functions to run. Each function
+     * is passed a `callback(err, result)` which it must call on completion with an
+     * error `err` (which can be `null`) and an optional `result` value.
+     * @param {Function} callback - A callback to run once any of the functions have
+     * completed. This function gets an error or result from the first function that
+     * completed. Invoked with (err, result).
+     * @example
+     *
+     * async.race([
+     *     function(callback) {
+     *         setTimeout(function() {
+     *             callback(null, 'one');
+     *         }, 200);
+     *     },
+     *     function(callback) {
+     *         setTimeout(function() {
+     *             callback(null, 'two');
+     *         }, 100);
+     *     }
+     * ],
+     * // main callback
+     * function(err, result) {
+     *     // the result will be equal to 'two' as it finishes earlier
+     * });
+     */
     function race(tasks, cb) {
         cb = once(cb || noop);
         if (!isArray(tasks)) return cb(new TypeError('First argument to race must be an array of functions'));
@@ -3648,11 +5223,70 @@
 
     var slice = Array.prototype.slice;
 
+    /**
+     * Same as `reduce`, only operates on `coll` in reverse order.
+     *
+     * @name reduceRight
+     * @static
+     * @memberOf async
+     * @see async.reduce
+     * @alias foldr
+     * @category Collection
+     * @param {Array|Object} coll - A collection to iterate over.
+     * @param {*} memo - The initial state of the reduction.
+     * @param {Function} iteratee - A function applied to each item in the
+     * array to produce the next step in the reduction. The `iteratee` is passed a
+     * `callback(err, reduction)` which accepts an optional error as its first
+     * argument, and the state of the reduction as the second. If an error is
+     * passed to the callback, the reduction is stopped and the main `callback` is
+     * immediately called with the error. Invoked with (memo, item, callback).
+     * @param {Function} [callback] - A callback which is called after all the
+     * `iteratee` functions have finished. Result is the reduced value. Invoked with
+     * (err, result).
+     */
     function reduceRight(arr, memo, iteratee, cb) {
-        var reversed = slice.call(arr).reverse();
-        reduce(reversed, memo, iteratee, cb);
+      var reversed = slice.call(arr).reverse();
+      reduce(reversed, memo, iteratee, cb);
     }
 
+    /**
+     * Wraps the function in another function that always returns data even when it
+     * errors.
+     *
+     * The object returned has either the property `error` or `value`.
+     *
+     * @name reflect
+     * @static
+     * @memberOf async
+     * @category Util
+     * @param {Function} function - The function you want to wrap
+     * @returns {Function} - A function that always passes null to it's callback as
+     * the error. The second argument to the callback will be an `object` with
+     * either an `error` or a `value` property.
+     * @example
+     *
+     * async.parallel([
+     *     async.reflect(function(callback) {
+     *         // do some stuff ...
+     *         callback(null, 'one');
+     *     }),
+     *     async.reflect(function(callback) {
+     *         // do some more stuff but error ...
+     *         callback('bad stuff happened');
+     *     }),
+     *     async.reflect(function(callback) {
+     *         // do some more stuff ...
+     *         callback(null, 'two');
+     *     })
+     * ],
+     * // optional callback
+     * function(err, results) {
+     *     // values
+     *     // results[0].value = 'one'
+     *     // results[1].error = 'bad stuff happened'
+     *     // results[2].value = 'two'
+     * });
+     */
     function reflect(fn) {
         return initialParams(function reflectOn(args, reflectCallback) {
             args.push(rest(function callback(err, cbArgs) {
@@ -3689,20 +5323,236 @@
         }, callback);
     }
 
+    /**
+     * The same as `reject` but runs a maximum of `limit` async operations at a
+     * time.
+     *
+     * @name rejectLimit
+     * @static
+     * @memberOf async
+     * @see async.reject
+     * @category Collection
+     * @param {Array|Object} coll - A collection to iterate over.
+     * @param {number} limit - The maximum number of async operations at a time.
+     * @param {Function} iteratee - A truth test to apply to each item in `coll`.
+     * The `iteratee` is passed a `callback(err, truthValue)`, which must be called
+     * with a boolean argument once it has completed. Invoked with (item, callback).
+     * @param {Function} [callback] - A callback which is called after all the
+     * `iteratee` functions have finished. Invoked with (err, results).
+     */
     var rejectLimit = doParallelLimit(reject$1);
 
+    /**
+     * The opposite of `filter`. Removes values that pass an `async` truth test.
+     *
+     * @name reject
+     * @static
+     * @memberOf async
+     * @see async.filter
+     * @category Collection
+     * @param {Array|Object} coll - A collection to iterate over.
+     * @param {Function} iteratee - A truth test to apply to each item in `coll`.
+     * The `iteratee` is passed a `callback(err, truthValue)`, which must be called
+     * with a boolean argument once it has completed. Invoked with (item, callback).
+     * @param {Function} [callback] - A callback which is called after all the
+     * `iteratee` functions have finished. Invoked with (err, results).
+     * @example
+     *
+     * async.reject(['file1','file2','file3'], function(filePath, callback) {
+     *     fs.access(filePath, function(err) {
+     *         callback(null, !err)
+     *     });
+     * }, function(err, results) {
+     *     // results now equals an array of missing files
+     *     createFiles(results);
+     * });
+     */
     var reject = doLimit(rejectLimit, Infinity);
 
+    /**
+     * A helper function that wraps an array of functions with reflect.
+     *
+     * @name reflectAll
+     * @static
+     * @memberOf async
+     * @see async.reflect
+     * @category Util
+     * @param {Array} tasks - The array of functions to wrap in `async.reflect`.
+     * @returns {Array} Returns an array of functions, each function wrapped in
+     * `async.reflect`
+     * @example
+     *
+     * let tasks = [
+     *     function(callback) {
+     *         setTimeout(function() {
+     *             callback(null, 'one');
+     *         }, 200);
+     *     },
+     *     function(callback) {
+     *         // do some more stuff but error ...
+     *         callback(new Error('bad stuff happened'));
+     *     },
+     *     function(callback) {
+     *         setTimeout(function() {
+     *             callback(null, 'two');
+     *         }, 100);
+     *     }
+     * ];
+     *
+     * async.parallel(async.reflectAll(tasks),
+     * // optional callback
+     * function(err, results) {
+     *     // values
+     *     // results[0].value = 'one'
+     *     // results[1].error = Error('bad stuff happened')
+     *     // results[2].value = 'two'
+     * });
+     */
     function reflectAll(tasks) {
-        return tasks.map(reflect);
+      return tasks.map(reflect);
     }
 
+    /**
+     * The same as `reject` but runs only a single async operation at a time.
+     *
+     * @name rejectSeries
+     * @static
+     * @memberOf async
+     * @see async.reject
+     * @category Collection
+     * @param {Array|Object} coll - A collection to iterate over.
+     * @param {Function} iteratee - A truth test to apply to each item in `coll`.
+     * The `iteratee` is passed a `callback(err, truthValue)`, which must be called
+     * with a boolean argument once it has completed. Invoked with (item, callback).
+     * @param {Function} [callback] - A callback which is called after all the
+     * `iteratee` functions have finished. Invoked with (err, results).
+     */
     var rejectSeries = doLimit(rejectLimit, 1);
 
+    /**
+     * Run the functions in the `tasks` collection in series, each one running once
+     * the previous function has completed. If any functions in the series pass an
+     * error to its callback, no more functions are run, and `callback` is
+     * immediately called with the value of the error. Otherwise, `callback`
+     * receives an array of results when `tasks` have completed.
+     *
+     * It is also possible to use an object instead of an array. Each property will
+     * be run as a function, and the results will be passed to the final `callback`
+     * as an object instead of an array. This can be a more readable way of handling
+     *  results from {@link async.series}.
+     *
+     * **Note** that while many implementations preserve the order of object
+     * properties, the [ECMAScript Language Specification](http://www.ecma-international.org/ecma-262/5.1/#sec-8.6)
+     * explicitly states that
+     *
+     * > The mechanics and order of enumerating the properties is not specified.
+     *
+     * So if you rely on the order in which your series of functions are executed,
+     * and want this to work on all platforms, consider using an array.
+     *
+     * @name series
+     * @static
+     * @memberOf async
+     * @category Control Flow
+     * @param {Array|Object} tasks - A collection containing functions to run, each
+     * function is passed a `callback(err, result)` it must call on completion with
+     * an error `err` (which can be `null`) and an optional `result` value.
+     * @param {Function} [callback] - An optional callback to run once all the
+     * functions have completed. This function gets a results array (or object)
+     * containing all the result arguments passed to the `task` callbacks. Invoked
+     * with (err, result).
+     * @example
+     * async.series([
+     *     function(callback) {
+     *         // do some stuff ...
+     *         callback(null, 'one');
+     *     },
+     *     function(callback) {
+     *         // do some more stuff ...
+     *         callback(null, 'two');
+     *     }
+     * ],
+     * // optional callback
+     * function(err, results) {
+     *     // results is now equal to ['one', 'two']
+     * });
+     *
+     * async.series({
+     *     one: function(callback) {
+     *         setTimeout(function() {
+     *             callback(null, 1);
+     *         }, 200);
+     *     },
+     *     two: function(callback){
+     *         setTimeout(function() {
+     *             callback(null, 2);
+     *         }, 100);
+     *     }
+     * }, function(err, results) {
+     *     // results is now equal to: {one: 1, two: 2}
+     * });
+     */
     function series(tasks, cb) {
-        return _parallel(eachOfSeries, tasks, cb);
+      return _parallel(eachOfSeries, tasks, cb);
     }
 
+    /**
+     * Attempts to get a successful response from `task` no more than `times` times
+     * before returning an error. If the task is successful, the `callback` will be
+     * passed the result of the successful task. If all attempts fail, the callback
+     * will be passed the error and result (if any) of the final attempt.
+     *
+     * @name retry
+     * @static
+     * @memberOf async
+     * @category Control Flow
+     * @param {Object|number} [opts = {times: 5, interval: 0}| 5] - Can be either an
+     * object with `times` and `interval` or a number.
+     * * `times` - The number of attempts to make before giving up.  The default
+     *   is `5`.
+     * * `interval` - The time to wait between retries, in milliseconds.  The
+     *   default is `0`.
+     * * If `opts` is a number, the number specifies the number of times to retry,
+     *   with the default interval of `0`.
+     * @param {Function} task - A function which receives two arguments: (1) a
+     * `callback(err, result)` which must be called when finished, passing `err`
+     * (which can be `null`) and the `result` of the function's execution, and (2)
+     * a `results` object, containing the results of the previously executed
+     * functions (if nested inside another control flow). Invoked with
+     * (callback, results).
+     * @param {Function} [callback] - An optional callback which is called when the
+     * task has succeeded, or after the final failed attempt. It receives the `err`
+     * and `result` arguments of the last attempt at completing the `task`. Invoked
+     * with (err, results).
+     * @example
+     *
+     * // The `retry` function can be used as a stand-alone control flow by passing
+     * // a callback, as shown below:
+     *
+     * // try calling apiMethod 3 times
+     * async.retry(3, apiMethod, function(err, result) {
+     *     // do something with the result
+     * });
+     *
+     * // try calling apiMethod 3 times, waiting 200 ms between each retry
+     * async.retry({times: 3, interval: 200}, apiMethod, function(err, result) {
+     *     // do something with the result
+     * });
+     *
+     *  // try calling apiMethod the default 5 times no delay between each retry
+     * async.retry(apiMethod, function(err, result) {
+     *     // do something with the result
+     * });
+     *
+     * // It can also be embedded within other control flow functions to retry
+     * // individual methods that are not as reliable, like this:
+     * async.auto({
+     *     users: api.getUsers.bind(api),
+     *     payments: async.retry(3, api.getPayments.bind(api))
+     * }, function(err, results) {
+     *     // do something with the results
+     * });
+     */
     function retry(times, task, callback) {
         var DEFAULT_TIMES = 5;
         var DEFAULT_INTERVAL = 0;
@@ -3769,6 +5619,29 @@
         }
     }
 
+    /**
+     * A close relative of `retry`.  This method wraps a task and makes it
+     * retryable, rather than immediately calling it with retries.
+     *
+     * @name retryable
+     * @static
+     * @memberOf async
+     * @see async.retry
+     * @category Control Flow
+     * @param {Object|number} [opts = {times: 5, interval: 0}| 5] - optional
+     * options, exactly the same as from `retry`
+     * @param {Function} task - the asynchronous function to wrap
+     * @returns {Functions} The wrapped function, which when invoked, will retry on
+     * an error, based on the parameters specified in `opts`.
+     * @example
+     *
+     * async.auto({
+     *     dep1: async.retryable(3, getFromFlakyService),
+     *     process: ["dep1", async.retryable(3, function (results, cb) {
+     *         maybeProcessData(results.dep1, cb);
+     *     })]
+     * }, callback);
+     */
     function retryable (opts, task) {
         if (!task) {
             task = opts;
@@ -3783,12 +5656,125 @@
         });
     }
 
+    /**
+     * The same as `some` but runs a maximum of `limit` async operations at a time.
+     *
+     * @name someLimit
+     * @static
+     * @memberOf async
+     * @see async.some
+     * @alias anyLimit
+     * @category Collection
+     * @param {Array|Object} coll - A collection to iterate over.
+     * @param {number} limit - The maximum number of async operations at a time.
+     * @param {Function} iteratee - A truth test to apply to each item in the array
+     * in parallel. The iteratee is passed a `callback(err, truthValue)` which must
+     * be called with a boolean argument once it has completed. Invoked with
+     * (item, callback).
+     * @param {Function} [callback] - A callback which is called as soon as any
+     * iteratee returns `true`, or after all the iteratee functions have finished.
+     * Result will be either `true` or `false` depending on the values of the async
+     * tests. Invoked with (err, result).
+     */
     var someLimit = _createTester(eachOfLimit, Boolean, identity);
 
+    /**
+     * Returns `true` if at least one element in the `coll` satisfies an async test.
+     * If any iteratee call returns `true`, the main `callback` is immediately
+     * called.
+     *
+     * @name some
+     * @static
+     * @memberOf async
+     * @alias any
+     * @category Collection
+     * @param {Array|Object} coll - A collection to iterate over.
+     * @param {Function} iteratee - A truth test to apply to each item in the array
+     * in parallel. The iteratee is passed a `callback(err, truthValue)` which must
+     * be called with a boolean argument once it has completed. Invoked with
+     * (item, callback).
+     * @param {Function} [callback] - A callback which is called as soon as any
+     * iteratee returns `true`, or after all the iteratee functions have finished.
+     * Result will be either `true` or `false` depending on the values of the async
+     * tests. Invoked with (err, result).
+     * @example
+     *
+     * async.some(['file1','file2','file3'], function(filePath, callback) {
+     *     fs.access(filePath, function(err) {
+     *         callback(null, !err)
+     *     });
+     * }, function(err, result) {
+     *     // if result is true then at least one of the files exists
+     * });
+     */
     var some = doLimit(someLimit, Infinity);
 
+    /**
+     * The same as `some` but runs only a single async operation at a time.
+     *
+     * @name someSeries
+     * @static
+     * @memberOf async
+     * @see async.some
+     * @alias anySeries
+     * @category Collection
+     * @param {Array|Object} coll - A collection to iterate over.
+     * @param {Function} iteratee - A truth test to apply to each item in the array
+     * in parallel. The iteratee is passed a `callback(err, truthValue)` which must
+     * be called with a boolean argument once it has completed. Invoked with
+     * (item, callback).
+     * @param {Function} [callback] - A callback which is called as soon as any
+     * iteratee returns `true`, or after all the iteratee functions have finished.
+     * Result will be either `true` or `false` depending on the values of the async
+     * tests. Invoked with (err, result).
+     */
     var someSeries = doLimit(someLimit, 1);
 
+    /**
+     * Sorts a list by the results of running each `coll` value through an async
+     * `iteratee`.
+     *
+     * @name sortBy
+     * @static
+     * @memberOf async
+     * @category Collection
+     * @param {Array|Object} coll - A collection to iterate over.
+     * @param {Function} iteratee - A function to apply to each item in `coll`.
+     * The iteratee is passed a `callback(err, sortValue)` which must be called once
+     * it has completed with an error (which can be `null`) and a value to use as
+     * the sort criteria. Invoked with (item, callback).
+     * @param {Function} [callback] - A callback which is called after all the
+     * `iteratee` functions have finished, or an error occurs. Results is the items
+     * from the original `coll` sorted by the values returned by the `iteratee`
+     * calls. Invoked with (err, results).
+     * @example
+     *
+     * async.sortBy(['file1','file2','file3'], function(file, callback) {
+     *     fs.stat(file, function(err, stats) {
+     *         callback(err, stats.mtime);
+     *     });
+     * }, function(err, results) {
+     *     // results is now the original array of files sorted by
+     *     // modified date
+     * });
+     *
+     * // By modifying the callback parameter the
+     * // sorting order can be influenced:
+     *
+     * // ascending order
+     * async.sortBy([1,9,3,5], function(x, callback) {
+     *     callback(null, x);
+     * }, function(err,result) {
+     *     // result callback
+     * });
+     *
+     * // descending order
+     * async.sortBy([1,9,3,5], function(x, callback) {
+     *     callback(null, x*-1);    //<- x*-1 instead of x, turns the order around
+     * }, function(err,result) {
+     *     // result callback
+     * });
+     */
     function sortBy(arr, iteratee, cb) {
         map(arr, function (x, cb) {
             iteratee(x, function (err, criteria) {
@@ -3807,6 +5793,28 @@
         }
     }
 
+    /**
+     * Sets a time limit on an asynchronous function. If the function does not call
+     * its callback within the specified miliseconds, it will be called with a
+     * timeout error. The code property for the error object will be `'ETIMEDOUT'`.
+     *
+     * @name timeout
+     * @static
+     * @memberOf async
+     * @category Util
+     * @param {Function} function - The asynchronous function you want to set the
+     * time limit.
+     * @param {number} miliseconds - The specified time limit.
+     * @param {*} [info] - Any variable you want attached (`string`, `object`, etc)
+     * to timeout Error for more information..
+     * @returns {Function} Returns a wrapped function that can be used with any of
+     * the control flow functions.
+     * @example
+     *
+     * async.timeout(function(callback) {
+     *     doAsyncTask(callback);
+     * }, 1000);
+     */
     function timeout(asyncFn, miliseconds, info) {
         var originalCallback, timer;
         var timedOut = false;
@@ -3863,40 +5871,232 @@
       return result;
     }
 
+    /**
+    * The same as {@link times} but runs a maximum of `limit` async operations at a
+    * time.
+     *
+     * @name timesLimit
+     * @static
+     * @memberOf async
+     * @see async.times
+     * @category Control Flow
+     * @param {number} n - The number of times to run the function.
+     * @param {number} limit - The maximum number of async operations at a time.
+     * @param {Function} iteratee - The function to call `n` times. Invoked with the
+     * iteration index and a callback (n, next).
+     * @param {Function} callback - see {@link async.map}.
+     */
     function timeLimit(count, limit, iteratee, cb) {
-        return mapLimit(baseRange(0, count, 1), limit, iteratee, cb);
+      return mapLimit(baseRange(0, count, 1), limit, iteratee, cb);
     }
 
+    /**
+     * Calls the `iteratee` function `n` times, and accumulates results in the same
+     * manner you would use with {@link async.map}.
+     *
+     * @name times
+     * @static
+     * @memberOf async
+     * @see async.map
+     * @category Control Flow
+     * @param {number} n - The number of times to run the function.
+     * @param {Function} iteratee - The function to call `n` times. Invoked with the
+     * iteration index and a callback (n, next).
+     * @param {Function} callback - see {@link async.map}.
+     * @example
+     *
+     * // Pretend this is some complicated async factory
+     * var createUser = function(id, callback) {
+     *     callback(null, {
+     *         id: 'user' + id
+     *     });
+     * };
+     *
+     * // generate 5 users
+     * async.times(5, function(n, next) {
+     *     createUser(n, function(err, user) {
+     *         next(err, user);
+     *     });
+     * }, function(err, users) {
+     *     // we should now have 5 users
+     * });
+     */
     var times = doLimit(timeLimit, Infinity);
 
+    /**
+     * The same as {@link async.times} but runs only a single async operation at a time.
+     *
+     * @name timesSeries
+     * @static
+     * @memberOf async
+     * @see async.times
+     * @category Control Flow
+     * @param {number} n - The number of times to run the function.
+     * @param {Function} iteratee - The function to call `n` times. Invoked with the
+     * iteration index and a callback (n, next).
+     * @param {Function} callback - see {@link async.map}.
+     */
     var timesSeries = doLimit(timeLimit, 1);
 
-    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}
+     * })
+     */
+    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);
         });
     }
 
+    /**
+     * Undoes a {@link async.memoize}d function, reverting it to the original,
+     * unmemoized form. Handy for testing.
+     *
+     * @name unmemoize
+     * @static
+     * @memberOf async
+     * @see async.memoize
+     * @category Util
+     * @param {Function} fn - the memoized function
+     */
+
     function unmemoize(fn) {
         return function () {
             return (fn.unmemoized || fn).apply(null, arguments);
         };
     }
 
+    /**
+     * Repeatedly call `fn` until `test` returns `true`. Calls `callback` when
+     * stopped, or an error occurs. `callback` will be passed an error and any
+     * arguments passed to the final `fn`'s callback.
+     *
+     * The inverse of {@link async.whilst}.
+     *
+     * @name until
+     * @static
+     * @memberOf async
+     * @see async.whilst
+     * @category Control Flow
+     * @param {Function} test - synchronous truth test to perform before each
+     * execution of `fn`. Invoked with ().
+     * @param {Function} fn - A function which is called each time `test` fails.
+     * The function is passed a `callback(err)`, which must be called once it has
+     * completed with an optional `err` argument. Invoked with (callback).
+     * @param {Function} [callback] - A callback which is called after the test
+     * function has passed and repeated execution of `fn` has stopped. `callback`
+     * will be passed an error and any arguments passed to the final `fn`'s
+     * callback. Invoked with (err, [results]);
+     */
     function until(test, iteratee, cb) {
         return whilst(function () {
             return !test.apply(this, arguments);
         }, iteratee, cb);
     }
 
+    /**
+     * Runs the `tasks` array of functions in series, each passing their results to
+     * the next in the array. However, if any of the `tasks` pass an error to their
+     * own callback, the next function is not executed, and the main `callback` is
+     * immediately called with the error.
+     *
+     * @name waterfall
+     * @static
+     * @memberOf async
+     * @category Control Flow
+     * @param {Array} tasks - An array of functions to run, each function is passed
+     * a `callback(err, result1, result2, ...)` it must call on completion. The
+     * first argument is an error (which can be `null`) and any further arguments
+     * will be passed as arguments in order to the next task.
+     * @param {Function} [callback] - An optional callback to run once all the
+     * functions have completed. This will be passed the results of the last task's
+     * callback. Invoked with (err, [results]).
+     * @example
+     *
+     * async.waterfall([
+     *     function(callback) {
+     *         callback(null, 'one', 'two');
+     *     },
+     *     function(arg1, arg2, callback) {
+     *         // arg1 now equals 'one' and arg2 now equals 'two'
+     *         callback(null, 'three');
+     *     },
+     *     function(arg1, callback) {
+     *         // arg1 now equals 'three'
+     *         callback(null, 'done');
+     *     }
+     * ], function (err, result) {
+     *     // result now equals 'done'
+     * });
+     *
+     * // Or, with named functions:
+     * async.waterfall([
+     *     myFirstFunction,
+     *     mySecondFunction,
+     *     myLastFunction,
+     * ], function (err, result) {
+     *     // result now equals 'done'
+     * });
+     * function myFirstFunction(callback) {
+     *     callback(null, 'one', 'two');
+     * }
+     * function mySecondFunction(arg1, arg2, callback) {
+     *     // arg1 now equals 'one' and arg2 now equals 'two'
+     *     callback(null, 'three');
+     * }
+     * function myLastFunction(arg1, callback) {
+     *     // arg1 now equals 'three'
+     *     callback(null, 'done');
+     * }
+     */
     function waterfall (tasks, cb) {
         cb = once(cb || noop);
         if (!isArray(tasks)) return cb(new Error('First argument to waterfall must be an array of functions'));