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

1 files changed, 38 insertions, 0 deletions

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) {