1 files changed, 32 insertions, 0 deletions
diff --git a/lib/compose.js b/lib/compose.js
index 9e92521..9c954d0 100644
--- a/lib/compose.js
+++ b/lib/compose.js
@@ -4,6 +4,38 @@ import seq from './seq';
 
 var reverse = Array.prototype.reverse;
 
+/**
+ * Creates a function which is a composition of the passed asynchronous
+ * functions. Each function consumes the return value of the function that
+ * follows. Composing functions `f()`, `g()`, and `h()` would produce the result
+ * of `f(g(h()))`, only this version uses callbacks to obtain the return values.
+ *
+ * Each function is executed with the `this` binding of the composed function.
+ *
+ * @name compose
+ * @static
+ * @memberOf async
+ * @category Control Flow
+ * @param {...Function} functions - the asynchronous functions to compose
+ * @example
+ *
+ * function add1(n, callback) {
+ *     setTimeout(function () {
+ *         callback(null, n + 1);
+ *     }, 10);
+ * }
+ *
+ * function mul3(n, callback) {
+ *     setTimeout(function () {
+ *         callback(null, n * 3);
+ *     }, 10);
+ * }
+ *
+ * var add1mul3 = async.compose(mul3, add1);
+ * add1mul3(4, function (err, result) {
+ *     // result now equals 15
+ * });
+ */
 export default function compose(/* functions... */) {
     return seq.apply(null, reverse.call(arguments));
 }