jsdoc-style documentation finished documenting `Util` methods

need to rebase to master before I can document the recently added
reflect functions

jsdoc-style documentation finished for 'Util' methods

documented the new `reflect` and `reflectAll` functions

8 files changed, 280 insertions, 0 deletions

diff --git a/lib/asyncify.js b/lib/asyncify.js
index cf392e9..98ff5ce 100644
--- a/lib/asyncify.js
+++ b/lib/asyncify.js
@@ -3,6 +3,60 @@
 import isObject from 'lodash/isObject';
 import initialParams from './internal/initialParams';
 
+/**
+ * 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);
+ */
 export default function asyncify(func) {
     return initialParams(function (args, callback) {
         var result;
diff --git a/lib/constant.js b/lib/constant.js
index 133b244..350a905 100644
--- a/lib/constant.js
+++ b/lib/constant.js
@@ -3,6 +3,47 @@
 import rest from 'lodash/rest';
 import initialParams from './internal/initialParams';
 
+/**
+ * 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);
+ */
 export default rest(function(values) {
     var args = [null].concat(values);
     return initialParams(function (ignoredArgs, callback) {
diff --git a/lib/dir.js b/lib/dir.js
index 049b416..71425dc 100644
--- a/lib/dir.js
+++ b/lib/dir.js
@@ -2,4 +2,31 @@
 
 import consoleFunc from './internal/consoleFunc';
 
+/**
+ * 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'}
+ */
 export default consoleFunc('dir');
diff --git a/lib/ensureAsync.js b/lib/ensureAsync.js
index 091f3ae..62bb5ef 100644
--- a/lib/ensureAsync.js
+++ b/lib/ensureAsync.js
@@ -3,6 +3,39 @@
 import setImmediate from './internal/setImmediate';
 import initialParams from './internal/initialParams';
 
+/**
+ * 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);
+ */
 export default function ensureAsync(fn) {
     return initialParams(function (args, callback) {
         var sync = true;
diff --git a/lib/log.js b/lib/log.js
index b581264..b6eb7f7 100644
--- a/lib/log.js
+++ b/lib/log.js
@@ -2,4 +2,30 @@
 
 import consoleFunc from './internal/consoleFunc';
 
+/**
+ * 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'
+ */
 export default consoleFunc('log');
diff --git a/lib/reflect.js b/lib/reflect.js
index 2711254..a4c3ac6 100644
--- a/lib/reflect.js
+++ b/lib/reflect.js
@@ -1,6 +1,44 @@
 import initialParams from './internal/initialParams';
 import rest from 'lodash/rest';
 
+/**
+ * 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'
+ * });
+ */
 export default function reflect(fn) {
     return initialParams(function reflectOn(args, reflectCallback) {
         args.push(rest(function callback(err, cbArgs) {
diff --git a/lib/reflectAll.js b/lib/reflectAll.js
index c4ecd9f..2a0f197 100644
--- a/lib/reflectAll.js
+++ b/lib/reflectAll.js
@@ -2,6 +2,45 @@
 
 import reflect from './reflect';
 
+/**
+ * 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'
+ * });
+ */
 export default function reflectAll(tasks) {
     return tasks.map(reflect);
 }
diff --git a/lib/timeout.js b/lib/timeout.js
index ebf0446..f6f3893 100644
--- a/lib/timeout.js
+++ b/lib/timeout.js
@@ -2,6 +2,28 @@
 
 import initialParams from './internal/initialParams';
 
+/**
+ * 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);
+ */
 export default function timeout(asyncFn, miliseconds, info) {
     var originalCallback, timer;
     var timedOut = false;