jsdoc-style documentation for 'collection' methods

Converted documentation from README to jsdoc-style for respective
methods. Currently, only done for 'collection' methods.

jsdoc-style documentation - fixed 'collection' methods documentation

Only the base functions now contain an example, while the `series` and
`limit` versions simply contain a reference to the base function. Fixed
styling issue and misspelled tag.

29 files changed, 712 insertions, 1 deletions

diff --git a/lib/concat.js b/lib/concat.js
index af019a3..176cb97 100644
--- a/lib/concat.js
+++ b/lib/concat.js
@@ -3,4 +3,30 @@
 import concat from './internal/concat';
 import doParallel from './internal/doParallel';
 
+/**
+ * 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
+ * });
+ */
 export default doParallel(concat);
diff --git a/lib/concatSeries.js b/lib/concatSeries.js
index 76f4043..73312dc 100644
--- a/lib/concatSeries.js
+++ b/lib/concatSeries.js
@@ -3,4 +3,22 @@
 import concat from './internal/concat';
 import doSeries from './internal/doSeries';
 
+/**
+ * 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).
+ */
 export default doSeries(concat);
diff --git a/lib/detect.js b/lib/detect.js
index b2c4778..0b06374 100644
--- a/lib/detect.js
+++ b/lib/detect.js
@@ -6,4 +6,38 @@ import createTester from './internal/createTester';
 import eachOf from './eachOf';
 import findGetResult from './internal/findGetResult';
 
+/**
+ * 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
+ * });
+ */
 export default createTester(eachOf, identity, findGetResult);
diff --git a/lib/detectLimit.js b/lib/detectLimit.js
index 357786d..20c8040 100644
--- a/lib/detectLimit.js
+++ b/lib/detectLimit.js
@@ -6,4 +6,25 @@ import createTester from './internal/createTester';
 import eachOfLimit from './eachOfLimit';
 import findGetResult from './internal/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).
+ */
 export default createTester(eachOfLimit, identity, findGetResult);
diff --git a/lib/detectSeries.js b/lib/detectSeries.js
index 325a500..659d820 100644
--- a/lib/detectSeries.js
+++ b/lib/detectSeries.js
@@ -6,4 +6,23 @@ import createTester from './internal/createTester';
 import eachOfSeries from './eachOfSeries';
 import findGetResult from './internal/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).
+ */
 export default createTester(eachOfSeries, identity, findGetResult);
diff --git a/lib/each.js b/lib/each.js
index d81763a..f2c9929 100644
--- a/lib/each.js
+++ b/lib/each.js
@@ -3,4 +3,62 @@
 import eachLimit from './eachLimit';
 import doLimit from './internal/doLimit';
 
+/**
+ * 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');
+ *     }
+ * });
+ */
 export default doLimit(eachLimit, Infinity);
diff --git a/lib/eachLimit.js b/lib/eachLimit.js
index 74965a8..415e6e8 100644
--- a/lib/eachLimit.js
+++ b/lib/eachLimit.js
@@ -3,7 +3,26 @@
 import eachOfLimit from './internal/eachOfLimit';
 import withoutIndex from './internal/withoutIndex';
 
-
+/**
+ * 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).
+ */
 export default function eachLimit(arr, limit, iteratee, cb) {
     return eachOfLimit(limit)(arr, withoutIndex(iteratee), cb);
 }
diff --git a/lib/eachOf.js b/lib/eachOf.js
index d16e1b3..5bb82e4 100644
--- a/lib/eachOf.js
+++ b/lib/eachOf.js
@@ -3,4 +3,43 @@
 import eachOfLimit from './eachOfLimit';
 import doLimit from './internal/doLimit';
 
+/**
+ * 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);
+ * });
+ */
 export default doLimit(eachOfLimit, Infinity);
diff --git a/lib/eachOfLimit.js b/lib/eachOfLimit.js
index b6ca139..753dbc0 100644
--- a/lib/eachOfLimit.js
+++ b/lib/eachOfLimit.js
@@ -2,6 +2,27 @@
 
 import _eachOfLimit from './internal/eachOfLimit';
 
+/**
+ * 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).
+ */
 export default function eachOfLimit(obj, limit, iteratee, cb) {
     _eachOfLimit(limit)(obj, iteratee, cb);
 }
