1 files changed, 39 insertions, 4 deletions
diff --git a/lib/index.js b/lib/index.js
index 0bb7efe..39657d5 100644
--- a/lib/index.js
+++ b/lib/index.js
@@ -1,11 +1,45 @@
 /**
+ * An "async function" in the context of Async is an asynchronous function with
+ * a variable number of parameters, with the final parameter being a callback.
+ * (`function (arg1, arg2, ..., callback) {}`)
+ * The final callback is of the form `callback(err, results...)`, which must be
+ * called once the function is completed.  The callback can be called with a
+ * Error as its first argument to signal that an error occurred.
+ * Otherwise, it can be called with `null` as the first argument, and any
+ * additional `result` arguments that may apply to signal successful completion.
+ * The callback must be called exactly once, ideally on a later tick of the
+ * JavaScript event loop.
+ *
+ * This type of function is also referred to as a "Node-style async function".
+ *
+ * Wherever we accept a Node-style async function, we also directly accept an
+ * ES2017 `async` function.
+ * In this case, the `async` function will not be passed a callback, and any
+ * thrown error will be used as the `err` argument of a theoretical callback,
+ * and the return value will be used as the `result` value.
+ *
+ * Note that we can only detect native `async function`s in this case.
+ * Your environment must have `async`/`await` support for this to work.
+ * (e.g. Node > v7.6, or a recent version of a modern browser).
+ * If you are using `async` functions through a transpiler (e.g. Babel), you
+ * must still wrap the function with [asyncify]{@link module:Utils.asyncify},
+ * because the `async function` will be compiled to an ordinary function that
+ * returns a promise.
+ *
+ * @typedef {Function} AsyncFunction
+ * @static
+ */
+
+/**
  * Async is a utility module which provides straight-forward, powerful functions
  * for working with asynchronous JavaScript. Although originally designed for
  * use with [Node.js](http://nodejs.org) and installable via
  * `npm install --save async`, it can also be used directly in the browser.
  * @module async
+ * @see AsyncFunction
  */
 
+
 /**
  * A collection of `async` functions for manipulating collections, such as
  * arrays and objects.
@@ -17,10 +51,11 @@
  * @module ControlFlow
  */
 
- /**
-  * A collection of `async` utility functions.
-  * @module Utils
-  */
+/**
+ * A collection of `async` utility functions.
+ * @module Utils
+ */
+
 import applyEach from './applyEach';
 import applyEachSeries from './applyEachSeries';
 import apply from './apply';