clarify AsyncFunction docs

2 files changed, 11 insertions, 7 deletions

diff --git a/lib/asyncify.js b/lib/asyncify.js
index 61794fb..1f0955e 100644
--- a/lib/asyncify.js
+++ b/lib/asyncify.js
@@ -12,7 +12,7 @@ import initialParams from './internal/initialParams';
  * resolved/rejected state will be used to call the callback, rather than simply
  * the synchronous return value.
  *
- * This also means you can asyncify ES2016 `async` functions.
+ * This also means you can asyncify ES2017 `async` functions.
  *
  * @name asyncify
  * @static
@@ -48,7 +48,8 @@ import initialParams from './internal/initialParams';
  *     }
  * ], callback);
  *
- * // es2017 example
+ * // es2017 example, though `asyncify` is not needed if your JS environment
+ * // supports async functions out of the box
  * var q = async.queue(async.asyncify(async function(file) {
  *     var intermediateStep = await processFile(file);
  *     return await somePromise(intermediateStep)
diff --git a/lib/index.js b/lib/index.js
index 39657d5..0fbeefc 100644
--- a/lib/index.js
+++ b/lib/index.js
@@ -13,12 +13,15 @@
  * 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.
+ * [ES2017 `async` function]{@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/async_function}.
+ * In this case, the `async` function will not be passed a final callback
+ * argument, and any thrown error will be used as the `err` argument of the
+ * implicit callback, and the return value will be used as the `result` value.
+ * (i.e. a `rejected` of the returned Promise becomes the `err` callback
+ * argument, and a `resolved` value becomes the `result`.)
  *
- * Note that we can only detect native `async function`s in this case.
+ * Note, due to JavaScript limitations, we can only detect native `async`
+ * functions and not transpilied implementations.
  * 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