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

docs: update documentations

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";

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

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.

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.

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

async/enumerate.ts

@@ -1,5 +1,5 @@
 /**
- * Enumerate an iterable.
+ * Enumerates an iterable.
  *
  * @param iterable The iterable to enumerate.
  * @param start The starting index.

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.

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

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.

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

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.

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";

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

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>

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.

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.

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

enumerate.ts

@@ -1,5 +1,5 @@
 /**
- * Enumerate an iterable.
+ * Enumerates an iterable.
  *
  * @param iterable The iterable to enumerate.
  * @param start The starting index.

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.

for_each.ts

@@ -7,6 +7,7 @@
  * @example
  * ```ts
  * import { forEach } from "@core/iterutil/for-each";
+ *
  * forEach([1, 2, 3], console.log);
  * // 1
  * // 2

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.

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";

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

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.

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.
  *

uniq.ts

@@ -13,7 +13,7 @@
  * console.log([...iter]); // [1, 2, 3]
  * ```
  *
- * @example
+ * @example With identify function
  * ```ts
  * import { uniq } from "@core/iterutil/uniq";
  *

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;
 };