diff options
77 files changed, 575 insertions, 173 deletions
diff --git a/lib/apply.js b/lib/apply.js index 44f77e4..8c43e34 100644 --- a/lib/apply.js +++ b/lib/apply.js @@ -1,6 +1,9 @@ import rest from 'lodash/rest'; /** + * ``` + * import apply from 'async/apply' + * ``` * Creates a continuation function with some arguments already applied. * * Useful as a shorthand when combined with other control flow functions. Any @@ -9,7 +12,7 @@ import rest from 'lodash/rest'; * * @name apply * @static - * @memberOf module:async + * @memberOf module:Utils * @method * @category Util * @param {Function} function - The function you want to eventually apply all diff --git a/lib/applyEach.js b/lib/applyEach.js index c84430f..656014c 100644 --- a/lib/applyEach.js +++ b/lib/applyEach.js @@ -2,6 +2,9 @@ import applyEach from './internal/applyEach'; import map from './map'; /** + * ``` + * import applyEach from 'async/applyEach' + * ``` * Applies the provided arguments to each function in the array, calling * `callback` after all functions have completed. If you only provide the first * argument, then it will return a function which lets you pass in the @@ -9,7 +12,7 @@ import map from './map'; * * @name applyEach * @static - * @memberOf module:async + * @memberOf module:ControlFlow * @method * @category Control Flow * @param {Array|Object} fns - A collection of asynchronous functions to all diff --git a/lib/applyEachSeries.js b/lib/applyEachSeries.js index 1181d94..892e355 100644 --- a/lib/applyEachSeries.js +++ b/lib/applyEachSeries.js @@ -2,13 +2,16 @@ import applyEach from './internal/applyEach'; import mapSeries from './mapSeries'; /** - * The same as `applyEach` but runs only a single async operation at a time. + * ``` + * import applyEachSeries from 'async/applyEachSeries' + * ``` + * The same as [`applyEach`]{@link module:ControlFlow.applyEach} but runs only a single async operation at a time. * * @name applyEachSeries * @static - * @memberOf module:async + * @memberOf module:ControlFlow * @method - * @see [async.applyEach]{@link module:async.applyEach} + * @see [async.applyEach]{@link module:ControlFlow.applyEach} * @category Control Flow * @param {Array|Object} fns - A collection of asynchronous functions to all * call with the same arguments diff --git a/lib/asyncify.js b/lib/asyncify.js index f5a19f7..9baa238 100644 --- a/lib/asyncify.js +++ b/lib/asyncify.js @@ -2,6 +2,9 @@ import isObject from 'lodash/isObject'; import initialParams from './internal/initialParams'; /** + * ``` + * import asyncify from 'async/asyncify' + * ``` * Take a sync function and make it async, passing its return value to a * callback. This is useful for plugging sync functions into a waterfall, * series, or other async functions. Any arguments passed to the generated @@ -16,7 +19,7 @@ import initialParams from './internal/initialParams'; * * @name asyncify * @static - * @memberOf module:async + * @memberOf module:Utils * @method * @alias wrapSync * @category Util diff --git a/lib/auto.js b/lib/auto.js index 6b5c3d2..c6f291c 100644 --- a/lib/auto.js +++ b/lib/auto.js @@ -10,6 +10,9 @@ import rest from 'lodash/rest'; import onlyOnce from './internal/onlyOnce'; /** + * ``` + * import auto from 'async/auto' + * ``` * Determines the best order for running the functions in `tasks`, based on * their requirements. Each function can optionally depend on other functions * being completed first, and each function is run as soon as its requirements @@ -26,7 +29,7 @@ import onlyOnce from './internal/onlyOnce'; * * @name auto * @static - * @memberOf module:async + * @memberOf module:ControlFlow * @method * @category Control Flow * @param {Object} tasks - An object. Each of its properties is either a diff --git a/lib/autoInject.js b/lib/autoInject.js index 5805d56..fc6399c 100644 --- a/lib/autoInject.js +++ b/lib/autoInject.js @@ -12,7 +12,10 @@ function parseParams(func) { } /** - * A dependency-injected version of the {@link async.auto} function. Dependent + * ``` + * import autoInject from 'async/autoInject' + * ``` + * A dependency-injected version of the [async.auto]{@link module:ControlFlow.auto} function. Dependent * tasks are specified as parameters to the function, after the usual callback * parameter, with the parameter names matching the names of the tasks it * depends on. This can provide even more readable task graphs which can be @@ -22,13 +25,13 @@ function parseParams(func) { * specified as named parameters after the initial error parameter. * * The autoInject function is purely syntactic sugar and its semantics are - * otherwise equivalent to {@link async.auto}. + * otherwise equivalent to [async.auto]{@link module:ControlFlow.auto}. * * @name autoInject * @static - * @memberOf module:async + * @memberOf module:ControlFlow * @method - * @see [async.auto]{@link module:async.applyEach} + * @see [async.auto]{@link module:ControlFlow.auto} * @category Control Flow * @param {Object} tasks - An object, each of whose properties is a function of * the form 'func([dependencies...], callback). The object's key of a property diff --git a/lib/cargo.js b/lib/cargo.js index e17c8f5..9bdc613 100644 --- a/lib/cargo.js +++ b/lib/cargo.js @@ -2,9 +2,9 @@ import queue from './internal/queue'; /** * A cargo of tasks for the worker function to complete. Cargo inherits all of - * the same methods and event callbacks as {@link async.queue}. + * the same methods and event callbacks as [`queue`]{@link module:ControlFlow.queue}. * @typedef {Object} CargoObject - * @memberOf module:async + * @memberOf module:ControlFlow * @property {Function} length - A function returning the number of items * waiting to be processed. Invoke like `cargo.length()`. * @property {number} payload - An `integer` for determining how many tasks @@ -31,6 +31,9 @@ import queue from './internal/queue'; */ /** + * ``` + * import cargo from 'async/cargo' + * ``` * Creates a `cargo` object with the specified payload. Tasks added to the * cargo will be processed altogether (up to the `payload` limit). If the * `worker` is in progress, the task is queued until it becomes available. Once @@ -38,15 +41,15 @@ import queue from './internal/queue'; * called. Check out [these](https://camo.githubusercontent.com/6bbd36f4cf5b35a0f11a96dcd2e97711ffc2fb37/68747470733a2f2f662e636c6f75642e6769746875622e636f6d2f6173736574732f313637363837312f36383130382f62626330636662302d356632392d313165322d393734662d3333393763363464633835382e676966) [animations](https://camo.githubusercontent.com/f4810e00e1c5f5f8addbe3e9f49064fd5d102699/68747470733a2f2f662e636c6f75642e6769746875622e636f6d2f6173736574732f313637363837312f36383130312f38346339323036362d356632392d313165322d383134662d3964336430323431336266642e676966) * for how `cargo` and `queue` work. * - * While [queue](#queue) passes only one task to one of a group of workers + * While [`queue`]{@link module:ControlFlow.queue} passes only one task to one of a group of workers * at a time, cargo passes an array of tasks to a single worker, repeating * when the worker is finished. * * @name cargo * @static - * @memberOf module:async + * @memberOf module:ControlFlow * @method - * @see [async.queue]{@link module:async.queue} + * @see [async.queue]{@link module:ControlFlow.queue} * @category Control Flow * @param {Function} worker - An asynchronous function for processing an array * of queued tasks, which must call its `callback(err)` argument when finished, @@ -54,7 +57,7 @@ import queue from './internal/queue'; * @param {number} [payload=Infinity] - An optional `integer` for determining * how many tasks should be processed per round; if omitted, the default is * unlimited. - * @returns {module:async.CargoObject} A cargo object to manage the tasks. Callbacks can + * @returns {module:ControlFlow.CargoObject} A cargo object to manage the tasks. Callbacks can * attached as certain properties to listen for specific events during the * lifecycle of the cargo and inner queue. * @example diff --git a/lib/compose.js b/lib/compose.js index ba22878..0f87239 100644 --- a/lib/compose.js +++ b/lib/compose.js @@ -3,6 +3,9 @@ import seq from './seq'; var reverse = Array.prototype.reverse; /** + * ``` + * import compose from 'async/compose' + * ``` * 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 @@ -12,7 +15,7 @@ var reverse = Array.prototype.reverse; * * @name compose * @static - * @memberof module:async + * @memberOf module:ControlFlow * @method * @category Control Flow * @param {...Function} functions - the asynchronous functions to compose diff --git a/lib/concat.js b/lib/concat.js index 43d519f..05043c3 100644 --- a/lib/concat.js +++ b/lib/concat.js @@ -2,6 +2,9 @@ import concat from './internal/concat'; import doParallel from './internal/doParallel'; /** + * ``` + * import concat from 'async/concat' + * ``` * Applies `iteratee` to each item in `coll`, concatenating the results. Returns * the concatenated list. The `iteratee`s are called in parallel, and the * results are concatenated as they return. There is no guarantee that the @@ -10,7 +13,7 @@ import doParallel from './internal/doParallel'; * * @name concat * @static - * @memberOf module:async + * @memberOf module:Collections * @method * @category Collection * @param {Array|Object} coll - A collection to iterate over. diff --git a/lib/concatSeries.js b/lib/concatSeries.js index 1272d73..374d8ee 100644 --- a/lib/concatSeries.js +++ b/lib/concatSeries.js @@ -2,13 +2,16 @@ import concat from './internal/concat'; import doSeries from './internal/doSeries'; /** - * The same as `concat` but runs only a single async operation at a time. + * ``` + * import concatSeries from 'async/concatSeries' + * ``` + * The same as [`concat`]{@link module:Collections.concat} but runs only a single async operation at a time. * * @name concatSeries * @static - * @memberOf module:async + * @memberOf module:Collections * @method - * @see [async.concat]{@link module:async.queue} + * @see [async.concat]{@link module:Collections.concat} * @category Collection * @param {Array|Object} coll - A collection to iterate over. * @param {Function} iteratee - A function to apply to each item in `coll`. diff --git a/lib/constant.js b/lib/constant.js index 5cfc79c..5c325a1 100644 --- a/lib/constant.js +++ b/lib/constant.js @@ -2,13 +2,16 @@ import rest from 'lodash/rest'; import initialParams from './internal/initialParams'; /** + * ``` + * import constant from 'async/constant' + * ``` * Returns a function that when called, calls-back with the values provided. - * Useful as the first function in a `waterfall`, or for plugging values in to - * `auto`. + * Useful as the first function in a [`waterfall`]{@link module:ControlFlow.waterfall}, or for plugging values in to + * [`auto`]{@link module:ControlFlow.auto}. * * @name constant * @static - * @memberOf module:async + * @memberOf module:Utils * @method * @category Util * @param {...*} arguments... - Any number of arguments to automatically invoke diff --git a/lib/detect.js b/lib/detect.js index 1fb4fe5..606ebe2 100644 --- a/lib/detect.js +++ b/lib/detect.js @@ -5,6 +5,9 @@ import eachOf from './eachOf'; import findGetResult from './internal/findGetResult'; /** + * ``` + * import detect from 'async/detect' + * ``` * Returns the first value in `coll` that passes an async truth test. The * `iteratee` is applied in parallel, meaning the first iteratee to return * `true` will fire the detect `callback` with that result. That means the @@ -12,14 +15,14 @@ import findGetResult from './internal/findGetResult'; * that passes the test. * If order within the original `coll` is important, then look at - * `detectSeries`. + * [`detectSeries`]{@link module:Collections.detectSeries}. * * @name detect * @static - * @memberOf module:async + * @memberOf module:Collections * @method * @alias find - * @category Collection + * @category Collections * @param {Array|Object} coll - A collection to iterate over. * @param {Function} iteratee - A truth test to apply to each item in `coll`. * The iteratee is passed a `callback(err, truthValue)` which must be called diff --git a/lib/detectLimit.js b/lib/detectLimit.js index 335add4..6911fb9 100644 --- a/lib/detectLimit.js +++ b/lib/detectLimit.js @@ -5,16 +5,19 @@ import eachOfLimit from './eachOfLimit'; import findGetResult from './internal/findGetResult'; /** - * The same as `detect` but runs a maximum of `limit` async operations at a + * ``` + * import detectLimit from 'async/detectLimit' + * ``` + * The same as [`detect`]{@link module:Collections.detect} but runs a maximum of `limit` async operations at a * time. * * @name detectLimit * @static - * @memberOf module:async + * @memberOf module:Collections * @method - * @see [async.detect]{@link module:async.detect} + * @see [async.detect]{@link module:Collections.detect} * @alias findLimit - * @category Collection + * @category Collections * @param {Array|Object} coll - A collection to iterate over. * @param {number} limit - The maximum number of async operations at a time. * @param {Function} iteratee - A truth test to apply to each item in `coll`. diff --git a/lib/detectSeries.js b/lib/detectSeries.js index 798199e..ac2f41c 100644 --- a/lib/detectSeries.js +++ b/lib/detectSeries.js @@ -5,15 +5,18 @@ import eachOfSeries from './eachOfSeries'; import findGetResult from './internal/findGetResult'; /** - * The same as `detect` but runs only a single async operation at a time. + * ``` + * import detectSeries from 'async/detectSeries' + * ``` + * The same as [`detect`]{@link module:Collections.detect} but runs only a single async operation at a time. * * @name detectSeries * @static - * @memberOf module:async + * @memberOf module:Collections * @method - * @see [async.detect]{@link module:async.detect} + * @see [async.detect]{@link module:Collections.detect} * @alias findSeries - * @category Collection + * @category Collections * @param {Array|Object} coll - A collection to iterate over. * @param {Function} iteratee - A truth test to apply to each item in `coll`. * The iteratee is passed a `callback(err, truthValue)` which must be called @@ -1,15 +1,18 @@ import consoleFunc from './internal/consoleFunc'; /** + * ``` + * import dir from 'async/dir' + * ``` * Logs the result of an `async` function to the `console` using `console.dir` * to display the properties of the resulting object. Only works in Node.js or * in browsers that support `console.dir` and `console.error` (such as FF and * Chrome). If multiple arguments are returned from the async function, * `console.dir` is called on each argument in order. * - * @name log + * @name dir * @static - * @memberOf module:async + * @memberOf module:Utils * @method * @category Util * @param {Function} function - The function you want to eventually apply all diff --git a/lib/doDuring.js b/lib/doDuring.js index 2a40c05..7df8f60 100644 --- a/lib/doDuring.js +++ b/lib/doDuring.js @@ -1,15 +1,18 @@ import during from './during'; /** - * The post-check version of {@link async.during}. To reflect the difference in + * ``` + * import doDuring from 'async/doDuring' + * ``` + * The post-check version of [`during`]{@link module:ControlFlow.during}. To reflect the difference in * the order of operations, the arguments `test` and `fn` are switched. * - * Also a version of {@link async.doWhilst} with asynchronous `test` function. + * Also a version of [`doWhilst`]{@link module:ControlFlow.doWhilst} with asynchronous `test` function. * @name doDuring * @static - * @memberOf module:async + * @memberOf module:ControlFlow * @method - * @see [async.during]{@link module:async.during} + * @see [async.during]{@link module:ControlFlow.during} * @category Control Flow * @param {Function} fn - A function which is called each time `test` passes. * The function is passed a `callback(err)`, which must be called once it has diff --git a/lib/doUntil.js b/lib/doUntil.js index ee9f257..68fb4a1 100644 --- a/lib/doUntil.js +++ b/lib/doUntil.js @@ -1,14 +1,17 @@ import doWhilst from './doWhilst'; /** - * Like {@link async.doWhilst}, except the `test` is inverted. Note the + * ``` + * import doUtil from 'async/doUtil' + * ``` + * Like ['doWhilst']{@link module:ControlFlow.doWhilst}, except the `test` is inverted. Note the * argument ordering differs from `until`. * * @name doUntil * @static - * @memberOf module:async + * @memberOf module:ControlFlow * @method - * @see [async.doWhilst]{@link module:async.doWhilst} + * @see [async.doWhilst]{@link module:ControlFlow.doWhilst} * @category Control Flow * @param {Function} fn - A function which is called each time `test` fails. * The function is passed a `callback(err)`, which must be called once it has diff --git a/lib/doWhilst.js b/lib/doWhilst.js index 655ede9..344339d 100644 --- a/lib/doWhilst.js +++ b/lib/doWhilst.js @@ -1,16 +1,19 @@ import whilst from './whilst'; /** - * The post-check version of {@link async.whilst}. To reflect the difference in + * ``` + * import doWhilst from 'async/doWhilst' + * ``` + * The post-check version of [`whilst`]{@link module:ControlFlow.whilst}. To reflect the difference in * the order of operations, the arguments `test` and `fn` are switched. * * `doWhilst` is to `whilst` as `do while` is to `while` in plain JavaScript. * * @name doWhilst * @static - * @memberOf module:async + * @memberOf module:ControlFlow * @method - * @see [async.whilst]{@link module:async.whilst} + * @see [async.whilst]{@link module:ControlFlow.whilst} * @category Control Flow * @param {Function} fn - A function which is called each time `test` passes. * The function is passed a `callback(err)`, which must be called once it has diff --git a/lib/during.js b/lib/during.js index 943b3dd..e6016bb 100644 --- a/lib/during.js +++ b/lib/during.js @@ -2,16 +2,19 @@ import noop from 'lodash/noop'; import rest from 'lodash/rest'; /** - * Like {@link async.whilst}, except the `test` is an asynchronous function that + * ``` + * import during from 'async/during' + * ``` + * Like [`whilst`]{@link module:ControlFlow.whilst}, except the `test` is an asynchronous function that * is passed a callback in the form of `function (err, truth)`. If error is * passed to `test` or `fn`, the main callback is immediately called with the * value of the error. * * @name during * @static - * @memberOf module:async + * @memberOf module:ControlFlow * @method - * @see [async.whilst]{@link module:async.whilst} + * @see [async.whilst]{@link module:ControlFlow.whilst} * @category Control Flow * @param {Function} test - asynchronous truth test to perform before each * execution of `fn`. Invoked with (callback). diff --git a/lib/each.js b/lib/each.js index e0a5e1c..eb8f242 100644 --- a/lib/each.js +++ b/lib/each.js @@ -2,6 +2,9 @@ import eachLimit from './eachLimit'; import doLimit from './internal/doLimit'; /** + * ``` + * import each from 'async/each' + * ``` * Applies the function `iteratee` to each item in `coll`, in parallel. * The `iteratee` is called with an item from the list, and a callback for when * it has finished. If the `iteratee` passes an error to its `callback`, the @@ -13,7 +16,7 @@ import doLimit from './internal/doLimit'; * * @name each * @static - * @memberOf module:async + * @memberOf module:Collections * @method * @alias forEach * @category Collection diff --git a/lib/eachLimit.js b/lib/eachLimit.js index 544157a..6a263aa 100644 --- a/lib/eachLimit.js +++ b/lib/eachLimit.js @@ -2,13 +2,16 @@ import eachOfLimit from './internal/eachOfLimit'; import withoutIndex from './internal/withoutIndex'; /** - * The same as `each` but runs a maximum of `limit` async operations at a time. + * ``` + * import eachLimit from 'async/eachLimit' + * ``` + * The same as [`each`]{@link module:Collections.each} but runs a maximum of `limit` async operations at a time. * * @name eachLimit * @static - * @memberOf module:async + * @memberOf module:Collections * @method - * @see [async.each]{@link module:async.each} + * @see [async.each]{@link module:Collections.each} * @alias forEachLimit * @category Collection * @param {Array|Object} coll - A colleciton to iterate over. diff --git a/lib/eachOf.js b/lib/eachOf.js index e621007..d8f46f7 100644 --- a/lib/eachOf.js +++ b/lib/eachOf.js @@ -2,15 +2,19 @@ import eachOfLimit from './eachOfLimit'; import doLimit from './internal/doLimit'; /** - * Like `each`, except that it passes the key (or index) as the second argument + * ``` + * import eachOf from 'async/eachOf' + * ``` + * Like [`each`]{@link module:Collections.each}, except that it passes the key (or index) as the second argument * to the iteratee. * * @name eachOf * @static - * @memberOf module:async + * @memberOf module:Collections * @method * @alias forEachOf * @category Collection + * @see [async.each]{@link module:Collections.each} * @param {Array|Object} coll - A collection to iterate over. * @param {Function} iteratee - A function to apply to each * item in `coll`. The `key` is the item's key, or index in the case of an diff --git a/lib/eachOfLimit.js b/lib/eachOfLimit.js index 767cedd..e81d590 100644 --- a/lib/eachOfLimit.js +++ b/lib/eachOfLimit.js @@ -1,14 +1,17 @@ import _eachOfLimit from './internal/eachOfLimit'; /** - * The same as `eachOf` but runs a maximum of `limit` async operations at a + * ``` + * import eachOfLimit from 'async/eachOfLimit' + * ``` + * The same as [`eachOf`]{@link module:Collections.eachOf} but runs a maximum of `limit` async operations at a * time. * * @name eachOfLimit * @static - * @memberOf module:async + * @memberOf module:Collections * @method - * @see [async.eachOf]{@link module:async.eachOf} + * @see [async.eachOf]{@link module:Collections.eachOf} * @alias forEachOfLimit * @category Collection * @param {Array|Object} coll - A collection to iterate over. diff --git a/lib/eachOfSeries.js b/lib/eachOfSeries.js index 475ae03..103d088 100644 --- a/lib/eachOfSeries.js +++ b/lib/eachOfSeries.js @@ -2,13 +2,16 @@ import eachOfLimit from './eachOfLimit'; import doLimit from './internal/doLimit'; /** - * The same as `eachOf` but runs only a single async operation at a time. + * ``` + * import eachOfSeries from 'async/eachOfSeries' + * ``` + * The same as [`eachOf`]{@link module:Collections.eachOf} but runs only a single async operation at a time. * * @name eachOfSeries * @static - * @memberOf module:async + * @memberOf module:Collections * @method - * @see [async.eachOf]{@link module:async.eachOf} + * @see [async.eachOf]{@link module:Collections.eachOf} * @alias forEachOfSeries * @category Collection * @param {Array|Object} coll - A collection to iterate over. diff --git a/lib/eachSeries.js b/lib/eachSeries.js index 8a5465a..87fabfb 100644 --- a/lib/eachSeries.js +++ b/lib/eachSeries.js @@ -2,13 +2,16 @@ import eachLimit from './eachLimit'; import doLimit from './internal/doLimit'; /** - * The same as `each` but runs only a single async operation at a time. + * ``` + * import eachSeries from 'async/eachSeries' + * ``` + * The same as [`each`]{@link module:Collections.each} but runs only a single async operation at a time. * * @name eachSeries * @static - * @memberOf module:async + * @memberOf module:Collections * @method - * @see [async.each]{@link module:async.each} + * @see [async.each]{@link module:Collections.each} * @alias forEachSeries * @category Collection * @param {Array|Object} coll - A collection to iterate over. diff --git a/lib/ensureAsync.js b/lib/ensureAsync.js index bd0b29a..6ef698e 100644 --- a/lib/ensureAsync.js +++ b/lib/ensureAsync.js @@ -2,6 +2,9 @@ import setImmediate from './internal/setImmediate'; import initialParams from './internal/initialParams'; /** + * ``` + * import ensureAsync from 'async/ensureAsync' + * ``` * Wrap an async function and ensure it calls its callback on a later tick of * the event loop. If the function already calls its callback on a next tick, * no extra deferral is added. This is useful for preventing stack overflows @@ -11,7 +14,7 @@ import initialParams from './internal/initialParams'; * * @name ensureAsync * @static - * @memberOf module:async + * @memberOf module:Utils * @method * @category Util * @param {Function} fn - an async function, one that expects a node-style diff --git a/lib/every.js b/lib/every.js index c28d6b0..6355218 100644 --- a/lib/every.js +++ b/lib/every.js @@ -2,12 +2,15 @@ import everyLimit from './everyLimit'; import doLimit from './internal/doLimit'; /** + * ``` + * import every from 'async/every' + * ``` * Returns `true` if every element in `coll` satisfies an async test. If any * iteratee call returns `false`, the main `callback` is immediately called. * * @name every * @static - * @memberOf module:async + * @memberOf module:Collections * @method * @alias all * @category Collection diff --git a/lib/everyLimit.js b/lib/everyLimit.js index f06a14d..a8cd65a 100644 --- a/lib/everyLimit.js +++ b/lib/everyLimit.js @@ -3,13 +3,16 @@ import eachOfLimit from './eachOfLimit'; import notId from './internal/notId'; /** - * The same as `every` but runs a maximum of `limit` async operations at a time. + * ``` + * import everyLimit from 'async/everyLimit' + * ``` + * The same as [`every`]{@link module:Collections.every} but runs a maximum of `limit` async operations at a time. * * @name everyLimit * @static - * @memberOf module:async + * @memberOf module:Collections * @method - * @see [async.every]{@link module:async.every} + * @see [async.every]{@link module:Collections.every} * @alias allLimit * @category Collection * @param {Array|Object} coll - A collection to iterate over. diff --git a/lib/everySeries.js b/lib/everySeries.js index 7b99d6d..4333584 100644 --- a/lib/everySeries.js +++ b/lib/everySeries.js @@ -2,13 +2,16 @@ import everyLimit from './everyLimit'; import doLimit from './internal/doLimit'; /** - * The same as `every` but runs only a single async operation at a time. + * ``` + * import everySeries from 'async/everySeries' + * ``` + * The same as [`every`]{@link module:Collections.every} but runs only a single async operation at a time. * * @name everySeries * @static - * @memberOf module:async + * @memberOf module:Collections * @method - * @see [async.every]{@link module:async.every} + * @see [async.every]{@link module:Collections.every} * @alias allSeries * @category Collection * @param {Array|Object} coll - A collection to iterate over. diff --git a/lib/filter.js b/lib/filter.js index 9dce1be..b576df2 100644 --- a/lib/filter.js +++ b/lib/filter.js @@ -2,13 +2,16 @@ import filterLimit from './filterLimit'; import doLimit from './internal/doLimit'; /** + * ``` + * import filter from 'async/filter' + * ``` * Returns a new array of all the values in `coll` which pass an async truth * test. This operation is performed in parallel, but the results array will be * in the same order as the original. * * @name filter * @static - * @memberOf module:async + * @memberOf module:Collections * @method * @alias select * @category Collection diff --git a/lib/filterLimit.js b/lib/filterLimit.js index 7504608..d9a43c8 100644 --- a/lib/filterLimit.js +++ b/lib/filterLimit.js @@ -2,14 +2,17 @@ import filter from './internal/filter'; import doParallelLimit from './internal/doParallelLimit'; /** - * The same as `filter` but runs a maximum of `limit` async operations at a + * ``` + * import filterLimit from 'async/filterLimit' + * ``` + * The same as [`filter`]{@link module:Collections.filter} but runs a maximum of `limit` async operations at a * time. * * @name filterLimit * @static - * @memberOf module:async + * @memberOf module:Collections * @method - * @see [async.filter]{@link module:async.filter} + * @see [async.filter]{@link module:Collections.filter} * @alias selectLimit * @category Collection * @param {Array|Object} coll - A collection to iterate over. diff --git a/lib/filterSeries.js b/lib/filterSeries.js index a170ce6..1afa9b2 100644 --- a/lib/filterSeries.js +++ b/lib/filterSeries.js @@ -2,13 +2,16 @@ import filterLimit from './filterLimit'; import doLimit from './internal/doLimit'; /** - * The same as `filter` but runs only a single async operation at a time. + * ``` + * import filterSeries from 'async/filterSeries' + * ``` + * The same as [`filter`]{@link module:Collections.filter} but runs only a single async operation at a time. * * @name filterSeries * @static - * @memberOf module:async + * @memberOf module:Collections * @method - * @see [async.filter]{@link module:async.filter} + * @see [async.filter]{@link module:Collections.filter} * @alias selectSeries * @category Collection * @param {Array|Object} coll - A collection to iterate over. diff --git a/lib/forever.js b/lib/forever.js index 44eb19c..7f060ca 100644 --- a/lib/forever.js +++ b/lib/forever.js @@ -4,6 +4,9 @@ import onlyOnce from './internal/onlyOnce'; import ensureAsync from './ensureAsync'; /** + * ``` + * import forever from 'async/forever' + * ``` * Calls the asynchronous function `fn` with a callback parameter that allows it * to call itself again, in series, indefinitely. @@ -13,7 +16,7 @@ import ensureAsync from './ensureAsync'; * * @name forever * @static - * @memberOf module:async + * @memberOf module:ControlFlow * @method * @category Control Flow * @param {Function} fn - a function to call repeatedly. Invoked with (next). diff --git a/lib/index.js b/lib/index.js index 091f657..28b87d6 100644 --- a/lib/index.js +++ b/lib/index.js @@ -5,6 +5,22 @@ * `npm install --save async`, it can also be used directly in the browser. * @module async */ + +/** + * A collection of `async` functions for manipulating collections, such as + * arrays and objects. + * @module Collections + */ + +/** + * A collection of `async` functions for controlling the flow through a script. + * @module ControlFlow + */ + + /** + * A collection of `async` utility functions. + * @module Utils + */ import applyEach from './applyEach'; import applyEachSeries from './applyEachSeries'; import apply from './apply'; diff --git a/lib/iterator.js b/lib/iterator.js index 49206ff..1d67145 100644 --- a/lib/iterator.js +++ b/lib/iterator.js @@ -1,4 +1,7 @@ /** + * ``` + * import iterator from 'async/iterator' + * ``` * Creates an iterator function which calls the next function in the `tasks` * array, returning a continuation to call the next one after that. It's also * possible to “peek” at the next iterator with `iterator.next()`. @@ -8,7 +11,7 @@ * * @name iterator * @static - * @memberOf module:async + * @memberOf module:ControlFlow * @method * @category Control Flow * @param {Array} tasks - An array of functions to run. @@ -1,6 +1,9 @@ import consoleFunc from './internal/consoleFunc'; /** + * ``` + * import log from 'async/log' + * ``` * Logs the result of an `async` function to the `console`. Only works in * Node.js or in browsers that support `console.log` and `console.error` (such * as FF and Chrome). If multiple arguments are returned from the async @@ -8,7 +11,7 @@ import consoleFunc from './internal/consoleFunc'; * * @name log * @static - * @memberOf module:async + * @memberOf module:Utils * @method * @category Util * @param {Function} function - The function you want to eventually apply all @@ -2,6 +2,9 @@ import mapLimit from './mapLimit'; import doLimit from './internal/doLimit'; /** + * ``` + * import map from 'async/map' + * ``` * Produces a new collection of values by mapping each value in `coll` through * the `iteratee` function. The `iteratee` is called with an item from `coll` * and a callback for when it has finished processing. Each of these callback @@ -20,7 +23,7 @@ import doLimit from './internal/doLimit'; * * @name map * @static - * @memberOf module:async + * @memberOf module:Collections * @method * @category Collection * @param {Array|Object} coll - A collection to iterate over. diff --git a/lib/mapLimit.js b/lib/mapLimit.js index b773d58..1d3d3b2 100644 --- a/lib/mapLimit.js +++ b/lib/mapLimit.js @@ -2,13 +2,16 @@ import doParallelLimit from './internal/doParallelLimit'; import map from './internal/map'; /** - * The same as `map` but runs a maximum of `limit` async operations at a time. + * ``` + * import mapLimit from 'async/mapLimit' + * ``` + * The same as [`map`]{@link module:Collections.map} but runs a maximum of `limit` async operations at a time. * * @name mapLimit * @static - * @memberOf module:async + * @memberOf module:Collections * @method - * @see [async.map]{@link module:async.map} + * @see [async.map]{@link module:Collections.map} * @category Collection * @param {Array|Object} coll - A collection to iterate over. * @param {number} limit - The maximum number of async operations at a time. diff --git a/lib/mapSeries.js b/lib/mapSeries.js index abbeb0a..5e39065 100644 --- a/lib/mapSeries.js +++ b/lib/mapSeries.js @@ -2,13 +2,16 @@ import mapLimit from './mapLimit'; import doLimit from './internal/doLimit'; /** - * The same as `map` but runs only a single async operation at a time. + * ``` + * import mapSeries from 'async/mapSeries' + * ``` + * The same as [`map`]{@link module:Collections.map} but runs only a single async operation at a time. * * @name mapSeries * @static - * @memberOf module:async + * @memberOf module:Collections * @method - * @see [async.map]{@link module:async.map} + * @see [async.map]{@link module:Collections.map} * @category Collection * @param {Array|Object} coll - A collection to iterate over. * @param {Function} iteratee - A function to apply to each item in `coll`. diff --git a/lib/mapValues.js b/lib/mapValues.js index a1f7967..1f19e3e 100644 --- a/lib/mapValues.js +++ b/lib/mapValues.js @@ -3,7 +3,10 @@ import doLimit from './internal/doLimit'; /** - * A relative of `map`, designed for use with objects. + * ``` + * import mapValues from 'async/mapValues' + * ``` + * A relative of [`map`]{@link module:Collections.map}, designed for use with objects. * * Produces a new Object by mapping each value of `obj` through the `iteratee` * function. The `iteratee` is called each `value` and `key` from `obj` and a @@ -17,7 +20,7 @@ import doLimit from './internal/doLimit'; * * @name mapValues * @static - * @memberOf module:async + * @memberOf module:Collections * @method * @category Collection * @param {Object} obj - A collection to iterate over. diff --git a/lib/mapValuesLimit.js b/lib/mapValuesLimit.js index 9d2333c..0f3584a 100644 --- a/lib/mapValuesLimit.js +++ b/lib/mapValuesLimit.js @@ -1,14 +1,17 @@ import eachOfLimit from './eachOfLimit'; /** - * The same as `mapValues` but runs a maximum of `limit` async operations at a + * ``` + * import mapValuesLimit from 'async/mapValuesLimit' + * ``` + * The same as [`mapValues`]{@link module:Collections.mapValues} but runs a maximum of `limit` async operations at a * time. * * @name mapValuesLimit * @static - * @memberOf module:async + * @memberOf module:Collections * @method - * @see [async.mapValues]{@link module:async.mapValues} + * @see [async.mapValues]{@link module:Collections.mapValues} * @category Collection * @param {Object} obj - A collection to iterate over. * @param {number} limit - The maximum number of async operations at a time. diff --git a/lib/mapValuesSeries.js b/lib/mapValuesSeries.js index 35f1c95..e9746a1 100644 --- a/lib/mapValuesSeries.js +++ b/lib/mapValuesSeries.js @@ -2,13 +2,16 @@ import mapValuesLimit from './mapValuesLimit'; import doLimit from './internal/doLimit'; /** - * The same as `mapValues` but runs only a single async operation at a time. + * ``` + * import mapValuesSeries from 'async/mapValuesSeries' + * ``` + * The same as [`mapValues`]{@link module:Collections.mapValues} but runs only a single async operation at a time. * * @name mapValuesSeries * @static - * @memberOf module:async + * @memberOf module:Collections * @method - * @see [async.mapValues]{@link module:async.mapValues} + * @see [async.mapValues]{@link module:Collections.mapValues} * @category Collection * @param {Object} obj - A collection to iterate over. * @param {Function} iteratee - A function to apply to each value in `obj`. diff --git a/lib/memoize.js b/lib/memoize.js index 7cb22c2..3e2ee32 100644 --- a/lib/memoize.js +++ b/lib/memoize.js @@ -9,6 +9,9 @@ function has(obj, key) { } /** + * ``` + * import memoize from 'async/memoize' + * ``` * Caches the results of an `async` function. When creating a hash to store * function results against, the callback is omitted from the hash and an * optional hash function can be used. @@ -24,7 +27,7 @@ function has(obj, key) { * * @name memoize * @static - * @memberOf module:async + * @memberOf module:Utils * @method * @category Util * @param {Function} fn - The function to proxy and cache results from. diff --git a/lib/nextTick.js b/lib/nextTick.js index f6c9fca..1959c84 100644 --- a/lib/nextTick.js +++ b/lib/nextTick.js @@ -3,6 +3,9 @@ import { hasNextTick, hasSetImmediate, fallback, wrap } from './internal/setImmediate'; /** + * ``` + * import nextTick from 'async/nextTick' + * ``` * Calls `callback` on a later loop around the event loop. In Node.js this just * calls `setImmediate`. In the browser it will use `setImmediate` if * available, otherwise `setTimeout(callback, 0)`, which means other higher @@ -12,7 +15,7 @@ import { hasNextTick, hasSetImmediate, fallback, wrap } from './internal/setImm * * @name nextTick * @static - * @memberOf module:async + * @memberOf module:Utils * @method * @alias setImmediate * @category Util diff --git a/lib/parallel.js b/lib/parallel.js index e61e337..9df6bd6 100644 --- a/lib/parallel.js +++ b/lib/parallel.js @@ -2,6 +2,9 @@ import parallelLimit from './parallelLimit'; import doLimit from './internal/doLimit'; /** + * ``` + * import parallel from 'async/parallel' + * ``` * Run the `tasks` collection of functions in parallel, without waiting until * the previous function has completed. If any of the functions pass an error to * its callback, the main `callback` is immediately called with the value of the @@ -21,7 +24,7 @@ import doLimit from './internal/doLimit'; * * @name parallel * @static - * @memberOf module:async + * @memberOf module:ControlFlow * @method * @category Control Flow * @param {Array|Object} tasks - A collection containing functions to run. diff --git a/lib/parallelLimit.js b/lib/parallelLimit.js index d313bb8..7057bd0 100644 --- a/lib/parallelLimit.js +++ b/lib/parallelLimit.js @@ -2,14 +2,17 @@ import eachOfLimit from './internal/eachOfLimit'; import parallel from './internal/parallel'; /** - * The same as `parallel` but runs a maximum of `limit` async operations at a + * ``` + * import parallelLimit from 'async/parallelLimit' + * ``` + * The same as [`parallel`]{@link module:ControlFlow.parallel} but runs a maximum of `limit` async operations at a * time. * - * @name parallel + * @name parallelLimit * @static - * @memberOf module:async + * @memberOf module:ControlFlow * @method - * @see [async.parallel]{@link module:async.parallel} + * @see [async.parallel]{@link module:ControlFlow.parallel} * @category Control Flow * @param {Array|Collection} tasks - A collection containing functions to run. * Each function is passed a `callback(err, result)` which it must call on diff --git a/lib/priorityQueue.js b/lib/priorityQueue.js index 6fa02ce..4162311 100644 --- a/lib/priorityQueue.js +++ b/lib/priorityQueue.js @@ -7,14 +7,17 @@ import setImmediate from './setImmediate'; import queue from './queue'; /** - * The same as {@link async.queue} only tasks are assigned a priority and + * ``` + * import priorityQueue from 'async/priorityQueue' + * ``` + * The same as [async.queue]{@link module:ControlFlow.queue} only tasks are assigned a priority and * completed in ascending priority order. * * @name priorityQueue * @static - * @memberOf module:async + * @memberOf module:ControlFlow * @method - * @see [async.queue]{@link module:async.queue} + * @see [async.queue]{@link module:ControlFlow.queue} * @category Control Flow * @param {Function} worker - An asynchronous function for processing a queued * task, which must call its `callback(err)` argument when finished, with an @@ -24,7 +27,7 @@ import queue from './queue'; * @param {number} concurrency - An `integer` for determining how many `worker` * functions should be run in parallel. If omitted, the concurrency defaults to * `1`. If the concurrency is `0`, an error is thrown. - * @returns {queue} A priorityQueue object to manage the tasks. There are two + * @returns {module:ControlFlow.QueueObject} A priorityQueue object to manage the tasks. There are two * differences between `queue` and `priorityQueue` objects: * * `push(task, priority, [callback])` - `priority` should be a number. If an * array of `tasks` is given, all tasks will be assigned the same priority. diff --git a/lib/queue.js b/lib/queue.js index 799cc97..5f032d7 100644 --- a/lib/queue.js +++ b/lib/queue.js @@ -3,7 +3,7 @@ import queue from './internal/queue'; /** * A queue of tasks for the worker function to complete. * @typedef {Object} QueueObject - * @memberOf module:async + * @memberOf module:ControlFlow * @property {Function} length - a function returning the number of items * waiting to be processed. Invoke with `queue.length()`. * @property {Function} started - a function returning whether or not any @@ -48,6 +48,9 @@ import queue from './internal/queue'; */ /** + * ``` + * import queue from 'async/queue' + * ``` * Creates a `queue` object with the specified `concurrency`. Tasks added to the * `queue` are processed in parallel (up to the `concurrency` limit). If all * `worker`s are in progress, the task is queued until one becomes available. @@ -55,7 +58,7 @@ import queue from './internal/queue'; * * @name queue * @static - * @memberOf module:async + * @memberOf module:ControlFlow * @method * @category Control Flow * @param {Function} worker - An asynchronous function for processing a queued @@ -66,7 +69,7 @@ import queue from './internal/queue'; * @param {number} [concurrency=1] - An `integer` for determining how many * `worker` functions should be run in parallel. If omitted, the concurrency * defaults to `1`. If the concurrency is `0`, an error is thrown. - * @returns {module:async.QueueObject} A queue object to manage the tasks. Callbacks can + * @returns {module:ControlFlow.QueueObject} A queue object to manage the tasks. Callbacks can * attached as certain properties to listen for specific events during the * lifecycle of the queue. * @example diff --git a/lib/race.js b/lib/race.js index d656701..8efece4 100644 --- a/lib/race.js +++ b/lib/race.js @@ -4,6 +4,9 @@ import noop from 'lodash/noop'; import once from './internal/once'; /** + * ``` + * import race from 'async/race' + * ``` * Runs the `tasks` array of functions in parallel, without waiting until the * previous function has completed. Once any the `tasks` completed or pass an * error to its callback, the main `callback` is immediately called. It's @@ -11,7 +14,7 @@ import once from './internal/once'; * * @name race * @static - * @memberOf module:async + * @memberOf module:ControlFlow * @method * @category Control Flow * @param {Array} tasks - An array containing functions to run. Each function diff --git a/lib/reduce.js b/lib/reduce.js index 7754f33..d870c9d 100644 --- a/lib/reduce.js +++ b/lib/reduce.js @@ -1,6 +1,9 @@ import eachOfSeries from './eachOfSeries'; /** + * ``` + * import reduce from 'async/reduce' + * ``` * Reduces `coll` into a single value using an async `iteratee` to return each * successive step. `memo` is the initial state of the reduction. This function * only operates in series. @@ -13,7 +16,7 @@ import eachOfSeries from './eachOfSeries'; * * @name reduce * @static - * @memberOf module:async + * @memberOf module:Collections * @method * @alias inject * @alias foldl diff --git a/lib/reduceRight.js b/lib/reduceRight.js index d1ffa55..b3090d9 100644 --- a/lib/reduceRight.js +++ b/lib/reduceRight.js @@ -3,13 +3,16 @@ import reduce from './reduce'; var slice = Array.prototype.slice; /** - * Same as `reduce`, only operates on `coll` in reverse order. + * ``` + * import reduceRight from 'async/reduceRight' + * ``` + * Same as [`reduce`]{@link module:Collections.reduce}, only operates on `coll` in reverse order. * * @name reduceRight * @static - * @memberOf module:async + * @memberOf module:Collections * @method - * @see [async.reduce]{@link module:async.reduce} + * @see [async.reduce]{@link module:Collections.reduce} * @alias foldr * @category Collection * @param {Array|Object} coll - A collection to iterate over. diff --git a/lib/reflect.js b/lib/reflect.js index e650461..a8b7438 100644 --- a/lib/reflect.js +++ b/lib/reflect.js @@ -2,6 +2,9 @@ import initialParams from './internal/initialParams'; import rest from 'lodash/rest'; /** + * ``` + * import reflect from 'async/reflect' + * ``` * Wraps the function in another function that always returns data even when it * errors. * @@ -9,7 +12,7 @@ import rest from 'lodash/rest'; * * @name reflect * @static - * @memberOf module:async + * @memberOf module:Utils * @method * @category Util * @param {Function} fn - The function you want to wrap diff --git a/lib/reflectAll.js b/lib/reflectAll.js index 6167e6c..160334c 100644 --- a/lib/reflectAll.js +++ b/lib/reflectAll.js @@ -1,13 +1,16 @@ import reflect from './reflect'; /** + * ``` + * import reflectAll from 'async/reflectAll' + * ``` * A helper function that wraps an array of functions with reflect. * * @name reflectAll * @static - * @memberOf module:async + * @memberOf module:Utils * @method - * @see [async.reflect]{@link module:async.reflect} + * @see [async.reflect]{@link module:Utils.reflect} * @category Util * @param {Array} tasks - The array of functions to wrap in `async.reflect`. * @returns {Array} Returns an array of functions, each function wrapped in diff --git a/lib/reject.js b/lib/reject.js index fb7ad9d..dd54453 100644 --- a/lib/reject.js +++ b/lib/reject.js @@ -2,13 +2,16 @@ import rejectLimit from './rejectLimit'; import doLimit from './internal/doLimit'; /** - * The opposite of `filter`. Removes values that pass an `async` truth test. + * ``` + * import reject from 'async/reject' + * ``` + * The opposite of [`filter`]{@link module:Collections.filter}. Removes values that pass an `async` truth test. * * @name reject * @static - * @memberOf module:async + * @memberOf module:Collections * @method - * @see [async.filter]{@link module:async.filter} + * @see [async.filter]{@link module:Collections.filter} * @category Collection * @param {Array|Object} coll - A collection to iterate over. * @param {Function} iteratee - A truth test to apply to each item in `coll`. diff --git a/lib/rejectLimit.js b/lib/rejectLimit.js index 5942428..78c2def 100644 --- a/lib/rejectLimit.js +++ b/lib/rejectLimit.js @@ -2,14 +2,17 @@ import reject from './internal/reject'; import doParallelLimit from './internal/doParallelLimit'; /** - * The same as `reject` but runs a maximum of `limit` async operations at a + * ``` + * import rejectLimit from 'async/rejectLimit' + * ``` + * The same as [`reject`]{@link module:Collections.reject} but runs a maximum of `limit` async operations at a * time. * * @name rejectLimit * @static - * @memberOf module:async + * @memberOf module:Collections * @method - * @see [async.reject]{@link module:async.reject} + * @see [async.reject]{@link module:Collections.reject} * @category Collection * @param {Array|Object} coll - A collection to iterate over. * @param {number} limit - The maximum number of async operations at a time. diff --git a/lib/rejectSeries.js b/lib/rejectSeries.js index 6a3016a..a691536 100644 --- a/lib/rejectSeries.js +++ b/lib/rejectSeries.js @@ -2,13 +2,16 @@ import rejectLimit from './rejectLimit'; import doLimit from './internal/doLimit'; /** - * The same as `reject` but runs only a single async operation at a time. + * ``` + * import rejectSeries from 'async/rejectSeries' + * ``` + * The same as [`reject`]{@link module:Collections.reject} but runs only a single async operation at a time. * * @name rejectSeries * @static - * @memberOf module:async + * @memberOf module:Collections * @method - * @see [async.reject]{@link module:async.reject} + * @see [async.reject]{@link module:Collections.reject} * @category Collection * @param {Array|Object} coll - A collection to iterate over. * @param {Function} iteratee - A truth test to apply to each item in `coll`. diff --git a/lib/retry.js b/lib/retry.js index 6a98b99..b137a0d 100644 --- a/lib/retry.js +++ b/lib/retry.js @@ -3,6 +3,9 @@ import noop from 'lodash/noop'; import constant from 'lodash/constant'; /** + * ``` + * import retry from 'async/retry' + * ``` * Attempts to get a successful response from `task` no more than `times` times * before returning an error. If the task is successful, the `callback` will be * passed the result of the successful task. If all attempts fail, the callback @@ -10,7 +13,7 @@ import constant from 'lodash/constant'; * * @name retry * @static - * @memberOf module:async + * @memberOf module:ControlFlow * @method * @category Control Flow * @param {Object|number} [opts = {times: 5, interval: 0}| 5] - Can be either an diff --git a/lib/retryable.js b/lib/retryable.js index 45ef5ac..ad47351 100644 --- a/lib/retryable.js +++ b/lib/retryable.js @@ -2,14 +2,17 @@ import retry from './retry'; import initialParams from './internal/initialParams'; /** - * A close relative of `retry`. This method wraps a task and makes it + * ``` + * import retryable from 'async/retryable' + * ``` + * A close relative of [`retry`]{@link module:ControlFlow.retry}. This method wraps a task and makes it * retryable, rather than immediately calling it with retries. * * @name retryable * @static - * @memberOf module:async + * @memberOf module:ControlFlow * @method - * @see [async.retry]{@link module:async.retry} + * @see [async.retry]{@link module:ControlFlow.retry} * @category Control Flow * @param {Object|number} [opts = {times: 5, interval: 0}| 5] - optional * options, exactly the same as from `retry` @@ -3,17 +3,20 @@ import rest from 'lodash/rest'; import reduce from './reduce'; /** + * ``` + * import seq from 'async/seq' + * ``` * Version of the compose function that is more natural to read. Each function * consumes the return value of the previous function. It is the equivalent of - * {@link async.compose} with the arguments reversed. + * [compose]{@link module:ControlFlow.compose} with the arguments reversed. * * Each function is executed with the `this` binding of the composed function. * * @name seq * @static - * @memberOf module:async + * @memberOf module:ControlFlow * @method - * @see [async.compose]{@link module:async.compose} + * @see [async.compose]{@link module:ControlFlow.compose} * @category Control Flow * @param {...Function} functions - the asynchronous functions to compose * @returns {Function} a function that composes the `functions` in order diff --git a/lib/series.js b/lib/series.js index 713c839..1877e81 100644 --- a/lib/series.js +++ b/lib/series.js @@ -2,6 +2,9 @@ import parallel from './internal/parallel'; import eachOfSeries from './eachOfSeries'; /** + * ``` + * import series from 'async/series' + * ``` * Run the functions in the `tasks` collection in series, each one running once * the previous function has completed. If any functions in the series pass an * error to its callback, no more functions are run, and `callback` is @@ -24,7 +27,7 @@ import eachOfSeries from './eachOfSeries'; * * @name series * @static - * @memberOf module:async + * @memberOf module:ControlFlow * @method * @category Control Flow * @param {Array|Object} tasks - A collection containing functions to run, each diff --git a/lib/setImmediate.js b/lib/setImmediate.js index 7485b40..1b545a5 100644 --- a/lib/setImmediate.js +++ b/lib/setImmediate.js @@ -1,6 +1,9 @@ import setImmediate from './internal/setImmediate'; /** + * ``` + * import setImmediate from 'async/setImmediate' + * ``` * Calls `callback` on a later loop around the event loop. In Node.js this just * calls `setImmediate`. In the browser it will use `setImmediate` if * available, otherwise `setTimeout(callback, 0)`, which means other higher @@ -10,7 +13,7 @@ import setImmediate from './internal/setImmediate'; * * @name setImmediate * @static - * @memberOf module:async + * @memberOf module:Utils * @method * @alias nextTick * @category Util diff --git a/lib/some.js b/lib/some.js index 13ef62f..83bed71 100644 --- a/lib/some.js +++ b/lib/some.js @@ -2,13 +2,16 @@ import someLimit from './someLimit'; import doLimit from './internal/doLimit'; /** + * ``` + * import some from 'async/some' + * ``` * Returns `true` if at least one element in the `coll` satisfies an async test. * If any iteratee call returns `true`, the main `callback` is immediately * called. * * @name some * @static - * @memberOf module:async + * @memberOf module:Collections * @method * @alias any * @category Collection diff --git a/lib/someLimit.js b/lib/someLimit.js index b9d5cc5..b3920f1 100644 --- a/lib/someLimit.js +++ b/lib/someLimit.js @@ -3,13 +3,16 @@ import eachOfLimit from './eachOfLimit'; import identity from 'lodash/identity'; /** - * The same as `some` but runs a maximum of `limit` async operations at a time. + * ``` + * import someLimit from 'async/someLimit' + * ``` + * The same as [`some`]{@link module:Collections.some} but runs a maximum of `limit` async operations at a time. * * @name someLimit * @static - * @memberOf module:async + * @memberOf module:Collections * @method - * @see [async.some]{@link module:async.some} + * @see [async.some]{@link module:Collections.some} * @alias anyLimit * @category Collection * @param {Array|Object} coll - A collection to iterate over. diff --git a/lib/someSeries.js b/lib/someSeries.js index fa3e0e3..feec58f 100644 --- a/lib/someSeries.js +++ b/lib/someSeries.js @@ -2,13 +2,16 @@ import someLimit from './someLimit'; import doLimit from './internal/doLimit'; /** - * The same as `some` but runs only a single async operation at a time. + * ``` + * import someSeries from 'async/someSeries' + * ``` + * The same as [`some`]{@link module:Collections.some} but runs only a single async operation at a time. * * @name someSeries * @static - * @memberOf module:async + * @memberOf module:Collections * @method - * @see [async.some]{@link module:async.some} + * @see [async.some]{@link module:Collections.some} * @alias anySeries * @category Collection * @param {Array|Object} coll - A collection to iterate over. diff --git a/lib/sortBy.js b/lib/sortBy.js index 8d8fd0d..f96b1ab 100644 --- a/lib/sortBy.js +++ b/lib/sortBy.js @@ -4,12 +4,15 @@ import property from 'lodash/_baseProperty'; import map from './map'; /** + * ``` + * import sortBy from 'async/sortBy' + * ``` * Sorts a list by the results of running each `coll` value through an async * `iteratee`. * * @name sortBy * @static - * @memberOf module:async + * @memberOf module:Collections * @method * @category Collection * @param {Array|Object} coll - A collection to iterate over. diff --git a/lib/timeout.js b/lib/timeout.js index f5974ff..f2643ac 100644 --- a/lib/timeout.js +++ b/lib/timeout.js @@ -1,13 +1,16 @@ import initialParams from './internal/initialParams'; /** + * ``` + * import timeout from 'async/timeout' + * ``` * Sets a time limit on an asynchronous function. If the function does not call * its callback within the specified milliseconds, it will be called with a * timeout error. The code property for the error object will be `'ETIMEDOUT'`. * * @name timeout * @static - * @memberOf module:async + * @memberOf module:Utils * @method * @category Util * @param {Function} asyncFn - The asynchronous function you want to set the diff --git a/lib/times.js b/lib/times.js index 62843c6..e6e4187 100644 --- a/lib/times.js +++ b/lib/times.js @@ -2,19 +2,22 @@ import timesLimit from './timesLimit'; import doLimit from './internal/doLimit'; /** + * ``` + * import times from 'async/times' + * ``` * Calls the `iteratee` function `n` times, and accumulates results in the same - * manner you would use with {@link async.map}. + * manner you would use with [map]{@link module:Collections.map}. * * @name times * @static - * @memberOf module:async + * @memberOf module:ControlFlow * @method - * @see [async.map]{@link module:async.map} + * @see [async.map]{@link module:Collections.map} * @category Control Flow * @param {number} n - The number of times to run the function. * @param {Function} iteratee - The function to call `n` times. Invoked with the * iteration index and a callback (n, next). - * @param {Function} callback - see {@link async.map}. + * @param {Function} callback - see {@link module:Collections.map}. * @example * * // Pretend this is some complicated async factory diff --git a/lib/timesLimit.js b/lib/timesLimit.js index 302c803..01a6399 100644 --- a/lib/timesLimit.js +++ b/lib/timesLimit.js @@ -2,20 +2,23 @@ import mapLimit from './mapLimit'; import range from 'lodash/_baseRange'; /** -* The same as {@link times} but runs a maximum of `limit` async operations at a -* time. + * ``` + * import timesLimit from 'async/timesLimit' + * ``` + * The same as [times]{@link module:ControlFlow.times} but runs a maximum of `limit` async operations at a + * time. * * @name timesLimit * @static - * @memberOf module:async + * @memberOf module:ControlFlow * @method - * @see [async.times]{@link module:async.times} + * @see [async.times]{@link module:ControlFlow.times} * @category Control Flow * @param {number} count - The number of times to run the function. * @param {number} limit - The maximum number of async operations at a time. * @param {Function} iteratee - The function to call `n` times. Invoked with the * iteration index and a callback (n, next). - * @param {Function} callback - see {@link async.map}. + * @param {Function} callback - see [async.map]{@link module:Collections.map}. */ export default function timeLimit(count, limit, iteratee, callback) { mapLimit(range(0, count, 1), limit, iteratee, callback); diff --git a/lib/timesSeries.js b/lib/timesSeries.js index 2a46a73..adef004 100644 --- a/lib/timesSeries.js +++ b/lib/timesSeries.js @@ -2,17 +2,20 @@ import timesLimit from './timesLimit'; import doLimit from './internal/doLimit'; /** - * The same as {@link async.times} but runs only a single async operation at a time. + * ``` + * import timesSeries from 'async/timesSeries' + * ``` + * The same as [times]{@link module:ControlFlow.times} but runs only a single async operation at a time. * * @name timesSeries * @static - * @memberOf module:async + * @memberOf module:ControlFlow * @method - * @see [async.times]{@link module:async.times} + * @see [async.times]{@link module:ControlFlow.times} * @category Control Flow * @param {number} n - The number of times to run the function. * @param {Function} iteratee - The function to call `n` times. Invoked with the * iteration index and a callback (n, next). - * @param {Function} callback - see {@link async.map}. + * @param {Function} callback - see {@link module:Collections.map}. */ export default doLimit(timesLimit, 1); diff --git a/lib/transform.js b/lib/transform.js index 4025fd7..854df2f 100644 --- a/lib/transform.js +++ b/lib/transform.js @@ -3,13 +3,16 @@ import isArray from 'lodash/isArray'; import eachOf from './eachOf'; /** + * ``` + * import transform from 'async/transform' + * ``` * A relative of `reduce`. Takes an Object or Array, and iterates over each * element in series, each step potentially mutating an `accumulator` value. * The type of the accumulator defaults to the type of collection passed in. * * @name transform * @static - * @memberOf module:async + * @memberOf module:Collections * @method * @category Collection * @param {Array|Object} coll - A collection to iterate over. diff --git a/lib/unmemoize.js b/lib/unmemoize.js index e8537d9..f0c65a3 100644 --- a/lib/unmemoize.js +++ b/lib/unmemoize.js @@ -1,12 +1,15 @@ /** - * Undoes a {@link async.memoize}d function, reverting it to the original, + * ``` + * import unmemoize from 'async/unmemoize' + * ``` + * Undoes a [memoize]{@link module:Utils.memoize}d function, reverting it to the original, * unmemoized form. Handy for testing. * * @name unmemoize * @static - * @memberOf module:async + * @memberOf module:Utils * @method - * @see [async.memoize]{@link module:async.memoize} + * @see [async.memoize]{@link module:Utils.memoize} * @category Util * @param {Function} fn - the memoized function * @returns {Function} a function that calls the original unmemoized function diff --git a/lib/until.js b/lib/until.js index 0b5fde8..23a3ca5 100644 --- a/lib/until.js +++ b/lib/until.js @@ -1,17 +1,20 @@ import whilst from './whilst'; /** + * ``` + * import whilst from 'async/whilst' + * ``` * Repeatedly call `fn` until `test` returns `true`. Calls `callback` when * stopped, or an error occurs. `callback` will be passed an error and any * arguments passed to the final `fn`'s callback. * - * The inverse of {@link async.whilst}. + * The inverse of [whilst]{@link module:ControlFlow.whilst}. * * @name until * @static - * @memberOf module:async + * @memberOf module:ControlFlow * @method - * @see [async.whilst]{@link module:async.whilst} + * @see [async.whilst]{@link module:ControlFlow.whilst} * @category Control Flow * @param {Function} test - synchronous truth test to perform before each * execution of `fn`. Invoked with (). diff --git a/lib/waterfall.js b/lib/waterfall.js index cd75b91..36a66f7 100644 --- a/lib/waterfall.js +++ b/lib/waterfall.js @@ -6,6 +6,9 @@ import rest from 'lodash/rest'; import onlyOnce from './internal/onlyOnce'; /** + *``` + * import waterfall from 'async/waterfall' + * ``` * Runs the `tasks` array of functions in series, each passing their results to * the next in the array. However, if any of the `tasks` pass an error to their * own callback, the next function is not executed, and the main `callback` is @@ -13,7 +16,7 @@ import onlyOnce from './internal/onlyOnce'; * * @name waterfall * @static - * @memberOf module:async + * @memberOf module:ControlFlow * @method * @category Control Flow * @param {Array} tasks - An array of functions to run, each function is passed diff --git a/lib/whilst.js b/lib/whilst.js index d6e6591..1cfb157 100644 --- a/lib/whilst.js +++ b/lib/whilst.js @@ -2,12 +2,15 @@ import noop from 'lodash/noop'; import rest from 'lodash/rest'; /** + * ``` + * import whilst from 'async/whilst' + * ``` * Repeatedly call `fn`, while `test` returns `true`. Calls `callback` when * stopped, or an error occurs. * * @name whilst * @static - * @memberOf module:async + * @memberOf module:ControlFlow * @method * @category Control Flow * @param {Function} test - synchronous truth test to perform before each diff --git a/package.json b/package.json index c386f5b..55eb20d 100644 --- a/package.json +++ b/package.json @@ -31,6 +31,7 @@ "benchmark": "bestiejs/benchmark.js", "bluebird": "^2.9.32", "chai": "^3.1.0", + "cheerio": "^0.20.0", "coveralls": "^2.11.2", "es6-promise": "^2.3.0", "esdoc": "^0.4.7", @@ -61,7 +62,7 @@ "coverage": "nyc npm test && nyc report", "coveralls": "nyc npm test && nyc report --reporter=text-lcov | coveralls", "doc": "esdoc -c ./support/esdoc.json", - "jsdocs": "jsdoc -c ./support/jsdoc.json", + "jsdocs": "jsdoc -c ./support/jsdoc.json && node support/fix-jsdoc-html.js", "lint": "eslint lib/ mocha_test/ perf/memory.js perf/suites.js perf/benchmark.js support/ karma.conf.js", "mocha-browser-test": "karma start", "mocha-node-test": "mocha mocha_test/ --compilers js:babel-core/register", diff --git a/support/fix-jsdoc-html.js b/support/fix-jsdoc-html.js new file mode 100644 index 0000000..3a39fa7 --- /dev/null +++ b/support/fix-jsdoc-html.js @@ -0,0 +1,166 @@ +var async = require('../dist/async'); +var fs = require('fs-extra'); +var path = require('path'); + +var $ = require('cheerio'); +var _ = require('lodash'); + +var docsDir = path.join(__dirname, '../docs'); +var asyncFile = path.join(__dirname, '../dist/async.js'); + +var pageTitle = 'ASYNC'; + +var docFilename = 'docs.html'; +var mainModuleFile = 'module-async.html'; +var mainSectionId = '#main'; +var sectionTitleClass = '.page-title' + +var HTMLFileBegin = '<!DOCTYPE html>\n<html lang="en">\n<head>\n'; +var HTMLFileHeadBodyJoin = '</head>\n<body>'; +var HTMLFileEnd = '</body>'; + +var pageTitlePadding = '12px'; + +var additionalFooterText = ' Documentation has been modified from the original. ' + + ' For more information, please see the <a href="https://github.com/caolan/async">async</a> repository.'; + +fs.copySync(asyncFile, path.join(docsDir, 'scripts/async.js'), { clobber: 'true'}); + +function generateHTMLFile(filename, $page, callback) { + // generate an HTML file from a cheerio object + var HTMLdata = HTMLFileBegin + $page.find('head').html() + + HTMLFileHeadBodyJoin + $page.find('body').html() + + HTMLFileEnd; + + fs.writeFile(filename, HTMLdata, callback); +} + +function extractModuleFiles(files) { + return _.filter(files, function(file) { + return _.startsWith(file, 'module') && file !== mainModuleFile; + }); +} + +function combineFakeModules(files, callback) { + var moduleFiles = extractModuleFiles(files); + + fs.readFile(path.join(docsDir, mainModuleFile), 'utf8', function(err, mainModuleData) { + if (err) return callback(err); + + var $mainPage = $(mainModuleData); + // each 'module' (category) has a separate page, with all of the + // important information in a 'main' div. Combine all of these divs into + // one on the actual module page (async) + async.eachSeries(moduleFiles, function(file, fileCallback) { + fs.readFile(path.join(docsDir, file), 'utf8', function(err, moduleData) { + if (err) return fileCallback(err); + var $modulePage = $(moduleData); + var moduleName = $modulePage.find(sectionTitleClass).text(); + $modulePage.find(sectionTitleClass).attr('id', moduleName.toLowerCase()); + $mainPage.find(mainSectionId).append($modulePage.find(mainSectionId).html()); + return fileCallback(); + }); + }, function(err) { + if (err) return callback(err); + + generateHTMLFile(path.join(docsDir, docFilename), $mainPage, callback); + }); + }); +} + +function applyPreCheerioFixes(data) { + var fixedPageTitleStyle = '<style>\n'+sectionTitleClass+' { padding-top: '+pageTitlePadding+'; }\n</style>\n' + var closingHeadTag = '</head>' + + var asyncScript = '<script src="scripts/async.js"></script>\n'; + var closingBodyTag = '</body>'; + + var rIncorrectCFText = />ControlFlow</g; + var fixedCFText = '>Control Flow<'; + + var rIncorrectModuleText = />module:(\w+)\.(\w+)</g + + // the heading needs additional padding at the top so it doesn't get cutoff + return data.replace(closingHeadTag, fixedPageTitleStyle+closingHeadTag) + // inject the async library onto each page + .replace(closingBodyTag, asyncScript+closingBodyTag) + // for JSDoc to work, the module needs to be labelled 'ControlFlow', while + // on the page it should appear as 'Control Flow' + .replace(rIncorrectCFText, fixedCFText) + // for return types, JSDoc doesn't allow replacing the link text, so it + // needs to be done here + .replace(rIncorrectModuleText, function(match, moduleName, methodName) { + return '>'+methodName+'<'; + }); +}; + +function fixToc($page, moduleFiles) { + // remove `async` listing from toc + $page.find('li').find('a[href="'+mainModuleFile+'"]').parent().remove(); + + // change toc title + $page.find('nav').children('h3').text(pageTitle); + + // make everything point to the same 'docs.html' page + _.each(moduleFiles, function(filename) { + $page.find('[href^="'+filename+'"]').each(function() { + var $ele = $(this); + var href = $ele.attr('href'); + + // category titles should sections title, while everything else + // points to the correct listing + if (href === filename) { + var moduleName = $ele.text().toLowerCase().replace(/\s/g, ''); + $ele.attr('href', docFilename+'#'+moduleName); + } else { + $ele.attr('href', href.replace(filename, docFilename)); + } + }); + }); +} + +function fixFooter($page) { + // add a note to the footer that the documentation has been modified + var $footer = $page.find('footer'); + var text = $footer.text(); + $footer.append(additionalFooterText); +}; + +function fixModuleLinks(files, callback) { + var moduleFiles = extractModuleFiles(files); + + async.each(files, function(file, fileCallback) { + var filePath = path.join(docsDir, file); + fs.readFile(filePath, 'utf8', function(err, fileData) { + if (err) return fileCallback(err); + var $file = $(applyPreCheerioFixes(fileData)); + + fixToc($file, moduleFiles); + + fixFooter($file); + $file.find('[href="'+mainModuleFile+'"]').attr('href', docFilename); + generateHTMLFile(filePath, $file, fileCallback); + }); + }, callback); +} + +fs.readdir(docsDir, function(err, files) { + if (err) { + throw err; + } + + var HTMLFiles = _.filter(files, function(file) { + return path.extname(file) === '.html'; + }); + + combineFakeModules(HTMLFiles, function(err) { + if (err) throw err; + + HTMLFiles.push(docFilename); + + fixModuleLinks(HTMLFiles, function(err) { + if (err) throw err; + console.log('Docs generated successfully'); + }); + }); +}); diff --git a/support/jsdoc.json b/support/jsdoc.json index ac95082..544db31 100644 --- a/support/jsdoc.json +++ b/support/jsdoc.json @@ -15,7 +15,6 @@ "recurse": true }, "templates": { - "cleverLinks": false, - "theme": "cerulean" + "cleverLinks": false } } |