jsdoc-style documentation began documenting `Control Flow` methods

remaining `Control Flow` methods to document:
- queue
- priorityQueue
- cargo
- auto
- autoInject
- retry
- retryable
- iterator
- times, timesSeries, timesLimit
- race

1 files changed, 28 insertions, 0 deletions

diff --git a/lib/forever.js b/lib/forever.js
index 82d004a..23f261b 100644
--- a/lib/forever.js
+++ b/lib/forever.js
@@ -5,6 +5,34 @@ import noop from 'lodash/noop';
 import onlyOnce from './internal/onlyOnce';
 import ensureAsync from './ensureAsync';
 
+/**
+ * Calls the asynchronous function `fn` with a callback parameter that allows it
+ * to call itself again, in series, indefinitely.
+
+ * If an error is passed to the
+ * callback then `errback` is called with the error, and execution stops,
+ * otherwise it will never be called.
+ *
+ * @name forever
+ * @static
+ * @memberOf async
+ * @category Control Flow
+ * @param {Function} fn - a function to call repeatedly. Invoked with (next).
+ * @param {Function} [errback] - when `fn` passes an error to it's callback,
+ * this function will be called, and execution stops. Invoked with (err).
+ * @example
+ *
+ * async.forever(
+ *     function(next) {
+ *         // next is suitable for passing to things that need a callback(err [, whatever]);
+ *         // it will result in this function being called again.
+ *     },
+ *     function(err) {
+ *         // if next is called with a value in its first parameter, it will appear
+ *         // in here as 'err', and execution will stop.
+ *     }
+ * );
+ */
 export default function forever(fn, cb) {
     var done = onlyOnce(cb || noop);
     var task = ensureAsync(fn);