Merge pull request #6 from jsr-core/fix-docs

lambdalisue · web-flow · commit 2b00af8f99f2 · 2024-08-08T12:45:05.000+09:00
docs: update documentations
diff --git 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";
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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;
 };

Original file line number	Diff line number	Diff line change
`@@ -13,9 +13,7 @@`
`13`	`13`	`* console.log(await toArray(iter)); // [1, 2, 3, 4]`
`14`	`14`	* ```
`15`	`15`	`*`
`16`		`- * It supports chaining malformed iterables.`
`17`		`- *`
`18`		`- * @example`
	`16`	`+ * @example With malformed iterables`
`19`	`17`	* ```ts
`20`	`18`	`* import { toArray } from "@core/iterutil/async/to-array";`
`21`	`19`	`* import { chain } from "@core/iterutil/async/chain";`
`@@ -36,6 +34,9 @@ export async function* chain<`
`36`	`34`	`}`
`37`	`35`	`}`
`38`	`36`
	`37`	`+/**`
	`38`	`+ * @inner`
	`39`	`+ */`
`39`	`40`	`export type Chain<T> = T extends readonly [] ? never`
`40`	`41`	`: T extends readonly [Iterable<infer U>] ? U`
`41`	`42`	`: T extends readonly [AsyncIterable<infer U>] ? U`
Original file line number	Diff line number	Diff line change
`@@ -1,5 +1,5 @@`
`1`	`1`	`/**`
`2`		`- * Removes all nullish values from an iterable.`
	`2`	+ * Removes all nullish (`null` or `undefined`) values from an iterable.
`3`	`3`	`*`
`4`	`4`	`* @param iterable The iterable to compact.`
`5`	`5`	`* @returns The compacted iterable.`
Original file line number	Diff line number	Diff line change
`@@ -1,5 +1,5 @@`
`1`	`1`	`/**`
`2`		`- * Compress an iterable by selecting elements using a selector iterable.`
	`2`	`+ * Compresses an iterable by selecting elements using a selector iterable.`
`3`	`3`	`*`
`4`	`4`	`* @param iterable The iterable to compress.`
`5`	`5`	`* @param selectors The selectors to use.`
Original file line number	Diff line number	Diff line change
`@@ -1,11 +1,10 @@`
`1`	`1`	`/**`
`2`	`2`	* Drops the first `limit` items from the iterable.
`3`	`3`	`*`
`4`		- * It throws an error if `limit` is less than 0.
`5`		`- *`
`6`	`4`	`* @param iterable The iterable to drop items from.`
`7`		`- * @param limit The number of items to drop.`
	`5`	`+ * @param limit The number of items to drop. It must be 0 or positive safe integer.`
`8`	`6`	* @returns The iterable with the first `limit` items dropped.
	`7`	+ * @throws {DropLimitError} If `limit` is less than 0 or non safe integer.
`9`	`8`	`*`
`10`	`9`	`* @example`
`11`	`10`	* ```ts
Original file line number	Diff line number	Diff line change
`@@ -1,5 +1,5 @@`
`1`	`1`	`/**`
`2`		`- * Enumerate an iterable.`
	`2`	`+ * Enumerates an iterable.`
`3`	`3`	`*`
`4`	`4`	`* @param iterable The iterable to enumerate.`
`5`	`5`	`* @param start The starting index.`
Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,5 @@`
`1`	`1`	`/**`
`2`		`- * Returns the first element of an iterable.`
`3`		- * If the iterable is empty, returns `undefined`.
	`2`	+ * Returns the first element of an iterable. If the iterable is empty, returns `undefined`.
`4`	`3`	`*`
`5`	`4`	`* @param iterable The iterable to get the first element from.`
`6`	`5`	* @returns The first element of the iterable, or `undefined` if the iterable is empty.
Original file line number	Diff line number	Diff line change
`@@ -1,5 +1,5 @@`
`1`	`1`	`/**`
`2`		`- * Convert an iterable to an iterator.`
	`2`	`+ * Converts an iterable to an iterator.`
`3`	`3`	`*`
`4`	`4`	`* @param iterable The iterable to convert.`
`5`	`5`	`* @returns The iterator.`