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

package/src/Iterable.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"
  *
@@ -49,10 +50,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"
  *
@@ -93,16 +92,19 @@ export const makeBy = <A>(f: (i: number) => A, options?: {
 }
 
 /**
- * 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
@@ -122,12 +124,13 @@ export 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
@@ -139,12 +142,13 @@ export 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
@@ -156,12 +160,13 @@ export 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
@@ -171,16 +176,31 @@ export const replicate: {
 } = dual(2, <A>(a: A, n: number): Iterable<A> => makeBy(() => a, { length: n }))
 
 /**
+ * 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 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
    */
@@ -188,6 +208,11 @@ export const repeat: {
 } = dual(2, <A>(self: Iterable<A>, n: number): Iterable<A> => flatten(makeBy(() => self, { length: n })))
 
 /**
+ * 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
  */
@@ -196,19 +221,20 @@ export const forever = <A>(self: Iterable<A>): Iterable<A> => repeat(self, Infin
 /**
  * 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 const fromRecord = <K extends string, A>(self: Readonly<Record<K, A>>): Iterable<[K, A]> => ({
@@ -224,7 +250,8 @@ export const fromRecord = <K extends string, A>(self: Readonly<Record<K, A>>): I
 /**
  * Prepend an element to the front of an `Iterable`, creating a new `Iterable`.
  *
- * @example
+ * **Example** (Prepending an element)
+ *
  * ```ts
  * import { Iterable } from "effect"
  *
@@ -245,7 +272,8 @@ export 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"
    *
@@ -266,7 +294,8 @@ export 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"
    *
@@ -289,7 +318,8 @@ export 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"
@@ -307,7 +337,8 @@ export 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"
@@ -325,7 +356,8 @@ export 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"
@@ -348,7 +380,8 @@ export 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"
  *
@@ -371,7 +404,8 @@ export 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"
    *
@@ -394,7 +428,8 @@ export 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"
    *
@@ -419,7 +454,8 @@ export const append: {
 /**
  * Concatenates two iterables, combining their elements.
  *
- * @example
+ * **Example** (Concatenating iterables)
+ *
  * ```ts
  * import { Iterable } from "effect"
  *
@@ -448,7 +484,8 @@ export const appendAll: {
   /**
    * Concatenates two iterables, combining their elements.
    *
-   * @example
+   * **Example** (Concatenating iterables)
+   *
    * ```ts
    * import { Iterable } from "effect"
    *
@@ -477,7 +514,8 @@ export const appendAll: {
   /**
    * Concatenates two iterables, combining their elements.
    *
-   * @example
+   * **Example** (Concatenating iterables)
+   *
    * ```ts
    * import { Iterable } from "effect"
    *
@@ -531,7 +569,8 @@ export 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"
  *
@@ -558,7 +597,8 @@ export 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"
    *
@@ -585,7 +625,8 @@ export 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"
    *
@@ -632,13 +673,14 @@ export 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
@@ -652,7 +694,8 @@ export 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"
  *
@@ -686,10 +729,10 @@ export 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)
@@ -720,7 +763,8 @@ export 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"
  *
@@ -730,13 +774,8 @@ export 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)
@@ -744,7 +783,7 @@ export const head = <A>(self: Iterable<A>): Option<A> => {
  * ```
  *
  * @category getters
- * @since 3.3.0
+ * @since 4.0.0
  */
 export const headUnsafe = <A>(self: Iterable<A>): A => {
   const iterator = self[Symbol.iterator]()
@@ -758,7 +797,8 @@ export 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"
  *
@@ -789,7 +829,8 @@ export const take: {
    *
    * **Note**. `n` is normalized to a non negative integer.
    *
-   * @example
+   * **Example** (Taking from the start)
+   *
    * ```ts
    * import { Iterable } from "effect"
    *
@@ -820,7 +861,8 @@ export const take: {
    *
    * **Note**. `n` is normalized to a non negative integer.
    *
-   * @example
+   * **Example** (Taking from the start)
+   *
    * ```ts
    * import { Iterable } from "effect"
    *
@@ -865,7 +907,8 @@ export 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"
  *
@@ -899,7 +942,8 @@ export 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"
    *
@@ -933,7 +977,8 @@ export 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"
    *
@@ -967,7 +1012,8 @@ export 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"
    *
@@ -1001,7 +1047,8 @@ export 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"
    *
@@ -1053,7 +1100,8 @@ export const takeWhile: {
  *
  * **Note**. `n` is normalized to a non negative integer.
  *
- * @example
+ * **Example** (Dropping from the start)
+ *
  * ```ts
  * import { Iterable } from "effect"
  *
@@ -1083,7 +1131,8 @@ export const drop: {
    *
    * **Note**. `n` is normalized to a non negative integer.
    *
-   * @example
+   * **Example** (Dropping from the start)
+   *
    * ```ts
    * import { Iterable } from "effect"
    *
@@ -1113,7 +1162,8 @@ export const drop: {
    *
    * **Note**. `n` is normalized to a non negative integer.
    *
-   * @example
+   * **Example** (Dropping from the start)
+   *
    * ```ts
    * import { Iterable } from "effect"
    *
@@ -1161,10 +1211,10 @@ export 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)
@@ -1202,10 +1252,10 @@ export 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 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,10 +1334,10 @@ export 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)
@@ -1325,10 +1375,10 @@ export 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)
@@ -1366,10 +1416,10 @@ export 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)
@@ -1407,10 +1457,10 @@ export 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)
@@ -1468,7 +1518,8 @@ export const findFirst: {
 /**
  * Find the last element for which a predicate holds.
  *
- * @example
+ * **Example** (Finding the last match)
+ *
  * ```ts
  * import { Iterable } from "effect"
  *
@@ -1500,7 +1551,8 @@ export const findLast: {
   /**
    * Find the last element for which a predicate holds.
    *
-   * @example
+   * **Example** (Finding the last match)
+   *
    * ```ts
    * import { Iterable } from "effect"
    *
@@ -1532,7 +1584,8 @@ export const findLast: {
   /**
    * Find the last element for which a predicate holds.
    *
-   * @example
+   * **Example** (Finding the last match)
+   *
    * ```ts
    * import { Iterable } from "effect"
    *
@@ -1564,7 +1617,8 @@ export const findLast: {
   /**
    * Find the last element for which a predicate holds.
    *
-   * @example
+   * **Example** (Finding the last match)
+   *
    * ```ts
    * import { Iterable } from "effect"
    *
@@ -1596,7 +1650,8 @@ export const findLast: {
   /**
    * Find the last element for which a predicate holds.
    *
-   * @example
+   * **Example** (Finding the last match)
+   *
    * ```ts
    * import { Iterable } from "effect"
    *
@@ -1628,7 +1683,8 @@ export const findLast: {
   /**
    * Find the last element for which a predicate holds.
    *
-   * @example
+   * **Example** (Finding the last match)
+   *
    * ```ts
    * import { Iterable } from "effect"
    *
@@ -1660,7 +1716,8 @@ export const findLast: {
   /**
    * Find the last element for which a predicate holds.
    *
-   * @example
+   * **Example** (Finding the last match)
+   *
    * ```ts
    * import { Iterable } from "effect"
    *
@@ -1714,7 +1771,8 @@ export const findLast: {
 /**
  * Takes two `Iterable`s and returns an `Iterable` of corresponding pairs.
  *
- * @example
+ * **Example** (Zipping iterables)
+ *
  * ```ts
  * import { Iterable } from "effect"
  *
@@ -1749,7 +1807,8 @@ export const zip: {
   /**
    * Takes two `Iterable`s and returns an `Iterable` of corresponding pairs.
    *
-   * @example
+   * **Example** (Zipping iterables)
+   *
    * ```ts
    * import { Iterable } from "effect"
    *
@@ -1784,7 +1843,8 @@ export const zip: {
   /**
    * Takes two `Iterable`s and returns an `Iterable` of corresponding pairs.
    *
-   * @example
+   * **Example** (Zipping iterables)
+   *
    * ```ts
    * import { Iterable } from "effect"
    *
@@ -1825,7 +1885,8 @@ export 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"
  *
@@ -1872,7 +1933,8 @@ export 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"
    *
@@ -1919,7 +1981,8 @@ export 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"
    *
@@ -1983,7 +2046,8 @@ export 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"
  *
@@ -2021,7 +2085,8 @@ export 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"
    *
@@ -2059,7 +2124,8 @@ export 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"
    *
@@ -2118,7 +2184,8 @@ export 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"
  *
@@ -2165,9 +2232,14 @@ export const containsWith = <A>(isEquivalent: (self: A, that: 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"
  *
@@ -2195,9 +2267,14 @@ export const containsWith = <A>(isEquivalent: (self: A, that: A) => boolean): {
  */
 export 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"
    *
@@ -2225,9 +2302,14 @@ export 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"
    *
@@ -2260,7 +2342,8 @@ export 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"
  *
@@ -2299,7 +2382,8 @@ export 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"
    *
@@ -2338,7 +2422,8 @@ export 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"
    *
@@ -2404,7 +2489,8 @@ export 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"
  *
@@ -2443,7 +2529,8 @@ export 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"
    *
@@ -2482,7 +2569,8 @@ export 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"
    *
@@ -2558,7 +2646,8 @@ export const groupWith: {
 /**
  * Group equal, consecutive elements of an `Iterable` into `NonEmptyArray`s.
  *
- * @example
+ * **Example** (Grouping consecutive elements)
+ *
  * ```ts
  * import { Iterable } from "effect"
  *
@@ -2592,10 +2681,14 @@ export const group: <A>(self: Iterable<A>) => Iterable<NonEmptyArray<A>> = group
 )
 
 /**
- * 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"
  *
@@ -2637,10 +2730,14 @@ export const group: <A>(self: Iterable<A>) => Iterable<NonEmptyArray<A>> = group
  */
 export 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"
    *
@@ -2682,10 +2779,14 @@ export 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"
    *
@@ -2759,7 +2860,8 @@ const constEmptyIterator: Iterator<never> = {
  * 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"
  *
@@ -2785,9 +2887,8 @@ export const empty = <A = never>(): Iterable<A> => constEmpty
  * 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"
  *
@@ -2823,10 +2924,8 @@ export const of = <A>(a: A): Iterable<A> => [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"
  *
@@ -2859,10 +2958,8 @@ export 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"
    *
@@ -2895,10 +2992,8 @@ export 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"
    *
@@ -2942,7 +3037,8 @@ export 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"
  *
@@ -2980,7 +3076,8 @@ export 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"
    *
@@ -3018,7 +3115,8 @@ export 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"
    *
@@ -3061,7 +3159,8 @@ export const flatMap: {
 /**
  * Flattens an Iterable of Iterables into a single Iterable
  *
- * @example
+ * **Example** (Flattening nested iterables)
+ *
  * ```ts
  * import { Iterable } from "effect"
  *
@@ -3119,10 +3218,10 @@ export 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"]
@@ -3165,10 +3264,10 @@ export 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"]
@@ -3211,10 +3310,10 @@ export 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"]
@@ -3277,10 +3376,10 @@ export 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"]
@@ -3314,10 +3413,10 @@ export 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"]
@@ -3351,10 +3450,10 @@ export 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"]
@@ -3408,10 +3507,10 @@ export 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(
@@ -3446,12 +3545,13 @@ export 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(
@@ -3467,7 +3567,7 @@ export const getSomes = <A>(self: Iterable<Option<A>>): Iterable<A> => {
  * ```
  *
  * @category filtering
- * @since 2.0.0
+ * @since 4.0.0
  */
 export const getFailures = <R0, L>(self: Iterable<Result<R0, L>>): Iterable<L> => {
   return {
@@ -3490,12 +3590,13 @@ export 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(
@@ -3511,7 +3612,7 @@ export const getFailures = <R0, L>(self: Iterable<Result<R0, L>>): Iterable<L> =
  * ```
  *
  * @category filtering
- * @since 2.0.0
+ * @since 4.0.0
  */
 export const getSuccesses = <R0, L>(self: Iterable<Result<R0, L>>): Iterable<R0> => {
   return {
@@ -3540,10 +3641,8 @@ export const getSuccesses = <R0, L>(self: Iterable<Result<R0, L>>): Iterable<R0>
  * 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"
  *
@@ -3584,10 +3683,8 @@ export 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"
    *
@@ -3628,10 +3725,8 @@ export 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"
    *
@@ -3672,10 +3767,8 @@ export 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"
    *
@@ -3716,10 +3809,8 @@ export 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"
    *
@@ -3781,7 +3872,8 @@ export 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"
  *
@@ -3815,7 +3907,7 @@ export const filter: {
  * ```
  *
  * @category sequencing
- * @since 2.0.0
+ * @since 4.0.0
  */
 export const flatMapNullishOr: {
   /**
@@ -3824,7 +3916,8 @@ export 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"
    *
@@ -3858,7 +3951,7 @@ export const flatMapNullishOr: {
    * ```
    *
    * @category sequencing
-   * @since 2.0.0
+   * @since 4.0.0
    */
   <A, B>(f: (a: A) => B): (self: Iterable<A>) => Iterable<NonNullable<B>>
   /**
@@ -3867,7 +3960,8 @@ export 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"
    *
@@ -3901,7 +3995,7 @@ export const flatMapNullishOr: {
    * ```
    *
    * @category sequencing
-   * @since 2.0.0
+   * @since 4.0.0
    */
   <A, B>(self: Iterable<A>, f: (a: A) => B): Iterable<NonNullable<B>>
 } = dual(
@@ -3916,7 +4010,8 @@ export const flatMapNullishOr: {
 /**
  * Check if a predicate holds true for some `Iterable` element.
  *
- * @example
+ * **Example** (Checking whether some element matches)
+ *
  * ```ts
  * import { Iterable } from "effect"
  *
@@ -3957,7 +4052,8 @@ export const some: {
   /**
    * Check if a predicate holds true for some `Iterable` element.
    *
-   * @example
+   * **Example** (Checking whether some element matches)
+   *
    * ```ts
    * import { Iterable } from "effect"
    *
@@ -3998,7 +4094,8 @@ export const some: {
   /**
    * Check if a predicate holds true for some `Iterable` element.
    *
-   * @example
+   * **Example** (Checking whether some element matches)
+   *
    * ```ts
    * import { Iterable } from "effect"
    *
@@ -4057,7 +4154,8 @@ export 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"
  *
@@ -4106,7 +4204,8 @@ export const unfold = <B, A>(b: B, f: (b: B) => Option<readonly [A, B]>): Iterab
 /**
  * Iterate over the `Iterable` applying `f`.
  *
- * @example
+ * **Example** (Iterating with side effects)
+ *
  * ```ts
  * import { Iterable } from "effect"
  *
@@ -4144,7 +4243,8 @@ export const forEach: {
   /**
    * Iterate over the `Iterable` applying `f`.
    *
-   * @example
+   * **Example** (Iterating with side effects)
+   *
    * ```ts
    * import { Iterable } from "effect"
    *
@@ -4182,7 +4282,8 @@ export const forEach: {
   /**
    * Iterate over the `Iterable` applying `f`.
    *
-   * @example
+   * **Example** (Iterating with side effects)
+   *
    * ```ts
    * import { Iterable } from "effect"
    *
@@ -4230,7 +4331,8 @@ export 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"
  *
@@ -4279,7 +4381,8 @@ export 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"
    *
@@ -4328,7 +4431,8 @@ export 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"
    *
@@ -4386,7 +4490,8 @@ export 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"
  *
@@ -4428,7 +4533,8 @@ export 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"
    *
@@ -4470,7 +4576,8 @@ export 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"
    *
@@ -4538,7 +4645,8 @@ export const dedupeAdjacentWith: {
 /**
  * Deduplicates adjacent elements that are identical.
  *
- * @example
+ * **Example** (Deduplicating adjacent elements)
+ *
  * ```ts
  * import { Iterable } from "effect"
  *
@@ -4577,7 +4685,8 @@ export const dedupeAdjacent: <A>(self: Iterable<A>) => Iterable<A> = dedupeAdjac
 /**
  * Zips this Iterable crosswise with the specified Iterable using the specified combiner.
  *
- * @example
+ * **Example** (Combining cartesian products)
+ *
  * ```ts
  * import { Iterable } from "effect"
  *
@@ -4620,14 +4729,15 @@ export const dedupeAdjacent: <A>(self: Iterable<A>) => Iterable<A> = dedupeAdjac
  * // ["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 const cartesianWith: {
   /**
    * Zips this Iterable crosswise with the specified Iterable using the specified combiner.
    *
-   * @example
+   * **Example** (Combining cartesian products)
+   *
    * ```ts
    * import { Iterable } from "effect"
    *
@@ -4670,14 +4780,15 @@ export 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"
    *
@@ -4720,8 +4831,8 @@ export 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>
 } = dual(
@@ -4733,7 +4844,8 @@ export const cartesianWith: {
 /**
  * Zips this Iterable crosswise with the specified Iterable.
  *
- * @example
+ * **Example** (Generating cartesian pairs)
+ *
  * ```ts
  * import { Iterable } from "effect"
  *
@@ -4767,14 +4879,15 @@ export const cartesianWith: {
  * console.log(Array.from(withEmpty)) // []
  * ```
  *
- * @since 2.0.0
  * @category elements
+ * @since 2.0.0
  */
 export const cartesian: {
   /**
    * Zips this Iterable crosswise with the specified Iterable.
    *
-   * @example
+   * **Example** (Generating cartesian pairs)
+   *
    * ```ts
    * import { Iterable } from "effect"
    *
@@ -4808,14 +4921,15 @@ export 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"
    *
@@ -4849,8 +4963,8 @@ export 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]>
 } = dual(
@@ -4861,7 +4975,7 @@ export const cartesian: {
 /**
  * Counts all the element of the given iterable that pass the given predicate
  *
- * **Example**
+ * **Example** (Counting matching elements)
  *
  * ```ts
  * import { Iterable } from "effect"
@@ -4877,7 +4991,7 @@ export 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"
@@ -4893,7 +5007,7 @@ export 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"