effect 4.0.0-beta.66 → 4.0.0-beta.68

package/dist/Iterable.d.ts

@@ -10,7 +10,8 @@
  * for stream processing and memory-efficient data manipulation. All functions in this
  * module preserve the lazy nature of iterables where possible.
  *
- * @example
+ * **Example** (Working with iterables)
+ *
  * ```ts
  * import { Iterable, Option } from "effect"
  *
@@ -41,10 +42,8 @@ import type { NoInfer } from "./Types.ts";
  * with each index starting from 0. If no length is specified, the iterable will
  * be infinite. This is useful for generating sequences, patterns, or any indexed data.
  *
- * @param f - Function that receives the index and returns the element
- * @param options - Configuration object with optional length
+ * **Example** (Generating values by index)
  *
- * @example
  * ```ts
  * import { Iterable } from "effect"
  *
@@ -69,16 +68,19 @@ export declare const makeBy: <A>(f: (i: number) => A, options?: {
     readonly length?: number;
 }) => Iterable<A>;
 /**
- * Return a `Iterable` containing a range of integers, including both endpoints.
+ * Returns an iterable of integers starting at `start` and increasing by `1`.
+ *
+ * When `end` is provided and `start <= end`, both endpoints are included. When
+ * `end` is omitted, the iterable is unbounded. When `start > end`, the
+ * iterable contains only `start`.
  *
- * If `end` is omitted, the range will not have an upper bound.
+ * **Example** (Creating a range)
  *
- * @example
  * ```ts
- * import { range } from "effect/Iterable"
+ * import { Iterable } from "effect"
  * import * as assert from "node:assert"
  *
- * assert.deepStrictEqual(Array.from(range(1, 3)), [1, 2, 3])
+ * assert.deepStrictEqual(Array.from(Iterable.range(1, 3)), [1, 2, 3])
  * ```
  *
  * @category constructors
@@ -90,12 +92,13 @@ export declare const range: (start: number, end?: number) => Iterable<number>;
  *
  * **Note**. `n` is normalized to an integer >= 1.
  *
- * @example
+ * **Example** (Repeating a value)
+ *
  * ```ts
- * import { replicate } from "effect/Iterable"
+ * import { Iterable } from "effect"
  * import * as assert from "node:assert"
  *
- * assert.deepStrictEqual(Array.from(replicate("a", 3)), ["a", "a", "a"])
+ * assert.deepStrictEqual(Array.from(Iterable.replicate("a", 3)), ["a", "a", "a"])
  * ```
  *
  * @category constructors
@@ -107,12 +110,13 @@ export declare const replicate: {
      *
      * **Note**. `n` is normalized to an integer >= 1.
      *
-     * @example
+     * **Example** (Repeating a value)
+     *
      * ```ts
-     * import { replicate } from "effect/Iterable"
+     * import { Iterable } from "effect"
      * import * as assert from "node:assert"
      *
-     * assert.deepStrictEqual(Array.from(replicate("a", 3)), ["a", "a", "a"])
+     * assert.deepStrictEqual(Array.from(Iterable.replicate("a", 3)), ["a", "a", "a"])
      * ```
      *
      * @category constructors
@@ -124,12 +128,13 @@ export declare const replicate: {
      *
      * **Note**. `n` is normalized to an integer >= 1.
      *
-     * @example
+     * **Example** (Repeating a value)
+     *
      * ```ts
-     * import { replicate } from "effect/Iterable"
+     * import { Iterable } from "effect"
      * import * as assert from "node:assert"
      *
-     * assert.deepStrictEqual(Array.from(replicate("a", 3)), ["a", "a", "a"])
+     * assert.deepStrictEqual(Array.from(Iterable.replicate("a", 3)), ["a", "a", "a"])
      * ```
      *
      * @category constructors
@@ -138,22 +143,42 @@ export declare const replicate: {
     <A>(a: A, n: number): Iterable<A>;
 };
 /**
+ * Repeats an iterable `n` times, yielding the full contents of `self` for each
+ * repetition.
+ *
+ * The result is lazy. Each repetition obtains a new iterator from `self`.
+ *
  * @category constructors
  * @since 4.0.0
  */
 export declare const repeat: {
     /**
+     * Repeats an iterable `n` times, yielding the full contents of `self` for each
+     * repetition.
+     *
+     * The result is lazy. Each repetition obtains a new iterator from `self`.
+     *
      * @category constructors
      * @since 4.0.0
      */
     (n: number): <A>(self: Iterable<A>) => Iterable<A>;
     /**
+     * Repeats an iterable `n` times, yielding the full contents of `self` for each
+     * repetition.
+     *
+     * The result is lazy. Each repetition obtains a new iterator from `self`.
+     *
      * @category constructors
      * @since 4.0.0
      */
     <A>(self: Iterable<A>, n: number): Iterable<A>;
 };
 /**
+ * Repeats an iterable without an upper bound.
+ *
+ * The returned iterable is lazy and should usually be bounded with `take` or
+ * another terminating consumer before materializing it.
+ *
  * @category constructors
  * @since 4.0.0
  */