diff --git a/lib/eachOfSeries.js b/lib/eachOfSeries.js
index 47787bb..0718805 100644
--- a/lib/eachOfSeries.js
+++ b/lib/eachOfSeries.js
@@ -3,4 +3,22 @@
 import eachOfLimit from './eachOfLimit';
 import doLimit from './internal/doLimit';
 
+/**
+ * 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).
+ */
 export default doLimit(eachOfLimit, 1);
diff --git a/lib/eachSeries.js b/lib/eachSeries.js
index 39dc81f..470c34c 100644
--- a/lib/eachSeries.js
+++ b/lib/eachSeries.js
@@ -3,4 +3,23 @@
 import eachLimit from './eachLimit';
 import doLimit from './internal/doLimit';
 
+/**
+ * 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).
+ */
 export default doLimit(eachLimit, 1);
diff --git a/lib/every.js b/lib/every.js
index b2d2abd..df28b00 100644
--- a/lib/every.js
+++ b/lib/every.js
@@ -3,4 +3,31 @@
 import everyLimit from './everyLimit';
 import doLimit from './internal/doLimit';
 
+/**
+ * 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
+ * });
+ */
 export default doLimit(everyLimit, Infinity);
diff --git a/lib/everyLimit.js b/lib/everyLimit.js
index 4b3fc5f..1c3511c 100644
--- a/lib/everyLimit.js
+++ b/lib/everyLimit.js
@@ -4,4 +4,23 @@ import createTester from './internal/createTester';
 import eachOfLimit from './eachOfLimit';
 import notId from './internal/notId';
 
+/**
+ * The same as `every` but runs a maximum of `limit` async operations at a time.
+ *
+ * @name everyLimit
+ * @static
+ * @memberOf async
+ * @see 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).
+ */
 export default createTester(eachOfLimit, notId, notId);
diff --git a/lib/everySeries.js b/lib/everySeries.js
index 0b3db2c..aca6cec 100644
--- a/lib/everySeries.js
+++ b/lib/everySeries.js
@@ -3,4 +3,22 @@
 import everyLimit from './everyLimit';
 import doLimit from './internal/doLimit';
 
+/**
+ * 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).
+ */
 export default doLimit(everyLimit, 1);
diff --git a/lib/filter.js b/lib/filter.js
index f3813d4..f350938 100644
--- a/lib/filter.js
+++ b/lib/filter.js
@@ -3,4 +3,30 @@
 import filterLimit from './filterLimit';
 import doLimit from './internal/doLimit';
 
+/**
+ * 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
+ * });
+ */
 export default doLimit(filterLimit, Infinity);
diff --git a/lib/filterLimit.js b/lib/filterLimit.js
index 8fe237f..414ea4d 100644
--- a/lib/filterLimit.js
+++ b/lib/filterLimit.js
@@ -3,4 +3,22 @@
 import filter from './internal/filter';
 import doParallelLimit from './internal/doParallelLimit';
 
+/**
+ * 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).
+ */
 export default doParallelLimit(filter);
diff --git a/lib/filterSeries.js b/lib/filterSeries.js
index d3995c9..97c3907 100644
--- a/lib/filterSeries.js
+++ b/lib/filterSeries.js
@@ -3,4 +3,20 @@
 import filterLimit from './filterLimit';
 import doLimit from './internal/doLimit';
 
+/**
+ * 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)
+ */
 export default doLimit(filterLimit, 1);
diff --git a/lib/map.js b/lib/map.js
index cb3f56d..b7ccdd4 100644
--- a/lib/map.js
+++ b/lib/map.js
@@ -3,4 +3,35 @@
 import mapLimit from './mapLimit';
 import doLimit from './internal/doLimit';
 
+/**
+ * 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
+ * });
+ */
 export default doLimit(mapLimit, Infinity);
diff --git a/lib/mapLimit.js b/lib/mapLimit.js
index 642b4c6..916b206 100644
--- a/lib/mapLimit.js
+++ b/lib/mapLimit.js
@@ -3,4 +3,22 @@
 import doParallelLimit from './internal/doParallelLimit';
 import map from './internal/map';
 
+/**
+ * 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).
+ */
 export default doParallelLimit(map);
