From 8483ad38fa662eda7149eed3a08b73d884a6a5c1 Mon Sep 17 00:00:00 2001
From: Alisue <lambdalisue@gmail.com>
Date: Thu, 8 Aug 2024 12:36:23 +0900
Subject: [PATCH 1/2] docs: update jsdoc comments

---
 async/chain.ts      | 7 ++++---
 async/compact.ts    | 2 +-
 async/compress.ts   | 2 +-
 async/drop.ts       | 5 ++---
 async/enumerate.ts  | 2 +-
 async/first.ts      | 3 +--
 async/for_each.ts   | 1 +
 async/iter.ts       | 2 +-
 async/take.ts       | 7 +++----
 async/take_while.ts | 2 +-
 async/uniq.ts       | 2 +-
 async/zip.ts        | 3 +++
 chain.ts            | 7 ++++---
 compact.ts          | 2 +-
 compress.ts         | 2 +-
 drop.ts             | 5 ++---
 enumerate.ts        | 2 +-
 first.ts            | 3 +--
 for_each.ts         | 1 +
 iter.ts             | 2 +-
 range.ts            | 1 +
 take.ts             | 7 +++----
 take_while.ts       | 2 +-
 to_array.ts         | 2 ++
 uniq.ts             | 2 +-
 zip.ts              | 3 +++
 26 files changed, 43 insertions(+), 36 deletions(-)

diff --git a/async/chain.ts b/async/chain.ts
index cf9e8ad..b1938b3 100644
--- a/async/chain.ts
+++ b/async/chain.ts
@@ -13,9 +13,7 @@
  * console.log(await toArray(iter)); // [1, 2, 3, 4]
  * ```
  *
- * It supports chaining malformed iterables.
- *
- * @example
+ * @example With malformed iterables
  * ```ts
  * import { toArray } from "@core/iterutil/async/to-array";
  * import { chain } from "@core/iterutil/async/chain";
@@ -36,6 +34,9 @@ export async function* chain<
   }
 }
 
+/**
+ * @inner
+ */
 export type Chain<T> = T extends readonly [] ? never
   : T extends readonly [Iterable<infer U>] ? U
   : T extends readonly [AsyncIterable<infer U>] ? U
