From d0fad009f745bd7ce64f92438f2dfd51a7bdc07c Mon Sep 17 00:00:00 2001
From: Robin Pokorny <robin.pokorny@klarna.com>
Date: Tue, 13 Jul 2021 21:32:20 +0200
Subject: [PATCH] :abc: add example use

---
 docs/README.md | 25 +++++++++++++++++++++++--
 src/index.ts   | 22 ++++++++++++++++++++++
 2 files changed, 45 insertions(+), 2 deletions(-)

diff --git a/docs/README.md b/docs/README.md
index d51db51..9a224ed 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -28,13 +28,15 @@ Promise Throttle All
 
 ▸ (): `Promise`<`T`\>
 
+A Task is a nullary function that returns a promise
+
 ##### Returns
 
 `Promise`<`T`\>
 
 #### Defined in
 
-[index.ts:1](https://github.com/robinpokorny/promise-throttle-all/blob/b09c7b6/src/index.ts#L1)
+[index.ts:4](https://github.com/robinpokorny/promise-throttle-all/blob/62c374f/src/index.ts#L4)
 
 ## Functions
 
@@ -42,6 +44,25 @@ Promise Throttle All
 
 ▸ `Const` **throttleAll**<`T`\>(`limit`, `tasks`): `Promise`<`T`[]\>
 
+Run tasks with limited concurency.
+
+**`example`** ```ts
+const task1 = () => new Promise((resolve) => {
+  setTimeout(resolve, 100, 1);
+});
+const task2 = () => Promise.resolve(2);
+
+throttleAll(1, [task1, task2])
+  .then((values) => { console.log(values) });
+// task2 will run after task2 finishes
+// logs: `[1, 2]`
+```
+@param limit - Limit of tasks that run at once.
+@param tasks - List of tasks to run.
+@returns A promise that fulfills to an array of the results
+of the input promises or rejects immediately upon any of
+the input tasks rejecting.
+
 #### Type parameters
 
 | Name |
@@ -61,4 +82,4 @@ Promise Throttle All
 
 #### Defined in
 
-[index.ts:5](https://github.com/robinpokorny/promise-throttle-all/blob/b09c7b6/src/index.ts#L5)
+[index.ts:27](https://github.com/robinpokorny/promise-throttle-all/blob/62c374f/src/index.ts#L27)
diff --git a/src/index.ts b/src/index.ts
index 1bca220..c51d3ed 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -1,7 +1,29 @@
+/**
+ * A Task is a nullary function that returns a promise
+ */
 export type Task<T> = () => Promise<T>
 
 const notSettled = Symbol(`not-settled`)
 
+/**
+ * Run tasks with limited concurency.
+ * @example ```ts
+ * const task1 = () => new Promise((resolve) => {
+ *   setTimeout(resolve, 100, 1);
+ * });
+ * const task2 = () => Promise.resolve(2);
+ *
+ * throttleAll(1, [task1, task2])
+ *   .then((values) => { console.log(values) });
+ * // task2 will run after task2 finishes
+ * // logs: `[1, 2]`
+ * ```
+ * @param limit - Limit of tasks that run at once.
+ * @param tasks - List of tasks to run.
+ * @returns A promise that fulfills to an array of the results
+ * of the input promises or rejects immediately upon any of
+ * the input tasks rejecting.
+ */
 export const throttleAll = <T>(
   limit: number,
   tasks: Task<T>[],