add docs

3 files changed, 78 insertions, 0 deletions

diff --git a/lib/mapValues.js b/lib/mapValues.js
index 60b8235..83ffc43 100644
--- a/lib/mapValues.js
+++ b/lib/mapValues.js
@@ -1,4 +1,46 @@
 import mapValuesLimit from './mapValuesLimit';
 import doLimit from './internal/doLimit';
 
+
+/**
+ * A relative of `map`, designed for use with objects.
+ *
+ * Produces a new Object by mapping each value of `obj` through the `iteratee`
+ * function. The `iteratee` is called each `value` and `key` from `obj` and a
+ * callback for when it has finished processing. Each of these callbacks takes
+ * two arguments: an `error`, and the transformed item from `obj`. If `iteratee`
+ * passes an error to its callback, the main `callback` (for the `mapValues`
+ * function) is immediately called with the error.
+ *
+ * Note, the order of the keys in the result is not guaranteed.  The keys will
+ * be roughly in the order they complete, (but this is very engine-specific)
+ *
+ * @name mapValues
+ * @static
+ * @memberOf async
+ * @category Collection
+ * @param {Object} obj - A collection to iterate over.
+ * @param {Function} iteratee - A function to apply to each value and key 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 value. Invoked with (value, key, 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 `obj`. Invoked with (err, result).
+ * @example
+ *
+ * async.mapValues({
+ *     f1: 'file1',
+ *     f2: 'file2',
+ *     f3: 'file3'
+ * }, fs.stat, function(err, result) {
+ *     // results is now a map of stats for each file, e.g.
+ *     // {
+ *     //     f1: [stats for file1],
+ *     //     f2: [stats for file2],
+ *     //     f3: [stats for file3]
+ *     // }
+ * });
+ */
+
 export default doLimit(mapValuesLimit, Infinity);
diff --git a/lib/mapValuesLimit.js b/lib/mapValuesLimit.js
index f2698f0..a1a43a1 100644
--- a/lib/mapValuesLimit.js
+++ b/lib/mapValuesLimit.js
@@ -1,5 +1,24 @@
 import eachOfLimit from './eachOfLimit';
 
+/**
+ * The same as `mapValues` but runs a maximum of `limit` async operations at a
+ * time.
+ *
+ * @name mapValuesLimit
+ * @static
+ * @memberOf async
+ * @see async.mapValues
+ * @category Collection
+ * @param {Object} obj - 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 value in `obj`.
+ * 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 value. Invoked with (value, key, callback).
+ * @param {Function} [callback] - A callback which is called when all `iteratee`
+ * functions have finished, or an error occurs. Result is an object of the
+ * transformed values from the `obj`. Invoked with (err, result).
+ */
 export default function mapValuesLimit(obj, limit, iteratee, callback) {
     var newObj = {};
     eachOfLimit(obj, limit, function(val, key, next) {
diff --git a/lib/mapValuesSeries.js b/lib/mapValuesSeries.js
index f093a9e..163d474 100644
--- a/lib/mapValuesSeries.js
+++ b/lib/mapValuesSeries.js
@@ -1,4 +1,21 @@
 import mapValuesLimit from './mapValuesLimit';
 import doLimit from './internal/doLimit';
 
+/**
+ * The same as `mapValues` but runs only a single async operation at a time.
+ *
+ * @name mapValuesSeries
+ * @static
+ * @memberOf async
+ * @see async.mapValues
+ * @category Collection
+ * @param {Object} obj - A collection to iterate over.
+ * @param {Function} iteratee - A function to apply to each value in `obj`.
+ * 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 value. Invoked with (value, key, callback).
+ * @param {Function} [callback] - A callback which is called when all `iteratee`
+ * functions have finished, or an error occurs. Result is an object of the
+ * transformed values from the `obj`. Invoked with (err, result).
+ */
 export default doLimit(mapValuesLimit, 1);