diff --git a/async/compact.ts b/async/compact.ts
index 92ec059..d47a836 100644
--- a/async/compact.ts
+++ b/async/compact.ts
@@ -1,5 +1,5 @@
 /**
- * Removes all nullish values from an iterable.
+ * Removes all nullish (`null` or `undefined`) values from an iterable.
  *
  * @param iterable The iterable to compact.
  * @returns The compacted iterable.
diff --git a/async/compress.ts b/async/compress.ts
index 9d75e04..09378ae 100644
--- a/async/compress.ts
+++ b/async/compress.ts
@@ -1,5 +1,5 @@
 /**
- * Compress an iterable by selecting elements using a selector iterable.
+ * Compresses an iterable by selecting elements using a selector iterable.
  *
  * @param iterable The iterable to compress.
  * @param selectors The selectors to use.
diff --git a/async/drop.ts b/async/drop.ts
index 35246bc..20750e9 100644
--- a/async/drop.ts
+++ b/async/drop.ts
@@ -1,11 +1,10 @@
 /**
  * Drops the first `limit` items from the iterable.
  *
- * It throws an error if `limit` is less than 0.
- *
  * @param iterable The iterable to drop items from.
- * @param limit The number of items to drop.
+ * @param limit The number of items to drop. It must be 0 or positive safe integer.
  * @returns The iterable with the first `limit` items dropped.
+ * @throws {DropLimitError} If `limit` is less than 0 or non safe integer.
  *
  * @example
  * ```ts
diff --git a/async/enumerate.ts b/async/enumerate.ts
index c92e9ed..13aedb5 100644
--- a/async/enumerate.ts
+++ b/async/enumerate.ts
@@ -1,5 +1,5 @@
 /**
- * Enumerate an iterable.
+ * Enumerates an iterable.
  *
  * @param iterable The iterable to enumerate.
  * @param start The starting index.
diff --git a/async/first.ts b/async/first.ts
index 831c8aa..b2133c6 100644
--- a/async/first.ts
+++ b/async/first.ts
@@ -1,6 +1,5 @@
 /**
- * Returns the first element of an iterable.
- * If the iterable is empty, returns `undefined`.
+ * Returns the first element of an iterable. If the iterable is empty, returns `undefined`.
  *
  * @param iterable The iterable to get the first element from.
  * @returns The first element of the iterable, or `undefined` if the iterable is empty.
diff --git a/async/for_each.ts b/async/for_each.ts
index f652294..407d422 100644
--- a/async/for_each.ts
+++ b/async/for_each.ts
@@ -7,6 +7,7 @@
  * @example
  * ```ts
  * import { forEach } from "@core/iterutil/async/for-each";
+ *
  * await forEach([1, 2, 3], console.log);
  * // 1
  * // 2
diff --git a/async/iter.ts b/async/iter.ts
index 633363b..2ffb7bc 100644
--- a/async/iter.ts
+++ b/async/iter.ts
@@ -1,5 +1,5 @@
 /**
- * Convert an iterable to an iterator.
+ * Converts an iterable to an iterator.
  *
  * @param iterable The iterable to convert.
  * @returns The iterator.
diff --git a/async/take.ts b/async/take.ts
index 5118d85..f2cca28 100644
--- a/async/take.ts
+++ b/async/take.ts
@@ -1,11 +1,10 @@
 /**
- * Take the first `limit` items from the iterable.
- *
- * It throws an error if `limit` is less than 0.
+ * Takes the first `limit` items from the iterable.
  *
  * @param iterable The iterable to take items from.
- * @param limit The number of items to take.
+ * @param limit The number of items to take. It must be 0 or positive safe integer.
  * @returns The iterable with the first `limit` items taken.
+ * @throws {TakeLimitError} If `limit` is less than 0 or non safe integer.
  *
  * @example
  * ```ts
diff --git a/async/take_while.ts b/async/take_while.ts
index 07bd64f..5ee4bc6 100644
--- a/async/take_while.ts
+++ b/async/take_while.ts
@@ -1,5 +1,5 @@
 /**
- * Take elements from the iterable while the predicate is true.
+ * Takes elements from the iterable while the predicate is true.
  *
  * @param iterable The iterable to take elements from.
  * @param fn The predicate to take elements with.
diff --git a/async/uniq.ts b/async/uniq.ts
index cc6eb15..bc42f22 100644
--- a/async/uniq.ts
+++ b/async/uniq.ts
@@ -14,7 +14,7 @@
  * console.log(await toArray(iter)); // [1, 2, 3]
  * ```
  *
- * @example
+ * @example With identify function
  * ```ts
  * import { toArray } from "@core/iterutil/async/to-array";
  * import { uniq } from "@core/iterutil/async/uniq";
diff --git a/async/zip.ts b/async/zip.ts
index 474758e..5980bf3 100644
--- a/async/zip.ts
+++ b/async/zip.ts
@@ -32,6 +32,9 @@ export async function* zip<
   }
 }
 
+/**
+ * @inner
+ */
 export type Zip<T extends (Iterable<unknown> | AsyncIterable<unknown>)[]> = {
   [P in keyof T]: T[P] extends Iterable<infer U> ? U
     : T[P] extends AsyncIterable<infer U> ? U
diff --git a/chain.ts b/chain.ts
index 2b601a1..00c7bf2 100644
--- a/chain.ts
+++ b/chain.ts
@@ -12,9 +12,7 @@
  * console.log([...iter]); // [1, 2, 3, 4]
  * ```
  *
- * It supports chaining malformed iterables.
- *
- * @example
+ * @example With malformed iterables
  * ```ts
  * import { chain } from "@core/iterutil/chain";
  *
@@ -30,6 +28,9 @@ export function* chain<T extends Iterable<unknown>[]>(
   }
 }
 
+/**
+ * @inner
+ */
 export type Chain<T> = T extends readonly [] ? never
   : T extends readonly [Iterable<infer U>] ? U
   : T extends readonly [Iterable<infer U>, ...infer R] ? U | Chain<R>