diff --git a/lib/mapSeries.js b/lib/mapSeries.js
index 9a6bd11..efa2818 100644
--- a/lib/mapSeries.js
+++ b/lib/mapSeries.js
@@ -3,4 +3,21 @@
 import mapLimit from './mapLimit';
 import doLimit from './internal/doLimit';
 
+/**
+ * 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).
+ */
 export default doLimit(mapLimit, 1);
diff --git a/lib/reduce.js b/lib/reduce.js
index 675ed8f..2aa516b 100644
--- a/lib/reduce.js
+++ b/lib/reduce.js
@@ -2,6 +2,44 @@
 
 import eachOfSeries from './eachOfSeries';
 
+/**
+ * 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
+ * });
+ */
 export default function reduce(arr, memo, iteratee, cb) {
     eachOfSeries(arr, function(x, i, cb) {
         iteratee(memo, x, function(err, v) {
diff --git a/lib/reduceRight.js b/lib/reduceRight.js
index f79f18f..033b9da 100644
--- a/lib/reduceRight.js
+++ b/lib/reduceRight.js
@@ -4,6 +4,27 @@ import reduce from './reduce';
 
 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).
+ */
 export default function reduceRight (arr, memo, iteratee, cb) {
     var reversed = slice.call(arr).reverse();
     reduce(reversed, memo, iteratee, cb);
diff --git a/lib/reject.js b/lib/reject.js
index 970a0ec..f7f6f10 100644
--- a/lib/reject.js
+++ b/lib/reject.js
@@ -3,4 +3,29 @@
 import rejectLimit from './rejectLimit';
 import doLimit from './internal/doLimit';
 
+/**
+ * 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);
+ * });
+ */
 export default doLimit(rejectLimit, Infinity);
diff --git a/lib/rejectLimit.js b/lib/rejectLimit.js
index 7cefed6..9b3fbd3 100644
--- a/lib/rejectLimit.js
+++ b/lib/rejectLimit.js
@@ -3,4 +3,21 @@
 import reject from './internal/reject';
 import doParallelLimit from './internal/doParallelLimit';
 
+/**
+ * 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).
+ */
 export default doParallelLimit(reject);
diff --git a/lib/rejectSeries.js b/lib/rejectSeries.js
index 00c145f..1732eca 100644
--- a/lib/rejectSeries.js
+++ b/lib/rejectSeries.js
@@ -3,4 +3,19 @@
 import rejectLimit from './rejectLimit';
 import doLimit from './internal/doLimit';
 
+/**
+ * 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).
+ */
 export default doLimit(rejectLimit, 1);
diff --git a/lib/some.js b/lib/some.js
index 000f2e2..ccae178 100644
--- a/lib/some.js
+++ b/lib/some.js
@@ -3,4 +3,33 @@
 import someLimit from './someLimit';
 import doLimit from './internal/doLimit';
 
+/**
+ * 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
+ * });
+ */
 export default doLimit(someLimit, Infinity);
diff --git a/lib/someLimit.js b/lib/someLimit.js
index 498a262..521c116 100644
--- a/lib/someLimit.js
+++ b/lib/someLimit.js
@@ -4,4 +4,24 @@ import createTester from './internal/createTester';
 import eachOfLimit from './eachOfLimit';
 import identity from 'lodash/identity';
 
+/**
+ * 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).
+ */
 export default createTester(eachOfLimit, Boolean, identity);
diff --git a/lib/someSeries.js b/lib/someSeries.js
index a5fc97c..41ca733 100644
--- a/lib/someSeries.js
+++ b/lib/someSeries.js
@@ -3,4 +3,23 @@
 import someLimit from './someLimit';
 import doLimit from './internal/doLimit';
 
+/**
+ * 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).
+ */
 export default doLimit(someLimit, 1);
diff --git a/lib/sortBy.js b/lib/sortBy.js
index 8b78221..3e98bf0 100644
--- a/lib/sortBy.js
+++ b/lib/sortBy.js
@@ -5,6 +5,51 @@ import property from 'lodash/_baseProperty';
 
 import map from './map';
 
+/**
+ * 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
+ * });
+ */
 export default function sortBy (arr, iteratee, cb) {
     map(arr, function (x, cb) {
         iteratee(x, function (err, criteria) {