docs: update jsdoc comments

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