Docs improvements

src/asyncEvery.mjs

@@ -7,7 +7,7 @@ import asyncFindIndex from './asyncFindIndex.mjs'
 /**
  * Returns `true` if all elements of an iterable pass a truth test and `false` otherwise.
  *
- * The calls to `iteratee` will be performed in a queue to limit the concurrency of these calls.
+ * The calls to `iteratee` will be performed asynchronously in a {@link Queue} to limit the concurrency of these calls.
  * If any truth test returns `false` the promise is immediately resolved.
  *
  * Whenever a test returns `false`, all the remaining tasks will be cancelled as long
@@ -22,8 +22,8 @@ import asyncFindIndex from './asyncFindIndex.mjs'
  *   * `value`: The current value to process
  *   * `index`: The index in the iterable. Will start from 0.
  *   * `iterable`: The iterable on which the operation is being performed.
- * @param {Queue | number} [queueOrConcurrency] If a queue is specified it will be used to schedule the calls to
- * `iteratee`. If a number is specified it will be used as the concurrency of a Queue that will be created
+ * @param {Queue | number} [queueOrConcurrency] If a {@link Queue} is specified it will be used to schedule the calls to
+ * `iteratee`. If a number is specified it will be used as the concurrency of a {@link Queue} that will be created
  * implicitly for the same purpose. Defaults to `1`.
  * @returns {Promise<boolean>} A promise that will be resolved to `true` if all values pass the truth test and `false`
  * if a least one of them doesn't pass it. That promise will be rejected if one of the truth test throws

src/asyncFilter.mjs

@@ -6,7 +6,7 @@ import asyncGeneratorFilter from './asyncGeneratorFilter.mjs'
 /**
  * Returns an array of all the values in `iterable` which pass an asynchronous truth test.
  *
- * The calls to `iteratee` will be performed in a queue to limit the concurrency of these calls.
+ * The calls to `iteratee` will be performed asynchronously in a {@link Queue} to limit the concurrency of these calls.
  * The results will be in the same order than in `iterable`.
  *
  * If any of the calls to `iteratee` throws an exception the returned promise will be rejected and the remaining
@@ -18,8 +18,8 @@ import asyncGeneratorFilter from './asyncGeneratorFilter.mjs'
  *   * `value`: The current value to process
  *   * `index`: The index in the iterable. Will start from 0.
  *   * `iterable`: The iterable on which the operation is being performed.
- * @param {Queue | number} [queueOrConcurrency] If a queue is specified it will be used to schedule the calls to
- * `iteratee`. If a number is specified it will be used as the concurrency of a Queue that will be created
+ * @param {Queue | number} [queueOrConcurrency] If a {@link Queue} is specified it will be used to schedule the calls to
+ * `iteratee`. If a number is specified it will be used as the concurrency of a {@link Queue} that will be created
  * implicitly for the same purpose. Defaults to `1`.
  * @returns {Promise<any[]>} A promise that will be resolved with an array containing all the values that passed
  * the truth test. This promise will be rejected if any of the `iteratee` calls throws an exception.

src/asyncFind.mjs

@@ -5,7 +5,7 @@ import Queue from './Queue.mjs'
 /**
  * Returns the first element of an iterable that passes an asynchronous truth test.
  *
- * The calls to `iteratee` will be performed in a queue to limit the concurrency of these calls.
+ * The calls to `iteratee` will be performed asynchronously in a {@link Queue} to limit the concurrency of these calls.
  *
  * Whenever a result is found, all the remaining tasks will be cancelled as long
  * as they didn't started already. In case of exception in one of the `iteratee` calls the promise
@@ -19,8 +19,8 @@ import Queue from './Queue.mjs'
  *   * `value`: The current value to process
  *   * `index`: The index in the iterable. Will start from 0.
  *   * `iterable`: The iterable on which the operation is being performed.
- * @param {Queue | number} [queueOrConcurrency] If a queue is specified it will be used to schedule the calls to
- * `iteratee`. If a number is specified it will be used as the concurrency of a Queue that will be created
+ * @param {Queue | number} [queueOrConcurrency] If a {@link Queue} is specified it will be used to schedule the calls to
+ * `iteratee`. If a number is specified it will be used as the concurrency of a {@link Queue} that will be created
  * implicitly for the same purpose. Defaults to `1`.
  * @param {boolean} [ordered] If true this function will return on the first element in the iterable
  * order for which `iteratee` returned true. If false it will be the first in time.

src/asyncFindIndex.mjs

@@ -5,7 +5,7 @@ import Queue from './Queue.mjs'
 /**
  * Returns the index of the first element of an iterable that passes an asynchronous truth test.
  *
- * The calls to `iteratee` will be performed in a queue to limit the concurrency of these calls.
+ * The calls to `iteratee` will be performed asynchronously in a {@link Queue} to limit the concurrency of these calls.
  *
  * Whenever a result is found, all the remaining tasks will be cancelled as long
  * as they didn't started already. In case of exception in one of the iteratee calls the promise
@@ -19,8 +19,8 @@ import Queue from './Queue.mjs'
  *   * `value`: The current value to process
  *   * `index`: The index in the iterable. Will start from 0.
  *   * `iterable`: The iterable on which the operation is being performed.
- * @param {Queue | number} [queueOrConcurrency] If a queue is specified it will be used to schedule the calls to
- * `iteratee`. If a number is specified it will be used as the concurrency of a Queue that will be created
+ * @param {Queue | number} [queueOrConcurrency] If a {@link Queue} is specified it will be used to schedule the calls to
+ * `iteratee`. If a number is specified it will be used as the concurrency of a {@link Queue} that will be created
  * implicitly for the same purpose. Defaults to `1`.
  * @param {boolean} [ordered] If true this function will return on the first element in the iterable
  * order for which `iteratee` returned true. If false it will be the first in time.

src/asyncForEach.mjs

@@ -5,7 +5,7 @@ import Queue from './Queue.mjs'
 /**
  * Calls a function on each element of iterable.
  *
- * The calls to `iteratee` will be performed in a queue to limit the concurrency of these calls.
+ * The calls to `iteratee` will be performed asynchronously in a {@link Queue} to limit the concurrency of these calls.
  *
  * If any of the calls to iteratee throws an exception the returned promise will be rejected and the remaining
  * pending tasks will be cancelled.
@@ -16,8 +16,8 @@ import Queue from './Queue.mjs'
  *   * `value`: The current value to process
  *   * `index`: The index in the iterable. Will start from 0.
  *   * `iterable`: The iterable on which the operation is being performed.
- * @param {Queue | number} [queueOrConcurrency] If a queue is specified it will be used to schedule the calls to
- * `iteratee`. If a number is specified it will be used as the concurrency of a Queue that will be created
+ * @param {Queue | number} [queueOrConcurrency] If a {@link Queue} is specified it will be used to schedule the calls to
+ * `iteratee`. If a number is specified it will be used as the concurrency of a {@link Queue} that will be created
  * implicitly for the same purpose. Defaults to `1`.
  * @returns {Promise} A promise that will be resolved when all the calls to `iteratee` have been done.
  * This promise will be rejected if any call to `iteratee` throws an exception.

src/asyncFromEntries.mjs

@@ -14,6 +14,7 @@ import asyncIterableWrap from './asyncIterableWrap.mjs'
  *   * The value
  * @returns {Promise<object>} A promise that will be resolved with a new object built with the
  * key-value pairs of the iterable.
+ * @see {@link generatorEntries} to convert an object to an iterable of key-value pairs
  * @example
  * // Example using a synchronous iterable
  * import { asyncFromEntries } from 'modern-async'

src/asyncGeneratorFilter.mjs

@@ -7,7 +7,7 @@ import asyncWrap from './asyncWrap.mjs'
 /**
  * Produces a an async iterable that will return each value or `iterable` which pass an asynchronous truth test.
  *
- * The iterable will perform the calls to `iteratee` in a queue to limit the concurrency of
+ * The iterable will perform the calls to `iteratee` asynchronously in a {@link Queue} to limit the concurrency of
  * these calls. The iterable will consume values from `iterable` only if slots are available in the
  * queue.
  *
@@ -23,8 +23,8 @@ import asyncWrap from './asyncWrap.mjs'
  *   * `value`: The current value to process
  *   * `index`: The index in the iterable. Will start from 0.
  *   * `iterable`: The iterable on which the operation is being performed.
- * @param {Queue | number} [queueOrConcurrency] If a queue is specified it will be used to schedule the calls to
- * `iteratee`. If a number is specified it will be used as the concurrency of a Queue that will be created
+ * @param {Queue | number} [queueOrConcurrency] If a {@link Queue} is specified it will be used to schedule the calls to
+ * `iteratee`. If a number is specified it will be used as the concurrency of a {@link Queue} that will be created
  * implicitly for the same purpose. Defaults to `1`.
  * @param {boolean} [ordered] If true the results will be yielded in the same order as in the source
  * iterable, regardless of which calls to iteratee returned first. If false the the results will be yielded as soon

src/asyncGeneratorMap.mjs

@@ -10,7 +10,7 @@ import reflectAsyncStatus from './reflectAsyncStatus.mjs'
  * Produces a an async iterable that will return each value or `iterable` after having processed them through
  * the `iteratee` function.
  *
- * The iterable will perform the calls to `iteratee` in a queue to limit the concurrency of
+ * The iterable will perform the calls to `iteratee` asynchronously in a {@link Queue} to limit the concurrency of
  * these calls. The iterable will consume values from `iterable` only if slots are available in the
  * queue.
  *
@@ -26,8 +26,8 @@ import reflectAsyncStatus from './reflectAsyncStatus.mjs'
  *   * `value`: The current value to process
  *   * `index`: The index in the iterable. Will start from 0.
  *   * `iterable`: The iterable on which the operation is being performed.
- * @param {Queue | number} [queueOrConcurrency] If a queue is specified it will be used to schedule the calls to
- * `iteratee`. If a number is specified it will be used as the concurrency of a Queue that will be created
+ * @param {Queue | number} [queueOrConcurrency] If a {@link Queue} is specified it will be used to schedule the calls to
+ * `iteratee`. If a number is specified it will be used as the concurrency of a {@link Queue} that will be created
  * implicitly for the same purpose. Defaults to `1`.
  * @param {boolean} [ordered] If true the results will be yielded in the same order as in the source
  * iterable, regardless of which calls to iteratee returned first. If false the the results will be yielded as soon

src/asyncMap.mjs

@@ -6,7 +6,7 @@ import asyncIterableToArray from './asyncIterableToArray.mjs'
 /**
  * Produces a new collection of values by mapping each value in `iterable` through the `iteratee` function.
  *
- * The calls to `iteratee` will be performed in a queue to limit the concurrency of these calls.
+ * The calls to `iteratee` will be performed asynchronously in a {@link Queue} to limit the concurrency of these calls.
  *
  * If any of the calls to iteratee throws an exception the returned promise will be rejected and the remaining
  * pending tasks will be cancelled.
@@ -17,8 +17,8 @@ import asyncIterableToArray from './asyncIterableToArray.mjs'
  *   * `value`: The current value to process
  *   * `index`: The index in the iterable. Will start from 0.
  *   * `iterable`: The iterable on which the operation is being performed.
- * @param {Queue | number} [queueOrConcurrency] If a queue is specified it will be used to schedule the calls to
- * `iteratee`. If a number is specified it will be used as the concurrency of a Queue that will be created
+ * @param {Queue | number} [queueOrConcurrency] If a {@link Queue} is specified it will be used to schedule the calls to
+ * `iteratee`. If a number is specified it will be used as the concurrency of a {@link Queue} that will be created
  * implicitly for the same purpose. Defaults to `1`.
  * @returns {Promise<any[]>} A promise that will be resolved with an array containing all the mapped value,
  * or will be rejected if any of the calls to `iteratee` throws an exception.

src/asyncMapEntries.mjs

@@ -10,7 +10,7 @@ import asyncWrap from './asyncWrap.mjs'
  * function, returning a new key-value pair, and re-construct a new object with the new
  * key-value pairs.
  *
- * The calls to `iteratee` will be performed in a queue to limit the concurrency of these calls.
+ * The calls to `iteratee` will be performed asynchronously in a {@link Queue} to limit the concurrency of these calls.
  *
  * If any of the calls to iteratee throws an exception the returned promise will be rejected and the remaining
  * pending tasks will be cancelled.
@@ -25,11 +25,13 @@ import asyncWrap from './asyncWrap.mjs'
  * That function must return a tuple containing two objects:
  *   * The mapped key.
  *   * The mapped value.
- * @param {Queue | number} [queueOrConcurrency] If a queue is specified it will be used to schedule the calls to
- * `iteratee`. If a number is specified it will be used as the concurrency of a Queue that will be created
+ * @param {Queue | number} [queueOrConcurrency] If a {@link Queue} is specified it will be used to schedule the calls to
+ * `iteratee`. If a number is specified it will be used as the concurrency of a {@link Queue} that will be created
  * implicitly for the same purpose. Defaults to `1`.
  * @returns {Promise<object>} A promise that will be resolved with a new object built with the
  * key-value pairs returned by `iteratee`.
+ * @see {@link asyncMapValues} to map values of an object
+ * @see {@link asyncMapKeys} to map keys of an object
  * @example
  * // example using the default concurrency of 1
  * import { asyncMapEntries, asyncSleep } from 'modern-async'

src/asyncMapKeys.mjs

@@ -7,7 +7,7 @@ import asyncWrap from './asyncWrap.mjs'
  * Maps the keys found in an object by calling the `iteratee`
  * function, returning a new key, and re-construct a new object with the new keys.
  *
- * The calls to `iteratee` will be performed in a queue to limit the concurrency of these calls.
+ * The calls to `iteratee` will be performed asynchronously in a {@link Queue} to limit the concurrency of these calls.
  *
  * If any of the calls to iteratee throws an exception the returned promise will be rejected and the remaining
  * pending tasks will be cancelled.
@@ -18,11 +18,13 @@ import asyncWrap from './asyncWrap.mjs'
  *   * `value`: The current value to process
  *   * `key`: The current key to process
  *   * `obj`: The object on which the operation is being performed.
- * @param {Queue | number} [queueOrConcurrency] If a queue is specified it will be used to schedule the calls to
- * `iteratee`. If a number is specified it will be used as the concurrency of a Queue that will be created
+ * @param {Queue | number} [queueOrConcurrency] If a {@link Queue} is specified it will be used to schedule the calls to
+ * `iteratee`. If a number is specified it will be used as the concurrency of a {@link Queue} that will be created
  * implicitly for the same purpose. Defaults to `1`.
  * @returns {Promise<object>} A promise that will be resolved with a new object built with the
  * new keys returned by `iteratee`.
+ * @see {@link asyncMapValues} to map values of an object
+ * @see {@link asyncMapEntries} to map both keys and values of an object simultaneously
  * @example
  * // example using the default concurrency of 1
  * import { asyncMapKeys, asyncSleep } from 'modern-async'

src/asyncMapValues.mjs

@@ -7,7 +7,7 @@ import asyncWrap from './asyncWrap.mjs'
  * Maps the values found in an object by calling the `iteratee`
  * function, returning a new value, and re-construct a new object with the new values.
  *
- * The calls to `iteratee` will be performed in a queue to limit the concurrency of these calls.
+ * The calls to `iteratee` will be performed asynchronously in a {@link Queue} to limit the concurrency of these calls.
  *
  * If any of the calls to iteratee throws an exception the returned promise will be rejected and the remaining
  * pending tasks will be cancelled.
@@ -18,11 +18,13 @@ import asyncWrap from './asyncWrap.mjs'
  *   * `value`: The current value to process
  *   * `key`: The current key to process
  *   * `obj`: The object on which the operation is being performed.
- * @param {Queue | number} [queueOrConcurrency] If a queue is specified it will be used to schedule the calls to
- * `iteratee`. If a number is specified it will be used as the concurrency of a Queue that will be created
+ * @param {Queue | number} [queueOrConcurrency] If a {@link Queue} is specified it will be used to schedule the calls to
+ * `iteratee`. If a number is specified it will be used as the concurrency of a {@link Queue} that will be created
  * implicitly for the same purpose. Defaults to `1`.
  * @returns {Promise<object>} A promise that will be resolved with a new object built with the
  * new values returned by `iteratee`.
+ * @see {@link asyncMapKeys} to map keys of an object
+ * @see {@link asyncMapEntries} to map both keys and values of an object simultaneously
  * @example
  * // example using the default concurrency of 1
  * import { asyncMapValues, asyncSleep } from 'modern-async'

src/asyncSleep.mjs

@@ -9,6 +9,9 @@ import asyncSleepCancellable from './asyncSleepCancellable.mjs'
  *
  * @param {number} amount An amount of time in milliseconds
  * @returns {Promise<void>} A promise that will be resolved after the given amount of time has passed.
+ * @see {@link asyncSleepCancellable} for a cancellable sleep implementation
+ * @see {@link asyncSleepPrecise} for a sleep implementation that can't trigger before the asked delay
+ * @see {@link asyncSleepPreciseCancellable} for a cancellable sleep implementation that can't trigger before the asked delay
  * @example
  * import { asyncSleep } from 'modern-async'
  *

src/asyncSleepCancellable.mjs

@@ -16,6 +16,9 @@ import CancelledError from './CancelledError.mjs'
  *   * `promise`: The promise
  *   * `cancel`: The cancel function. It will return a boolean that will be `true` if the promise was effectively cancelled,
  *     `false` otherwise.
+ * @see {@link asyncSleep} for a base sleep implementation
+ * @see {@link asyncSleepPrecise} for a sleep implementation that can't trigger before the asked delay
+ * @see {@link asyncSleepPreciseCancellable} for a cancellable sleep implementation that can't trigger before the asked delay
  * @example
  * import { asyncSleepCancellable } from 'modern-async'
  *

src/asyncSleepPrecise.mjs

@@ -4,7 +4,7 @@ import asyncSleepPreciseCancellable from './asyncSleepPreciseCancellable.mjs'
 /**
  * Waits a given amount of time.
  *
- * This function is similar to `asyncSleep()` except it ensures that the amount of time measured
+ * This function is similar to {@link asyncSleep} except it ensures that the amount of time measured
  * using the `Date` object is always greater than or equal the asked amount of time.
  *
  * This function can imply additional delay that can be bad for performances. As such it is
@@ -14,6 +14,9 @@ import asyncSleepPreciseCancellable from './asyncSleepPreciseCancellable.mjs'
  *
  * @param {number} amount An amount of time in milliseconds
  * @returns {Promise<void>} A promise that will be resolved after the given amount of time has passed.
+ * @see {@link asyncSleep} for a base sleep implementation
+ * @see {@link asyncSleepCancellable} for a cancellable sleep implementation
+ * @see {@link asyncSleepPreciseCancellable} for a cancellable sleep implementation that can't trigger before the asked delay
  * @example
  * import { asyncSleepPrecise } from 'modern-async'
  *