diff --git a/compact.ts b/compact.ts
index ec17c38..a61c2fb 100644
--- a/compact.ts
+++ b/compact.ts
@@ -1,5 +1,5 @@
 /**
- * Removes all nullish values from an iterable.
+ * Removes all nullish (`null` or `undefined`) values from an iterable.
  *
  * @param iterable The iterable to compact.
  * @returns The compacted iterable.
diff --git a/compress.ts b/compress.ts
index d38fa79..28f3d37 100644
--- a/compress.ts
+++ b/compress.ts
@@ -1,5 +1,5 @@
 /**
- * Compress an iterable by selecting elements using a selector iterable.
+ * Compresses an iterable by selecting elements using a selector iterable.
  *
  * @param iterable The iterable to compress.
  * @param selectors The selectors to use.
diff --git a/drop.ts b/drop.ts
index beb24a5..426b1b2 100644
--- a/drop.ts
+++ b/drop.ts
@@ -1,11 +1,10 @@
 /**
  * Drops the first `limit` items from the iterable.
  *
- * It throws an error if `limit` is less than 0.
- *
  * @param iterable The iterable to drop items from.
- * @param limit The number of items to drop.
+ * @param limit The number of items to drop. It must be 0 or positive safe integer.
  * @returns The iterable with the first `limit` items dropped.
+ * @throws {DropLimitError} If `limit` is less than 0 or non safe integer.
  *
  * @example
  * ```ts
diff --git a/enumerate.ts b/enumerate.ts
index 5231333..69fdc77 100644
--- a/enumerate.ts
+++ b/enumerate.ts
@@ -1,5 +1,5 @@
 /**
- * Enumerate an iterable.
+ * Enumerates an iterable.
  *
  * @param iterable The iterable to enumerate.
  * @param start The starting index.
diff --git a/first.ts b/first.ts
index 41c3c81..894d76d 100644
--- a/first.ts
+++ b/first.ts
@@ -1,6 +1,5 @@
 /**
- * Returns the first element of an iterable.
- * If the iterable is empty, returns `undefined`.
+ * Returns the first element of an iterable. If the iterable is empty, returns `undefined`.
  *
  * @param iterable The iterable to get the first element from.
  * @returns The first element of the iterable, or `undefined` if the iterable is empty.
diff --git a/for_each.ts b/for_each.ts
index 8673811..c75014f 100644
--- a/for_each.ts
+++ b/for_each.ts
@@ -7,6 +7,7 @@
  * @example
  * ```ts
  * import { forEach } from "@core/iterutil/for-each";
+ *
  * forEach([1, 2, 3], console.log);
  * // 1
  * // 2
diff --git a/iter.ts b/iter.ts
index 63e500c..4ac7d22 100644
--- a/iter.ts
+++ b/iter.ts
@@ -1,5 +1,5 @@
 /**
- * Convert an iterable to an iterator.
+ * Converts an iterable to an iterator.
  *
  * @param iterable The iterable to convert.
  * @returns The iterator.
diff --git a/range.ts b/range.ts
index a759c1c..3eaf920 100644
--- a/range.ts
+++ b/range.ts
@@ -3,6 +3,7 @@
  *
  * @param stop The end of the range.
  * @returns The range of numbers.
+ *
  * @example
  * ```ts
  * import { range } from "@core/iterutil/range";
diff --git a/take.ts b/take.ts
index 7cdd895..bc68c3d 100644
--- a/take.ts
+++ b/take.ts
@@ -1,11 +1,10 @@
 /**
- * Take the first `limit` items from the iterable.
- *
- * It throws an error if `limit` is less than 0.
+ * Takes the first `limit` items from the iterable.
  *
  * @param iterable The iterable to take items from.
- * @param limit The number of items to take.
+ * @param limit The number of items to take. It must be 0 or positive safe integer.
  * @returns The iterable with the first `limit` items taken.
+ * @throws {TakeLimitError} If `limit` is less than 0 or non safe integer.
  *
  * @example
  * ```ts
diff --git a/take_while.ts b/take_while.ts
index 350ccd9..a789a71 100644
--- a/take_while.ts
+++ b/take_while.ts
@@ -1,5 +1,5 @@
 /**
- * Take elements from the iterable while the predicate is true.
+ * Takes elements from the iterable while the predicate is true.
  *
  * @param iterable The iterable to take elements from.
  * @param fn The predicate to take elements with.
diff --git a/to_array.ts b/to_array.ts
index 2d6f5e6..3274890 100644
--- a/to_array.ts
+++ b/to_array.ts
@@ -1,6 +1,8 @@
 /**
  * Converts an iterable to an array.
  *
+ * Note that users should use `Array.from` directly. This function exists for consistency with `async/to-array.toArray`.
+ *
  * @param iterable The iterable to convert.
  * @returns The array.
  *
diff --git a/uniq.ts b/uniq.ts
index 6ac4939..4b24e93 100644
--- a/uniq.ts
+++ b/uniq.ts
@@ -13,7 +13,7 @@
  * console.log([...iter]); // [1, 2, 3]
  * ```
  *
- * @example
+ * @example With identify function
  * ```ts
  * import { uniq } from "@core/iterutil/uniq";
  *
diff --git a/zip.ts b/zip.ts
index 7927698..04e1cce 100644
--- a/zip.ts
+++ b/zip.ts
@@ -25,6 +25,9 @@ export function* zip<U extends Iterable<unknown>[]>(
   }
 }
 
+/**
+ * @inner
+ */
 export type Zip<T extends Iterable<unknown>[]> = {
   [P in keyof T]: T[P] extends Iterable<infer U> ? U : never;
 };