@@ -161,26 +186,28 @@ export declare const forever: <A>(self: Iterable<A>) => Iterable<A>;
 /**
  * Takes a record and returns an Iterable of tuples containing its keys and values.
  *
- * @example
+ * **Example** (Converting a record to entries)
+ *
  * ```ts
- * import { fromRecord } from "effect/Iterable"
+ * import { Iterable } from "effect"
  * import * as assert from "node:assert"
  *
  * const x = { a: 1, b: 2, c: 3 }
- * assert.deepStrictEqual(Array.from(fromRecord(x)), [["a", 1], ["b", 2], [
+ * assert.deepStrictEqual(Array.from(Iterable.fromRecord(x)), [["a", 1], ["b", 2], [
  *   "c",
  *   3
  * ]])
  * ```
  *
- * @category conversions
+ * @category converting
  * @since 2.0.0
  */
 export declare const fromRecord: <K extends string, A>(self: Readonly<Record<K, A>>) => Iterable<[K, A]>;
 /**
  * Prepend an element to the front of an `Iterable`, creating a new `Iterable`.
  *
- * @example
+ * **Example** (Prepending an element)
+ *
  * ```ts
  * import { Iterable } from "effect"
  *
@@ -201,7 +228,8 @@ export declare const prepend: {
     /**
      * Prepend an element to the front of an `Iterable`, creating a new `Iterable`.
      *
-     * @example
+     * **Example** (Prepending an element)
+     *
      * ```ts
      * import { Iterable } from "effect"
      *
@@ -222,7 +250,8 @@ export declare const prepend: {
     /**
      * Prepend an element to the front of an `Iterable`, creating a new `Iterable`.
      *
-     * @example
+     * **Example** (Prepending an element)
+     *
      * ```ts
      * import { Iterable } from "effect"
      *
@@ -244,7 +273,8 @@ export declare const prepend: {
 /**
  * Prepends the specified prefix iterable to the beginning of the specified iterable.
  *
- * @example
+ * **Example** (Prepending another iterable)
+ *
  * ```ts
  * import { Iterable } from "effect"
  * import * as assert from "node:assert"
@@ -262,7 +292,8 @@ export declare const prependAll: {
     /**
      * Prepends the specified prefix iterable to the beginning of the specified iterable.
      *
-     * @example
+     * **Example** (Prepending another iterable)
+     *
      * ```ts
      * import { Iterable } from "effect"
      * import * as assert from "node:assert"
@@ -280,7 +311,8 @@ export declare const prependAll: {
     /**
      * Prepends the specified prefix iterable to the beginning of the specified iterable.
      *
-     * @example
+     * **Example** (Prepending another iterable)
+     *
      * ```ts
      * import { Iterable } from "effect"
      * import * as assert from "node:assert"
@@ -299,7 +331,8 @@ export declare const prependAll: {
 /**
  * Append an element to the end of an `Iterable`, creating a new `Iterable`.
  *
- * @example
+ * **Example** (Appending an element)
+ *
  * ```ts
  * import { Iterable } from "effect"
  *
@@ -322,7 +355,8 @@ export declare const append: {
     /**
      * Append an element to the end of an `Iterable`, creating a new `Iterable`.
      *
-     * @example
+     * **Example** (Appending an element)
+     *
      * ```ts
      * import { Iterable } from "effect"
      *
@@ -345,7 +379,8 @@ export declare const append: {
     /**
      * Append an element to the end of an `Iterable`, creating a new `Iterable`.
      *
-     * @example
+     * **Example** (Appending an element)
+     *
      * ```ts
      * import { Iterable } from "effect"
      *
@@ -369,7 +404,8 @@ export declare const append: {
 /**
  * Concatenates two iterables, combining their elements.
  *
- * @example
+ * **Example** (Concatenating iterables)
+ *
  * ```ts
  * import { Iterable } from "effect"
  *
@@ -398,7 +434,8 @@ export declare const appendAll: {
     /**
      * Concatenates two iterables, combining their elements.
      *
-     * @example
+     * **Example** (Concatenating iterables)
+     *
      * ```ts
      * import { Iterable } from "effect"
      *
@@ -427,7 +464,8 @@ export declare const appendAll: {
     /**
      * Concatenates two iterables, combining their elements.
      *
-     * @example
+     * **Example** (Concatenating iterables)
+     *
      * ```ts
      * import { Iterable } from "effect"
      *
@@ -457,7 +495,8 @@ export declare const appendAll: {
 /**
  * Reduce an `Iterable` from the left, keeping all intermediate results instead of only the final result.
  *
- * @example
+ * **Example** (Tracking running results)
+ *
  * ```ts
  * import { Iterable } from "effect"
  *
@@ -484,7 +523,8 @@ export declare const scan: {
     /**
      * Reduce an `Iterable` from the left, keeping all intermediate results instead of only the final result.
      *
-     * @example
+     * **Example** (Tracking running results)
+     *
      * ```ts
      * import { Iterable } from "effect"
      *
@@ -511,7 +551,8 @@ export declare const scan: {
     /**
      * Reduce an `Iterable` from the left, keeping all intermediate results instead of only the final result.
      *
-     * @example
+     * **Example** (Tracking running results)
+     *
      * ```ts
      * import { Iterable } from "effect"
      *
@@ -539,13 +580,14 @@ export declare const scan: {
 /**
  * Determine if an `Iterable` is empty
  *
- * @example
+ * **Example** (Checking for emptiness)
+ *
  * ```ts
- * import { isEmpty } from "effect/Iterable"
+ * import { Iterable } from "effect"
  * import * as assert from "node:assert"
  *
- * assert.deepStrictEqual(isEmpty([]), true)
- * assert.deepStrictEqual(isEmpty([1, 2, 3]), false)
+ * assert.deepStrictEqual(Iterable.isEmpty([]), true)
+ * assert.deepStrictEqual(Iterable.isEmpty([1, 2, 3]), false)
  * ```
  *
  * @category guards
@@ -555,7 +597,8 @@ export declare const isEmpty: <A>(self: Iterable<A>) => self is Iterable<never>;
 /**
  * Return the number of elements in a `Iterable`.
  *
- * @example
+ * **Example** (Counting iterable elements)
+ *
  * ```ts
  * import { Iterable } from "effect"
  *
@@ -581,10 +624,10 @@ export declare const size: <A>(self: Iterable<A>) => number;
 /**
  * Get the first element of a `Iterable`, or `None` if the `Iterable` is empty.
  *
- * @example
+ * **Example** (Getting the first element)
+ *
  * ```ts
- * import { Iterable } from "effect"
- * import * as Option from "effect/Option"
+ * import { Iterable, Option } from "effect"
  *
  * const numbers = [1, 2, 3]
  * console.log(Iterable.head(numbers)) // Option.some(1)
@@ -610,7 +653,8 @@ export declare const head: <A>(self: Iterable<A>) => Option<A>;
 /**
  * Get the first element of a `Iterable`, or throw an error if the `Iterable` is empty.
  *
- * @example
+ * **Example** (Getting the first element unsafely)
+ *
  * ```ts
  * import { Iterable } from "effect"
  *
@@ -620,13 +664,8 @@ export declare const head: <A>(self: Iterable<A>) => Option<A>;
  * const letters = "hello"
  * console.log(Iterable.headUnsafe(letters)) // "h"
  *
- * // This will throw an error!
- * try {
- *   const empty = Iterable.empty<number>()
- *   Iterable.headUnsafe(empty) // throws Error: "headUnsafe: empty iterable"
- * } catch (error) {
- *   console.log((error as Error).message) // "headUnsafe: empty iterable"
- * }
+ * // Iterable.headUnsafe(Iterable.empty<number>())
+ * // throws Error: "headUnsafe: empty iterable"
  *
  * // Use only when you're certain the iterable is non-empty
  * const nonEmpty = Iterable.range(1, 10)
@@ -634,7 +673,7 @@ export declare const head: <A>(self: Iterable<A>) => Option<A>;
  * ```
  *
  * @category getters
- * @since 3.3.0
+ * @since 4.0.0
  */
 export declare const headUnsafe: <A>(self: Iterable<A>) => A;
 /**
@@ -642,7 +681,8 @@ export declare const headUnsafe: <A>(self: Iterable<A>) => A;
  *
  * **Note**. `n` is normalized to a non negative integer.
  *
- * @example
+ * **Example** (Taking from the start)
+ *
  * ```ts
  * import { Iterable } from "effect"
  *
@@ -673,7 +713,8 @@ export declare const take: {
      *
      * **Note**. `n` is normalized to a non negative integer.
      *
-     * @example
+     * **Example** (Taking from the start)
+     *
      * ```ts
      * import { Iterable } from "effect"
      *
@@ -704,7 +745,8 @@ export declare const take: {
      *
      * **Note**. `n` is normalized to a non negative integer.
      *
-     * @example
+     * **Example** (Taking from the start)
+     *
      * ```ts
      * import { Iterable } from "effect"
      *
@@ -734,7 +776,8 @@ export declare const take: {
 /**
  * Calculate the longest initial Iterable for which all element satisfy the specified predicate, creating a new `Iterable`.
  *
- * @example
+ * **Example** (Taking while a predicate holds)
+ *
  * ```ts
  * import { Iterable } from "effect"
  *
@@ -768,7 +811,8 @@ export declare const takeWhile: {
     /**
      * Calculate the longest initial Iterable for which all element satisfy the specified predicate, creating a new `Iterable`.
      *
-     * @example
+     * **Example** (Taking while a predicate holds)
+     *
      * ```ts
      * import { Iterable } from "effect"
      *
@@ -802,7 +846,8 @@ export declare const takeWhile: {
     /**
      * Calculate the longest initial Iterable for which all element satisfy the specified predicate, creating a new `Iterable`.
      *
-     * @example
+     * **Example** (Taking while a predicate holds)
+     *
      * ```ts
      * import { Iterable } from "effect"
      *
@@ -836,7 +881,8 @@ export declare const takeWhile: {
     /**
      * Calculate the longest initial Iterable for which all element satisfy the specified predicate, creating a new `Iterable`.
      *
-     * @example
+     * **Example** (Taking while a predicate holds)
+     *
      * ```ts
      * import { Iterable } from "effect"
      *
@@ -870,7 +916,8 @@ export declare const takeWhile: {
     /**
      * Calculate the longest initial Iterable for which all element satisfy the specified predicate, creating a new `Iterable`.
      *
-     * @example
+     * **Example** (Taking while a predicate holds)
+     *
      * ```ts
      * import { Iterable } from "effect"
      *
@@ -907,7 +954,8 @@ export declare const takeWhile: {
  *
  * **Note**. `n` is normalized to a non negative integer.
  *
- * @example
+ * **Example** (Dropping from the start)
+ *
  * ```ts
  * import { Iterable } from "effect"
  *
@@ -937,7 +985,8 @@ export declare const drop: {
      *
      * **Note**. `n` is normalized to a non negative integer.
      *
-     * @example
+     * **Example** (Dropping from the start)
+     *
      * ```ts
      * import { Iterable } from "effect"
      *
@@ -967,7 +1016,8 @@ export declare const drop: {
      *
      * **Note**. `n` is normalized to a non negative integer.
      *
-     * @example
+     * **Example** (Dropping from the start)
+     *
      * ```ts
      * import { Iterable } from "effect"
      *
@@ -997,10 +1047,10 @@ export declare const drop: {
  * Returns the first element that satisfies the specified
  * predicate, or `None` if no such element exists.
  *
- * @example
+ * **Example** (Finding the first match)
+ *
  * ```ts
- * import { Iterable } from "effect"
- * import * as Option from "effect/Option"
+ * import { Iterable, Option } from "effect"
  *
  * const numbers = [1, 3, 4, 6, 8]
  * const firstEven = Iterable.findFirst(numbers, (x) => x % 2 === 0)
@@ -1038,10 +1088,10 @@ export declare const findFirst: {
      * Returns the first element that satisfies the specified
      * predicate, or `None` if no such element exists.
      *
-     * @example
+     * **Example** (Finding the first match)
+     *
      * ```ts
-     * import { Iterable } from "effect"
-     * import * as Option from "effect/Option"
+     * import { Iterable, Option } from "effect"
      *
      * const numbers = [1, 3, 4, 6, 8]
      * const firstEven = Iterable.findFirst(numbers, (x) => x % 2 === 0)
@@ -1079,10 +1129,10 @@ export declare const findFirst: {
      * Returns the first element that satisfies the specified
      * predicate, or `None` if no such element exists.
      *
-     * @example
+     * **Example** (Finding the first match)
+     *
      * ```ts
-     * import { Iterable } from "effect"
-     * import * as Option from "effect/Option"
+     * import { Iterable, Option } from "effect"
      *
      * const numbers = [1, 3, 4, 6, 8]
      * const firstEven = Iterable.findFirst(numbers, (x) => x % 2 === 0)
@@ -1120,10 +1170,10 @@ export declare const findFirst: {
      * Returns the first element that satisfies the specified
      * predicate, or `None` if no such element exists.
      *
-     * @example
+     * **Example** (Finding the first match)
+     *
      * ```ts
-     * import { Iterable } from "effect"
-     * import * as Option from "effect/Option"
+     * import { Iterable, Option } from "effect"
      *
      * const numbers = [1, 3, 4, 6, 8]
      * const firstEven = Iterable.findFirst(numbers, (x) => x % 2 === 0)
@@ -1161,10 +1211,10 @@ export declare const findFirst: {
      * Returns the first element that satisfies the specified
      * predicate, or `None` if no such element exists.
      *
-     * @example
+     * **Example** (Finding the first match)
+     *
      * ```ts
-     * import { Iterable } from "effect"
-     * import * as Option from "effect/Option"
+     * import { Iterable, Option } from "effect"
      *
      * const numbers = [1, 3, 4, 6, 8]
      * const firstEven = Iterable.findFirst(numbers, (x) => x % 2 === 0)
@@ -1202,10 +1252,10 @@ export declare const findFirst: {
      * Returns the first element that satisfies the specified
      * predicate, or `None` if no such element exists.
      *
-     * @example
+     * **Example** (Finding the first match)
+     *
      * ```ts
-     * import { Iterable } from "effect"
-     * import * as Option from "effect/Option"
+     * import { Iterable, Option } from "effect"
      *
      * const numbers = [1, 3, 4, 6, 8]
      * const firstEven = Iterable.findFirst(numbers, (x) => x % 2 === 0)
@@ -1243,10 +1293,10 @@ export declare const findFirst: {
      * Returns the first element that satisfies the specified
      * predicate, or `None` if no such element exists.
      *
-     * @example
+     * **Example** (Finding the first match)
+     *
      * ```ts
-     * import { Iterable } from "effect"
-     * import * as Option from "effect/Option"
+     * import { Iterable, Option } from "effect"
      *
      * const numbers = [1, 3, 4, 6, 8]
      * const firstEven = Iterable.findFirst(numbers, (x) => x % 2 === 0)
@@ -1284,7 +1334,8 @@ export declare const findFirst: {
 /**
  * Find the last element for which a predicate holds.
  *
- * @example
+ * **Example** (Finding the last match)
+ *
  * ```ts
  * import { Iterable } from "effect"
  *
@@ -1316,7 +1367,8 @@ export declare const findLast: {
     /**
      * Find the last element for which a predicate holds.
      *
-     * @example
+     * **Example** (Finding the last match)
+     *
      * ```ts
      * import { Iterable } from "effect"
      *
@@ -1348,7 +1400,8 @@ export declare const findLast: {
     /**
      * Find the last element for which a predicate holds.
      *
-     * @example
+     * **Example** (Finding the last match)
+     *
      * ```ts
      * import { Iterable } from "effect"
      *
@@ -1380,7 +1433,8 @@ export declare const findLast: {
     /**
      * Find the last element for which a predicate holds.
      *
-     * @example
+     * **Example** (Finding the last match)
+     *
      * ```ts
      * import { Iterable } from "effect"
      *
@@ -1412,7 +1466,8 @@ export declare const findLast: {
     /**
      * Find the last element for which a predicate holds.
      *
-     * @example
+     * **Example** (Finding the last match)
+     *
      * ```ts
      * import { Iterable } from "effect"
      *
@@ -1444,7 +1499,8 @@ export declare const findLast: {
     /**
      * Find the last element for which a predicate holds.
      *
-     * @example
+     * **Example** (Finding the last match)
+     *
      * ```ts
      * import { Iterable } from "effect"
      *
@@ -1476,7 +1532,8 @@ export declare const findLast: {
     /**
      * Find the last element for which a predicate holds.
      *
-     * @example
+     * **Example** (Finding the last match)
+     *
      * ```ts
      * import { Iterable } from "effect"
      *
@@ -1509,7 +1566,8 @@ export declare const findLast: {
 /**
  * Takes two `Iterable`s and returns an `Iterable` of corresponding pairs.
  *
- * @example
+ * **Example** (Zipping iterables)
+ *
  * ```ts
  * import { Iterable } from "effect"
  *
@@ -1544,7 +1602,8 @@ export declare const zip: {
     /**
      * Takes two `Iterable`s and returns an `Iterable` of corresponding pairs.
      *
-     * @example
+     * **Example** (Zipping iterables)
+     *
      * ```ts
      * import { Iterable } from "effect"
      *
@@ -1579,7 +1638,8 @@ export declare const zip: {
     /**
      * Takes two `Iterable`s and returns an `Iterable` of corresponding pairs.
      *
-     * @example
+     * **Example** (Zipping iterables)
+     *
      * ```ts
      * import { Iterable } from "effect"
      *
@@ -1616,7 +1676,8 @@ export declare const zip: {
  * Apply a function to pairs of elements at the same index in two `Iterable`s, collecting the results. If one
  * input `Iterable` is short, excess elements of the longer `Iterable` are discarded.
  *
- * @example
+ * **Example** (Zipping with a combining function)
+ *
  * ```ts
  * import { Iterable } from "effect"
  *
@@ -1663,7 +1724,8 @@ export declare const zipWith: {
      * Apply a function to pairs of elements at the same index in two `Iterable`s, collecting the results. If one
      * input `Iterable` is short, excess elements of the longer `Iterable` are discarded.
      *
-     * @example
+     * **Example** (Zipping with a combining function)
+     *
      * ```ts
      * import { Iterable } from "effect"
      *
@@ -1710,7 +1772,8 @@ export declare const zipWith: {
      * Apply a function to pairs of elements at the same index in two `Iterable`s, collecting the results. If one
      * input `Iterable` is short, excess elements of the longer `Iterable` are discarded.
      *
-     * @example
+     * **Example** (Zipping with a combining function)
+     *
      * ```ts
      * import { Iterable } from "effect"
      *
@@ -1758,7 +1821,8 @@ export declare const zipWith: {
  * Places an element in between members of an `Iterable`.
  * If the input is a non-empty array, the result is also a non-empty array.
  *
- * @example
+ * **Example** (Interspersing separators)
+ *
  * ```ts
  * import { Iterable } from "effect"
  *
@@ -1796,7 +1860,8 @@ export declare const intersperse: {
      * Places an element in between members of an `Iterable`.
      * If the input is a non-empty array, the result is also a non-empty array.
      *
-     * @example
+     * **Example** (Interspersing separators)
+     *
      * ```ts
      * import { Iterable } from "effect"
      *
@@ -1834,7 +1899,8 @@ export declare const intersperse: {
      * Places an element in between members of an `Iterable`.
      * If the input is a non-empty array, the result is also a non-empty array.
      *
-     * @example
+     * **Example** (Interspersing separators)
+     *
      * ```ts
      * import { Iterable } from "effect"
      *
@@ -1872,7 +1938,8 @@ export declare const intersperse: {
 /**
  * Returns a function that checks if an `Iterable` contains a given value using a provided `isEquivalent` function.
  *
- * @example
+ * **Example** (Checking membership with custom equivalence)
+ *
  * ```ts
  * import { Iterable } from "effect"
  *
@@ -1910,9 +1977,14 @@ export declare const containsWith: <A>(isEquivalent: (self: A, that: A) => boole
     (self: Iterable<A>, a: A): boolean;
 };
 /**
- * Returns a function that checks if a `Iterable` contains a given value using the default `Equivalence`.
+ * Checks whether an iterable contains a value using Effect's default `Equal`
+ * equivalence.
+ *
+ * Can be called as `contains(self, value)` or curried as
+ * `contains(value)(self)`.
+ *
+ * **Example** (Checking membership)
  *
- * @example
  * ```ts
  * import { Iterable } from "effect"
  *
@@ -1940,9 +2012,14 @@ export declare const containsWith: <A>(isEquivalent: (self: A, that: A) => boole
  */
 export declare const contains: {
     /**
-     * Returns a function that checks if a `Iterable` contains a given value using the default `Equivalence`.
+     * Checks whether an iterable contains a value using Effect's default `Equal`
+     * equivalence.
+     *
+     * Can be called as `contains(self, value)` or curried as
+     * `contains(value)(self)`.
+     *
+     * **Example** (Checking membership)
      *
-     * @example
      * ```ts
      * import { Iterable } from "effect"
      *
@@ -1970,9 +2047,14 @@ export declare const contains: {
      */
     <A>(a: A): (self: Iterable<A>) => boolean;
     /**
-     * Returns a function that checks if a `Iterable` contains a given value using the default `Equivalence`.
+     * Checks whether an iterable contains a value using Effect's default `Equal`
+     * equivalence.
+     *
+     * Can be called as `contains(self, value)` or curried as
+     * `contains(value)(self)`.
+     *
+     * **Example** (Checking membership)
      *
-     * @example
      * ```ts
      * import { Iterable } from "effect"
      *
@@ -2004,7 +2086,8 @@ export declare const contains: {
  * Splits an `Iterable` into length-`n` pieces. The last piece will be shorter if `n` does not evenly divide the length of
  * the `Iterable`.
  *
- * @example
+ * **Example** (Chunking an iterable)
+ *
  * ```ts
  * import { Iterable } from "effect"
  *
@@ -2043,7 +2126,8 @@ export declare const chunksOf: {
      * Splits an `Iterable` into length-`n` pieces. The last piece will be shorter if `n` does not evenly divide the length of
      * the `Iterable`.
      *
-     * @example
+     * **Example** (Chunking an iterable)
+     *
      * ```ts
      * import { Iterable } from "effect"
      *
@@ -2082,7 +2166,8 @@ export declare const chunksOf: {
      * Splits an `Iterable` into length-`n` pieces. The last piece will be shorter if `n` does not evenly divide the length of
      * the `Iterable`.
      *
-     * @example
+     * **Example** (Chunking an iterable)
+     *
      * ```ts
      * import { Iterable } from "effect"
      *
@@ -2121,7 +2206,8 @@ export declare const chunksOf: {
 /**
  * Group equal, consecutive elements of an `Iterable` into `NonEmptyArray`s using the provided `isEquivalent` function.
  *
- * @example
+ * **Example** (Grouping consecutive elements with custom equivalence)
+ *
  * ```ts
  * import { Iterable } from "effect"
  *
@@ -2160,7 +2246,8 @@ export declare const groupWith: {
     /**
      * Group equal, consecutive elements of an `Iterable` into `NonEmptyArray`s using the provided `isEquivalent` function.
      *
-     * @example
+     * **Example** (Grouping consecutive elements with custom equivalence)
+     *
      * ```ts
      * import { Iterable } from "effect"
      *
@@ -2199,7 +2286,8 @@ export declare const groupWith: {
     /**
      * Group equal, consecutive elements of an `Iterable` into `NonEmptyArray`s using the provided `isEquivalent` function.
      *
-     * @example
+     * **Example** (Grouping consecutive elements with custom equivalence)
+     *
      * ```ts
      * import { Iterable } from "effect"
      *
@@ -2239,7 +2327,8 @@ export declare const groupWith: {
 /**
  * Group equal, consecutive elements of an `Iterable` into `NonEmptyArray`s.
  *
- * @example
+ * **Example** (Grouping consecutive elements)
+ *
  * ```ts
  * import { Iterable } from "effect"
  *
@@ -2270,10 +2359,14 @@ export declare const groupWith: {
  */
 export declare const group: <A>(self: Iterable<A>) => Iterable<NonEmptyArray<A>>;
 /**
- * Splits an `Iterable` into sub-non-empty-arrays stored in an object, based on the result of calling a `string`-returning
- * function on each element, and grouping the results according to values returned
+ * Groups all elements by the string or symbol key returned by `f`.
+ *
+ * Each property in the returned record contains a non-empty array of elements
+ * that produced that key. Unlike `group`, matching elements do not need to be
+ * consecutive.
+ *
+ * **Example** (Grouping by a key)
  *
- * @example
  * ```ts
  * import { Iterable } from "effect"
  *
@@ -2315,10 +2408,14 @@ export declare const group: <A>(self: Iterable<A>) => Iterable<NonEmptyArray<A>>
  */
 export declare const groupBy: {
     /**
-     * Splits an `Iterable` into sub-non-empty-arrays stored in an object, based on the result of calling a `string`-returning
-     * function on each element, and grouping the results according to values returned
+     * Groups all elements by the string or symbol key returned by `f`.
+     *
+     * Each property in the returned record contains a non-empty array of elements
+     * that produced that key. Unlike `group`, matching elements do not need to be
+     * consecutive.
+     *
+     * **Example** (Grouping by a key)
      *
-     * @example
      * ```ts
      * import { Iterable } from "effect"
      *
@@ -2360,10 +2457,14 @@ export declare const groupBy: {
      */
     <A, K extends string | symbol>(f: (a: A) => K): (self: Iterable<A>) => Record<Record.ReadonlyRecord.NonLiteralKey<K>, NonEmptyArray<A>>;
     /**
-     * Splits an `Iterable` into sub-non-empty-arrays stored in an object, based on the result of calling a `string`-returning
-     * function on each element, and grouping the results according to values returned
+     * Groups all elements by the string or symbol key returned by `f`.
+     *
+     * Each property in the returned record contains a non-empty array of elements
+     * that produced that key. Unlike `group`, matching elements do not need to be
+     * consecutive.
+     *
+     * **Example** (Grouping by a key)
      *
-     * @example
      * ```ts
      * import { Iterable } from "effect"
      *
@@ -2411,7 +2512,8 @@ export declare const groupBy: {
  * This function returns a reusable empty iterable that can be used as a base case
  * for operations or when you need to represent "no data" in a type-safe way.
  *
- * @example
+ * **Example** (Creating an empty iterable)
+ *
  * ```ts
  * import { Iterable } from "effect"
  *
@@ -2436,9 +2538,8 @@ export declare const empty: <A = never>() => Iterable<A>;
  * This is useful for wrapping a single value in an iterable context,
  * allowing it to be used with other iterable operations.
  *
- * @param a - The single element to wrap in an iterable
+ * **Example** (Wrapping a single value)
  *
- * @example
  * ```ts
  * import { Iterable } from "effect"
  *
@@ -2473,10 +2574,8 @@ export declare const of: <A>(a: A) => Iterable<A>;
  * with the transformed values. The operation is lazy - elements are only
  * transformed when the iterable is consumed.
  *
- * @param self - The source iterable to transform
- * @param f - Function that transforms each element (receives value and index)
+ * **Example** (Mapping elements)
  *
- * @example
  * ```ts
  * import { Iterable } from "effect"
  *
@@ -2509,10 +2608,8 @@ export declare const map: {
      * with the transformed values. The operation is lazy - elements are only
      * transformed when the iterable is consumed.
      *
-     * @param self - The source iterable to transform
-     * @param f - Function that transforms each element (receives value and index)
+     * **Example** (Mapping elements)
      *
-     * @example
      * ```ts
      * import { Iterable } from "effect"
      *
@@ -2545,10 +2642,8 @@ export declare const map: {
      * with the transformed values. The operation is lazy - elements are only
      * transformed when the iterable is consumed.
      *
-     * @param self - The source iterable to transform
-     * @param f - Function that transforms each element (receives value and index)
+     * **Example** (Mapping elements)
      *
-     * @example
      * ```ts
      * import { Iterable } from "effect"
      *
@@ -2577,7 +2672,8 @@ export declare const map: {
 /**
  * Applies a function to each element in an Iterable and returns a new Iterable containing the concatenated mapped elements.
  *
- * @example
+ * **Example** (FlatMapping iterables)
+ *
  * ```ts
  * import { Iterable } from "effect"
  *
@@ -2615,7 +2711,8 @@ export declare const flatMap: {
     /**
      * Applies a function to each element in an Iterable and returns a new Iterable containing the concatenated mapped elements.
      *
-     * @example
+     * **Example** (FlatMapping iterables)
+     *
      * ```ts
      * import { Iterable } from "effect"
      *
@@ -2653,7 +2750,8 @@ export declare const flatMap: {
     /**
      * Applies a function to each element in an Iterable and returns a new Iterable containing the concatenated mapped elements.
      *
-     * @example
+     * **Example** (FlatMapping iterables)
+     *
      * ```ts
      * import { Iterable } from "effect"
      *
@@ -2692,7 +2790,8 @@ export declare const flatMap: {
 /**
  * Flattens an Iterable of Iterables into a single Iterable
  *
- * @example
+ * **Example** (Flattening nested iterables)
+ *
  * ```ts
  * import { Iterable } from "effect"
  *
@@ -2728,10 +2827,10 @@ export declare const flatten: <A>(self: Iterable<Iterable<A>>) => Iterable<A>;
  * This combines mapping and filtering in a single operation - the function is applied to each element,
  * and only elements that result in `Result.succeed` are included in the result.
  *
- * @example
+ * **Example** (Filtering and transforming Result values)
+ *
  * ```ts
- * import { Iterable } from "effect"
- * import * as Result from "effect/Result"
+ * import { Iterable, Result } from "effect"
  *
  * // Parse strings to numbers, keeping only valid ones
  * const strings = ["1", "2", "invalid", "4", "not-a-number"]
@@ -2774,10 +2873,10 @@ export declare const filterMap: {
      * This combines mapping and filtering in a single operation - the function is applied to each element,
      * and only elements that result in `Result.succeed` are included in the result.
      *
-     * @example
+     * **Example** (Filtering and transforming Result values)
+     *
      * ```ts
-     * import { Iterable } from "effect"
-     * import * as Result from "effect/Result"
+     * import { Iterable, Result } from "effect"
      *
      * // Parse strings to numbers, keeping only valid ones
      * const strings = ["1", "2", "invalid", "4", "not-a-number"]
@@ -2820,10 +2919,10 @@ export declare const filterMap: {
      * This combines mapping and filtering in a single operation - the function is applied to each element,
      * and only elements that result in `Result.succeed` are included in the result.
      *
-     * @example
+     * **Example** (Filtering and transforming Result values)
+     *
      * ```ts
-     * import { Iterable } from "effect"
-     * import * as Result from "effect/Result"
+     * import { Iterable, Result } from "effect"
      *
      * // Parse strings to numbers, keeping only valid ones
      * const strings = ["1", "2", "invalid", "4", "not-a-number"]
@@ -2864,10 +2963,10 @@ export declare const filterMap: {
 /**
  * Transforms all elements of the `Iterable` for as long as the specified function succeeds.
  *
- * @example
+ * **Example** (Filtering and transforming until failure)
+ *
  * ```ts
- * import { Iterable } from "effect"
- * import * as Result from "effect/Result"
+ * import { Iterable, Result } from "effect"
  *
  * // Parse numbers until we hit an invalid one
  * const strings = ["1", "2", "3", "invalid", "4", "5"]
@@ -2901,10 +3000,10 @@ export declare const filterMapWhile: {
     /**
      * Transforms all elements of the `Iterable` for as long as the specified function succeeds.
      *
-     * @example
+     * **Example** (Filtering and transforming until failure)
+     *
      * ```ts
-     * import { Iterable } from "effect"
-     * import * as Result from "effect/Result"
+     * import { Iterable, Result } from "effect"
      *
      * // Parse numbers until we hit an invalid one
      * const strings = ["1", "2", "3", "invalid", "4", "5"]
@@ -2938,10 +3037,10 @@ export declare const filterMapWhile: {
     /**
      * Transforms all elements of the `Iterable` for as long as the specified function succeeds.
      *
-     * @example
+     * **Example** (Filtering and transforming until failure)
+     *
      * ```ts
-     * import { Iterable } from "effect"
-     * import * as Result from "effect/Result"
+     * import { Iterable, Result } from "effect"
      *
      * // Parse numbers until we hit an invalid one
      * const strings = ["1", "2", "3", "invalid", "4", "5"]
@@ -2976,10 +3075,10 @@ export declare const filterMapWhile: {
 /**
  * Retrieves the `Some` values from an `Iterable` of `Option`s.
  *
- * @example
+ * **Example** (Extracting Some values)
+ *
  * ```ts
- * import { Iterable } from "effect"
- * import * as Option from "effect/Option"
+ * import { Iterable, Option } from "effect"
  * import * as assert from "node:assert"
  *
  * assert.deepStrictEqual(
@@ -2995,12 +3094,13 @@ export declare const filterMapWhile: {
  */
 export declare const getSomes: <A>(self: Iterable<Option<A>>) => Iterable<A>;
 /**
- * Retrieves the `Err` values from an `Iterable` of `Result`s.
+ * Returns a lazy iterable containing the failure values from an iterable of
+ * `Result`s, skipping successful results.
+ *
+ * **Example** (Extracting failures)
  *
- * @example
  * ```ts
- * import { Iterable } from "effect"
- * import * as Result from "effect/Result"
+ * import { Iterable, Result } from "effect"
  * import * as assert from "node:assert"
  *
  * assert.deepStrictEqual(
@@ -3016,16 +3116,17 @@ export declare const getSomes: <A>(self: Iterable<Option<A>>) => Iterable<A>;
  * ```
  *
  * @category filtering
- * @since 2.0.0
+ * @since 4.0.0
  */
 export declare const getFailures: <R0, L>(self: Iterable<Result<R0, L>>) => Iterable<L>;
 /**
- * Retrieves the `Ok` values from an `Iterable` of `Result`s.
+ * Returns a lazy iterable containing the success values from an iterable of
+ * `Result`s, skipping failed results.
+ *
+ * **Example** (Extracting successes)
  *
- * @example
  * ```ts
- * import { Iterable } from "effect"
- * import * as Result from "effect/Result"
+ * import { Iterable, Result } from "effect"
  * import * as assert from "node:assert"
  *
  * assert.deepStrictEqual(
@@ -3041,7 +3142,7 @@ export declare const getFailures: <R0, L>(self: Iterable<Result<R0, L>>) => Iter
  * ```
  *
  * @category filtering
- * @since 2.0.0
+ * @since 4.0.0
  */
 export declare const getSuccesses: <R0, L>(self: Iterable<Result<R0, L>>) => Iterable<R0>;
 /**
@@ -3051,10 +3152,8 @@ export declare const getSuccesses: <R0, L>(self: Iterable<Result<R0, L>>) => Ite
  * the predicate function returns true. Like map, this operation is lazy and
  * elements are only tested when the iterable is consumed.
  *
- * @param self - The source iterable to filter
- * @param predicate - Function that tests each element (receives value and index)
+ * **Example** (Filtering elements)
  *
- * @example
  * ```ts
  * import { Iterable } from "effect"
  *
@@ -3095,10 +3194,8 @@ export declare const filter: {
      * the predicate function returns true. Like map, this operation is lazy and
      * elements are only tested when the iterable is consumed.
      *
-     * @param self - The source iterable to filter
-     * @param predicate - Function that tests each element (receives value and index)
+     * **Example** (Filtering elements)
      *
-     * @example
      * ```ts
      * import { Iterable } from "effect"
      *
@@ -3139,10 +3236,8 @@ export declare const filter: {
      * the predicate function returns true. Like map, this operation is lazy and
      * elements are only tested when the iterable is consumed.
      *
-     * @param self - The source iterable to filter
-     * @param predicate - Function that tests each element (receives value and index)
+     * **Example** (Filtering elements)
      *
-     * @example
      * ```ts
      * import { Iterable } from "effect"
      *
@@ -3183,10 +3278,8 @@ export declare const filter: {
      * the predicate function returns true. Like map, this operation is lazy and
      * elements are only tested when the iterable is consumed.
      *
-     * @param self - The source iterable to filter
-     * @param predicate - Function that tests each element (receives value and index)
+     * **Example** (Filtering elements)
      *
-     * @example
      * ```ts
      * import { Iterable } from "effect"
      *
@@ -3227,10 +3320,8 @@ export declare const filter: {
      * the predicate function returns true. Like map, this operation is lazy and
      * elements are only tested when the iterable is consumed.
      *
-     * @param self - The source iterable to filter
-     * @param predicate - Function that tests each element (receives value and index)
+     * **Example** (Filtering elements)
      *
-     * @example
      * ```ts
      * import { Iterable } from "effect"
      *
@@ -3271,7 +3362,8 @@ export declare const filter: {
  * This is useful when working with APIs or functions that return nullable values,
  * providing a clean way to filter out null/undefined while transforming.
  *
- * @example
+ * **Example** (FlatMapping nullable results)
+ *
  * ```ts
  * import { Iterable } from "effect"
  *
@@ -3305,7 +3397,7 @@ export declare const filter: {
  * ```
  *
  * @category sequencing
- * @since 2.0.0
+ * @since 4.0.0
  */
 export declare const flatMapNullishOr: {
     /**
@@ -3314,7 +3406,8 @@ export declare const flatMapNullishOr: {
      * This is useful when working with APIs or functions that return nullable values,
      * providing a clean way to filter out null/undefined while transforming.
      *
-     * @example
+     * **Example** (FlatMapping nullable results)
+     *
      * ```ts
      * import { Iterable } from "effect"
      *
@@ -3348,7 +3441,7 @@ export declare const flatMapNullishOr: {
      * ```
      *
      * @category sequencing
-     * @since 2.0.0
+     * @since 4.0.0
      */
     <A, B>(f: (a: A) => B): (self: Iterable<A>) => Iterable<NonNullable<B>>;
     /**
@@ -3357,7 +3450,8 @@ export declare const flatMapNullishOr: {
      * This is useful when working with APIs or functions that return nullable values,
      * providing a clean way to filter out null/undefined while transforming.
      *
-     * @example
+     * **Example** (FlatMapping nullable results)
+     *
      * ```ts
      * import { Iterable } from "effect"
      *
@@ -3391,14 +3485,15 @@ export declare const flatMapNullishOr: {
      * ```
      *
      * @category sequencing
-     * @since 2.0.0
+     * @since 4.0.0
      */
     <A, B>(self: Iterable<A>, f: (a: A) => B): Iterable<NonNullable<B>>;
 };
 /**
  * Check if a predicate holds true for some `Iterable` element.
  *
- * @example
+ * **Example** (Checking whether some element matches)
+ *
  * ```ts
  * import { Iterable } from "effect"
  *
@@ -3439,7 +3534,8 @@ export declare const some: {
     /**
      * Check if a predicate holds true for some `Iterable` element.
      *
-     * @example
+     * **Example** (Checking whether some element matches)
+     *
      * ```ts
      * import { Iterable } from "effect"
      *
@@ -3480,7 +3576,8 @@ export declare const some: {
     /**
      * Check if a predicate holds true for some `Iterable` element.
      *
-     * @example
+     * **Example** (Checking whether some element matches)
+     *
      * ```ts
      * import { Iterable } from "effect"
      *
@@ -3527,7 +3624,8 @@ export declare const some: {
  * maintains state. The function should return `Option.some([value, nextState])`
  * to continue or `Option.none()` to stop.
  *
- * @example
+ * **Example** (Unfolding state into values)
+ *
  * ```ts
  * import { Iterable, Option } from "effect"
  *
@@ -3560,7 +3658,8 @@ export declare const unfold: <B, A>(b: B, f: (b: B) => Option<readonly [A, B]>)
 /**
  * Iterate over the `Iterable` applying `f`.
  *
- * @example
+ * **Example** (Iterating with side effects)
+ *
  * ```ts
  * import { Iterable } from "effect"
  *
@@ -3598,7 +3697,8 @@ export declare const forEach: {
     /**
      * Iterate over the `Iterable` applying `f`.
      *
-     * @example
+     * **Example** (Iterating with side effects)
+     *
      * ```ts
      * import { Iterable } from "effect"
      *
@@ -3636,7 +3736,8 @@ export declare const forEach: {
     /**
      * Iterate over the `Iterable` applying `f`.
      *
-     * @example
+     * **Example** (Iterating with side effects)
+     *
      * ```ts
      * import { Iterable } from "effect"
      *
@@ -3678,7 +3779,8 @@ export declare const forEach: {
  * This function applies a reducing function against an accumulator and each element
  * of the iterable (from left to right) to reduce it to a single value.
  *
- * @example
+ * **Example** (Reducing an iterable)
+ *
  * ```ts
  * import { Iterable } from "effect"
  *
@@ -3727,7 +3829,8 @@ export declare const reduce: {
      * This function applies a reducing function against an accumulator and each element
      * of the iterable (from left to right) to reduce it to a single value.
      *
-     * @example
+     * **Example** (Reducing an iterable)
+     *
      * ```ts
      * import { Iterable } from "effect"
      *
@@ -3776,7 +3879,8 @@ export declare const reduce: {
      * This function applies a reducing function against an accumulator and each element
      * of the iterable (from left to right) to reduce it to a single value.
      *
-     * @example
+     * **Example** (Reducing an iterable)
+     *
      * ```ts
      * import { Iterable } from "effect"
      *
@@ -3823,7 +3927,8 @@ export declare const reduce: {
 /**
  * Deduplicates adjacent elements that are identical using the provided `isEquivalent` function.
  *
- * @example
+ * **Example** (Deduplicating adjacent elements with custom equivalence)
+ *
  * ```ts
  * import { Iterable } from "effect"
  *
@@ -3865,7 +3970,8 @@ export declare const dedupeAdjacentWith: {
     /**
      * Deduplicates adjacent elements that are identical using the provided `isEquivalent` function.
      *
-     * @example
+     * **Example** (Deduplicating adjacent elements with custom equivalence)
+     *
      * ```ts
      * import { Iterable } from "effect"
      *
@@ -3907,7 +4013,8 @@ export declare const dedupeAdjacentWith: {
     /**
      * Deduplicates adjacent elements that are identical using the provided `isEquivalent` function.
      *
-     * @example
+     * **Example** (Deduplicating adjacent elements with custom equivalence)
+     *
      * ```ts
      * import { Iterable } from "effect"
      *
@@ -3950,7 +4057,8 @@ export declare const dedupeAdjacentWith: {
 /**
  * Deduplicates adjacent elements that are identical.
  *
- * @example
+ * **Example** (Deduplicating adjacent elements)
+ *
  * ```ts
  * import { Iterable } from "effect"
  *
@@ -3988,7 +4096,8 @@ export declare const dedupeAdjacent: <A>(self: Iterable<A>) => Iterable<A>;
 /**
  * Zips this Iterable crosswise with the specified Iterable using the specified combiner.
  *
- * @example
+ * **Example** (Combining cartesian products)
+ *
  * ```ts
  * import { Iterable } from "effect"
  *
@@ -4031,14 +4140,15 @@ export declare const dedupeAdjacent: <A>(self: Iterable<A>) => Iterable<A>;
  * // ["admin_can_read", "admin_can_write", "admin_can_delete", "user_can_read", "user_can_write", "user_can_delete"]
  * ```
  *
- * @since 2.0.0
  * @category elements
+ * @since 2.0.0
  */
 export declare const cartesianWith: {
     /**
      * Zips this Iterable crosswise with the specified Iterable using the specified combiner.
      *
-     * @example
+     * **Example** (Combining cartesian products)
+     *
      * ```ts
      * import { Iterable } from "effect"
      *
@@ -4081,14 +4191,15 @@ export declare const cartesianWith: {
      * // ["admin_can_read", "admin_can_write", "admin_can_delete", "user_can_read", "user_can_write", "user_can_delete"]
      * ```
      *
-     * @since 2.0.0
      * @category elements
+     * @since 2.0.0
      */
     <A, B, C>(that: Iterable<B>, f: (a: A, b: B) => C): (self: Iterable<A>) => Iterable<C>;
     /**
      * Zips this Iterable crosswise with the specified Iterable using the specified combiner.
      *
-     * @example
+     * **Example** (Combining cartesian products)
+     *
      * ```ts
      * import { Iterable } from "effect"
      *
@@ -4131,15 +4242,16 @@ export declare const cartesianWith: {
      * // ["admin_can_read", "admin_can_write", "admin_can_delete", "user_can_read", "user_can_write", "user_can_delete"]
      * ```
      *
-     * @since 2.0.0
      * @category elements
+     * @since 2.0.0
      */
     <A, B, C>(self: Iterable<A>, that: Iterable<B>, f: (a: A, b: B) => C): Iterable<C>;
 };
 /**
  * Zips this Iterable crosswise with the specified Iterable.
  *
- * @example
+ * **Example** (Generating cartesian pairs)
+ *
  * ```ts
  * import { Iterable } from "effect"
  *
@@ -4173,14 +4285,15 @@ export declare const cartesianWith: {
  * console.log(Array.from(withEmpty)) // []
  * ```
  *
- * @since 2.0.0
  * @category elements
+ * @since 2.0.0
  */
 export declare const cartesian: {
     /**
      * Zips this Iterable crosswise with the specified Iterable.
      *
-     * @example
+     * **Example** (Generating cartesian pairs)
+     *
      * ```ts
      * import { Iterable } from "effect"
      *
@@ -4214,14 +4327,15 @@ export declare const cartesian: {
      * console.log(Array.from(withEmpty)) // []
      * ```
      *
-     * @since 2.0.0
      * @category elements
+     * @since 2.0.0
      */
     <B>(that: Iterable<B>): <A>(self: Iterable<A>) => Iterable<[A, B]>;
     /**
      * Zips this Iterable crosswise with the specified Iterable.
      *
-     * @example
+     * **Example** (Generating cartesian pairs)
+     *
      * ```ts
      * import { Iterable } from "effect"
      *
@@ -4255,15 +4369,15 @@ export declare const cartesian: {
      * console.log(Array.from(withEmpty)) // []
      * ```
      *
-     * @since 2.0.0
      * @category elements
+     * @since 2.0.0
      */
     <A, B>(self: Iterable<A>, that: Iterable<B>): Iterable<[A, B]>;
 };
 /**
  * Counts all the element of the given iterable that pass the given predicate
  *
- * **Example**
+ * **Example** (Counting matching elements)
  *
  * ```ts
  * import { Iterable } from "effect"
@@ -4279,7 +4393,7 @@ export declare const countBy: {
     /**
      * Counts all the element of the given iterable that pass the given predicate
      *
-     * **Example**
+     * **Example** (Counting matching elements)
      *
      * ```ts
      * import { Iterable } from "effect"
@@ -4295,7 +4409,7 @@ export declare const countBy: {
     /**
      * Counts all the element of the given iterable that pass the given predicate
      *
-     * **Example**
+     * **Example** (Counting matching elements)
      *
      * ```ts
      * import { Iterable } from "effect"