jsdoc-style documentation began documenting `Util` methods

remaining `Util`  methods to document (10):
- ensureAsync
- constant
- asyncify
- wrapSync
- log
- dir
- noConflict
- timeout
- reflect
- reflectAll

8 files changed, 212 insertions, 0 deletions

diff --git a/lib/apply.js b/lib/apply.js
index 76b5602..0c3c33d 100644
--- a/lib/apply.js
+++ b/lib/apply.js
@@ -2,6 +2,49 @@
 
 import rest from 'lodash/rest';
 
+/**
+ * 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
+ */
 export default rest(function(fn, args) {
     return rest(function(callArgs) {
         return fn.apply(null, args.concat(callArgs));
diff --git a/lib/memoize.js b/lib/memoize.js
index d1af636..955f709 100644
--- a/lib/memoize.js
+++ b/lib/memoize.js
@@ -10,6 +10,41 @@ 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
+ * });
+ */
 export default function memoize(fn, hasher) {
     var memo = Object.create(null);
     var queues = Object.create(null);
diff --git a/lib/nextTick.js b/lib/nextTick.js
index 05d9555..249bec2 100644
--- a/lib/nextTick.js
+++ b/lib/nextTick.js
@@ -2,4 +2,34 @@
 
 import setImmediate from './internal/setImmediate';
 
+/**
+ * Calls `callback` on a later loop around the event loop. In Node.js this just
+ * calls `setImmediate`.  In the browser it will use `setImmediate` if
+ * available, otherwise `setTimeout(callback, 0)`, which means other higher
+ * priority events may precede the execution of `callback`.
+ *
+ * This is used internally for browser-compatibility purposes.
+ *
+ * @name nextTick
+ * @static
+ * @memberOf async
+ * @alias setImmediate
+ * @category Util
+ * @param {Function} callback - The function to call on a later loop around
+ * the event loop. Invoked with (args...).
+ * @param {...*} args... - any number of additional arguments to pass to the
+ * callback on the next tick.
+ * @example
+ *
+ * var call_order = [];
+ * async.nextTick(function() {
+ *     call_order.push('two');
+ *     // call_order now equals ['one','two']
+ * });
+ * call_order.push('one');
+ *
+ * async.setImmediate(function (a, b, c) {
+ *     // a, b, and c equal 1, 2, and 3
+ * }, 1, 2, 3);
+ */
 export default setImmediate;
diff --git a/lib/race.js b/lib/race.js
index b89a5db..b12b2e7 100644
--- a/lib/race.js
+++ b/lib/race.js
@@ -5,6 +5,41 @@ import each from 'lodash/each';
 import noop from 'lodash/noop';
 import once from './internal/once';
 
+/**
+ * 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 Util
+ * @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
+ * });
+ */
 export default 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'));
diff --git a/lib/times.js b/lib/times.js
index 2cbd230..a81ba3b 100644
--- a/lib/times.js
+++ b/lib/times.js
@@ -3,4 +3,34 @@
 import timesLimit from './timesLimit';
 import doLimit from './internal/doLimit';
 
+/**
+ * Calls the `iteratee` function `n` times, and accumulates results in the same
+ * manner you would use with [`map`](#map).
+ *
+ * @name times
+ * @static
+ * @memberOf async
+ * @see `async.map`
+ * @category Util
+ * @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 [`map`](#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
+ * });
+ */
 export default doLimit(timesLimit, Infinity);
diff --git a/lib/timesLimit.js b/lib/timesLimit.js
index dbd9664..73ae4d1 100644
--- a/lib/timesLimit.js
+++ b/lib/timesLimit.js
@@ -3,6 +3,21 @@
 import mapLimit from './mapLimit';
 import range from 'lodash/_baseRange';
 
+/**
+* The same as `times` but runs a maximum of `limit` async operations at a
+* time.
+ *
+ * @name timesLimit
+ * @static
+ * @memberOf async
+ * @see `async.times`
+ * @category Util
+ * @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 [`map`](#map).
+ */
 export default function timeLimit(count, limit, iteratee, cb) {
     return mapLimit(range(0, count, 1), limit, iteratee, cb);
 }
diff --git a/lib/timesSeries.js b/lib/timesSeries.js
index af2219b..dd2ad45 100644
--- a/lib/timesSeries.js
+++ b/lib/timesSeries.js
@@ -3,4 +3,17 @@
 import timesLimit from './timesLimit';
 import doLimit from './internal/doLimit';
 
+/**
+ * The same as `times` but runs only a single async operation at a time.
+ *
+ * @name timesSeries
+ * @static
+ * @memberOf async
+ * @see `async.times`
+ * @category Util
+ * @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 [`map`](#map).
+ */
 export default doLimit(timesLimit, 1);
diff --git a/lib/unmemoize.js b/lib/unmemoize.js
index d652e7b..e7f0941 100644
--- a/lib/unmemoize.js
+++ b/lib/unmemoize.js
@@ -1,5 +1,16 @@
 'use strict';
 
+/**
+ * Undoes a [`memoize`](#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
+ */
 export default  function unmemoize(fn) {
     return function () {
         return (fn.unmemoized || fn).apply(null, arguments);