custom typedef doc test

2 files changed, 43 insertions, 10 deletions

diff --git a/lib/each.js b/lib/each.js
index e20b965..29f2baf 100644
--- a/lib/each.js
+++ b/lib/each.js
@@ -19,12 +19,10 @@ import wrapAsync from './internal/wrapAsync'
  * @alias forEach
  * @category Collection
  * @param {Array|Iterable|Object} coll - A collection to iterate over.
- * @param {Function} iteratee - A function to apply to each item
- * in `coll`. The iteratee is passed a `callback(err)` which must be called once
- * it has completed. If no error has occurred, the `callback` should be run
- * without arguments or with an explicit `null` argument. The array index is not
- * passed to the iteratee. Invoked with (item, callback). If you need the index,
- * use `eachOf`.
+ * @param {AsyncFunction} iteratee - An async function to apply to
+ * each item in `coll`. Invoked with (item, callback).
+ * The array index is not passed to the iteratee.
+ * If you need the index, use `eachOf`.
  * @param {Function} [callback] - A callback which is called when all
  * `iteratee` functions have finished, or an error occurs. Invoked with (err).
  * @example
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';