From e66d01ecffc70b866ec8411e49345a27a7177ca4 Mon Sep 17 00:00:00 2001
From: Alisue <lambdalisue@gmail.com>
Date: Thu, 8 Aug 2024 12:40:36 +0900
Subject: [PATCH 2/2] docs: update README

---
 README.md | 18 +++++++++---------
 1 file changed, 9 insertions(+), 9 deletions(-)

diff --git a/README.md b/README.md
index 7fe2222..df7ab0d 100644
--- a/README.md
+++ b/README.md
@@ -5,7 +5,7 @@
 [![codecov](https://codecov.io/github/jsr-core/iterutil/graph/badge.svg?token=pfbLRGU5AM)](https://codecov.io/github/jsr-core/iterutil)
 
 Iterator / AsyncIterator utility pack for JavaScript and TypeScript. Each module
-is designed to work independently, avoiding internal interdependencies as much
+is designed to work independently, avoiding internal inter-dependencies as much
 as possible.
 
 ## Usage
@@ -16,7 +16,7 @@ both synchronous and asynchronous iterables (`Iterable` and `AsyncIterable`).
 
 ### chain
 
-Chains multiple iterables or async iterables together.
+Chains multiple iterables together.
 
 ```ts
 import { chain } from "@core/iterutil/chain";
@@ -54,7 +54,7 @@ console.log(await toArray(iter)); // [[1, 2], [3, 4], [5]]
 
 ### compact
 
-Removes all nullish values from an iterable.
+Removes all nullish (`null` or `undefined`) values from an iterable.
 
 ```ts
 import { compact } from "@core/iterutil/compact";
@@ -73,7 +73,7 @@ console.log(await toArray(iter)); // [1, 2, 3]
 
 ### compress
 
-Compress an iterable by selecting elements using a selector iterable.
+Compresses an iterable by selecting elements using a selector iterable.
 
 ```ts
 import { compress } from "@core/iterutil/compress";
@@ -164,7 +164,7 @@ console.log(await toArray(iter)); // [3, 4, 5]
 
 ### enumerate
 
-Enumerate an iterable.
+Enumerates an iterable.
 
 ```ts
 import { enumerate } from "@core/iterutil/enumerate";
@@ -318,7 +318,7 @@ await forEach([1, 2, 3], console.log);
 
 ### iter
 
-Convert an iterable to an iterator.
+Converts an iterable to an iterator.
 
 ```ts
 import { iter } from "@core/iterutil/iter";
@@ -431,7 +431,7 @@ console.log(odd); // [1, 3, 5]
 
 ### range
 
-Generate a range of numbers.
+Generates a range of numbers.
 
 ```ts
 import { range } from "@core/iterutil/range";
@@ -492,7 +492,7 @@ console.log(await some([1, 3, 5], (value) => value % 2 === 0)); // false
 
 ### take
 
-Take the first `limit` items from the iterable.
+Takes the first `limit` items from the iterable.
 
 ```ts
 import { take } from "@core/iterutil/take";
@@ -511,7 +511,7 @@ console.log(await toArray(iter)); // [1, 2]
 
 ### takeWhile
 
-Take elements from the iterable while the predicate is true.
+Takes elements from the iterable while the predicate is true.
 
 ```ts
 import { takeWhile } from "@core/iterutil/take-while";