effect 3.8.4 → 3.9.0

package/src/Array.ts

@@ -123,7 +123,33 @@ export const range = (start: number, end: number): NonEmptyArray<number> =>
  * @since 2.0.0
  */
 export const replicate: {
+  /**
+   * Return a `NonEmptyArray` containing a value repeated the specified number of times.
+   *
+   * **Note**. `n` is normalized to an integer >= 1.
+   *
+   * @example
+   * import { Array } from "effect"
+   *
+   * assert.deepStrictEqual(Array.replicate("a", 3), ["a", "a", "a"])
+   *
+   * @category constructors
+   * @since 2.0.0
+   */
   (n: number): <A>(a: A) => NonEmptyArray<A>
+  /**
+   * Return a `NonEmptyArray` containing a value repeated the specified number of times.
+   *
+   * **Note**. `n` is normalized to an integer >= 1.
+   *
+   * @example
+   * import { Array } from "effect"
+   *
+   * assert.deepStrictEqual(Array.replicate("a", 3), ["a", "a", "a"])
+   *
+   * @category constructors
+   * @since 2.0.0
+   */
   <A>(a: A, n: number): NonEmptyArray<A>
 } = dual(2, <A>(a: A, n: number): NonEmptyArray<A> => makeBy(n, () => a))
 
@@ -207,12 +233,44 @@ export const fromOption: <A>(self: Option<A>) => Array<A> = O.toArray
  * @since 2.0.0
  */
 export const match: {
+  /**
+   * Matches the elements of an array, applying functions to cases of empty and non-empty arrays.
+   *
+   * @example
+   * import { Array } from "effect"
+   *
+   * const match = Array.match({
+   *   onEmpty: () => "empty",
+   *   onNonEmpty: ([head, ...tail]) => `head: ${head}, tail: ${tail.length}`
+   * })
+   * assert.deepStrictEqual(match([]), "empty")
+   * assert.deepStrictEqual(match([1, 2, 3]), "head: 1, tail: 2")
+   *
+   * @category pattern matching
+   * @since 2.0.0
+   */
   <B, A, C = B>(
     options: {
       readonly onEmpty: LazyArg<B>
       readonly onNonEmpty: (self: NonEmptyReadonlyArray<A>) => C
     }
   ): (self: ReadonlyArray<A>) => B | C
+  /**
+   * Matches the elements of an array, applying functions to cases of empty and non-empty arrays.
+   *
+   * @example
+   * import { Array } from "effect"
+   *
+   * const match = Array.match({
+   *   onEmpty: () => "empty",
+   *   onNonEmpty: ([head, ...tail]) => `head: ${head}, tail: ${tail.length}`
+   * })
+   * assert.deepStrictEqual(match([]), "empty")
+   * assert.deepStrictEqual(match([1, 2, 3]), "head: 1, tail: 2")
+   *
+   * @category pattern matching
+   * @since 2.0.0
+   */
   <A, B, C = B>(
     self: ReadonlyArray<A>,
     options: {
@@ -245,12 +303,44 @@ export const match: {
  * @since 2.0.0
  */
 export const matchLeft: {
+  /**
+   * Matches the elements of an array from the left, applying functions to cases of empty and non-empty arrays.
+   *
+   * @example
+   * import { Array } from "effect"
+   *
+   * const matchLeft = Array.matchLeft({
+   *   onEmpty: () => "empty",
+   *   onNonEmpty: (head, tail) => `head: ${head}, tail: ${tail.length}`
+   * })
+   * assert.deepStrictEqual(matchLeft([]), "empty")
+   * assert.deepStrictEqual(matchLeft([1, 2, 3]), "head: 1, tail: 2")
+   *
+   * @category pattern matching
+   * @since 2.0.0
+   */
   <B, A, C = B>(
     options: {
       readonly onEmpty: LazyArg<B>
       readonly onNonEmpty: (head: A, tail: Array<A>) => C
     }
   ): (self: ReadonlyArray<A>) => B | C
+  /**
+   * Matches the elements of an array from the left, applying functions to cases of empty and non-empty arrays.
+   *
+   * @example
+   * import { Array } from "effect"
+   *
+   * const matchLeft = Array.matchLeft({
+   *   onEmpty: () => "empty",
+   *   onNonEmpty: (head, tail) => `head: ${head}, tail: ${tail.length}`
+   * })
+   * assert.deepStrictEqual(matchLeft([]), "empty")
+   * assert.deepStrictEqual(matchLeft([1, 2, 3]), "head: 1, tail: 2")
+   *
+   * @category pattern matching
+   * @since 2.0.0
+   */
   <A, B, C = B>(
     self: ReadonlyArray<A>,
     options: {
@@ -283,12 +373,44 @@ export const matchLeft: {
  * @since 2.0.0
  */
 export const matchRight: {
+  /**
+   * Matches the elements of an array from the right, applying functions to cases of empty and non-empty arrays.
+   *
+   * @example
+   * import { Array } from "effect"
+   *
+   * const matchRight = Array.matchRight({
+   *   onEmpty: () => "empty",
+   *   onNonEmpty: (init, last) => `init: ${init.length}, last: ${last}`
+   * })
+   * assert.deepStrictEqual(matchRight([]), "empty")
+   * assert.deepStrictEqual(matchRight([1, 2, 3]), "init: 2, last: 3")
+   *
+   * @category pattern matching
+   * @since 2.0.0
+   */
   <B, A, C = B>(
     options: {
       readonly onEmpty: LazyArg<B>
       readonly onNonEmpty: (init: Array<A>, last: A) => C
     }
   ): (self: ReadonlyArray<A>) => B | C
+  /**
+   * Matches the elements of an array from the right, applying functions to cases of empty and non-empty arrays.
+   *
+   * @example
+   * import { Array } from "effect"
+   *
+   * const matchRight = Array.matchRight({
+   *   onEmpty: () => "empty",
+   *   onNonEmpty: (init, last) => `init: ${init.length}, last: ${last}`
+   * })
+   * assert.deepStrictEqual(matchRight([]), "empty")
+   * assert.deepStrictEqual(matchRight([1, 2, 3]), "init: 2, last: 3")
+   *
+   * @category pattern matching
+   * @since 2.0.0
+   */
   <A, B, C = B>(
     self: ReadonlyArray<A>,
     options: {
@@ -321,7 +443,33 @@ export const matchRight: {
  * @since 2.0.0
  */
 export const prepend: {
+  /**
+   * Prepend an element to the front of an `Iterable`, creating a new `NonEmptyArray`.
+   *
+   * @example
+   * import { Array } from "effect"
+   *
+   * const original = [2, 3, 4];
+   * const result = Array.prepend(original, 1);
+   * assert.deepStrictEqual(result, [1, 2, 3, 4]);
+   *
+   * @category concatenating
+   * @since 2.0.0
+   */
   <B>(head: B): <A>(self: Iterable<A>) => NonEmptyArray<A | B>
+  /**
+   * Prepend an element to the front of an `Iterable`, creating a new `NonEmptyArray`.
+   *
+   * @example
+   * import { Array } from "effect"
+   *
+   * const original = [2, 3, 4];
+   * const result = Array.prepend(original, 1);
+   * assert.deepStrictEqual(result, [1, 2, 3, 4]);
+   *
+   * @category concatenating
+   * @since 2.0.0
+   */
   <A, B>(self: Iterable<A>, head: B): NonEmptyArray<A | B>
 } = dual(2, <A, B>(self: Iterable<A>, head: B): NonEmptyArray<A | B> => [head, ...self])
 
@@ -341,11 +489,71 @@ export const prepend: {
  * @since 2.0.0
  */
 export const prependAll: {
+  /**
+   * Prepends the specified prefix array (or iterable) to the beginning of the specified array (or iterable).
+   * If either array is non-empty, the result is also a non-empty array.
+   *
+   * @example
+   * import { Array } from "effect"
+   *
+   * const prefix = [0, 1];
+   * const array = [2, 3];
+   * const result = Array.prependAll(array, prefix);
+   * assert.deepStrictEqual(result, [0, 1, 2, 3]);
+   *
+   * @category concatenating
+   * @since 2.0.0
+   */
   <S extends Iterable<any>, T extends Iterable<any>>(
     that: T
   ): (self: S) => ReadonlyArray.OrNonEmpty<S, T, ReadonlyArray.Infer<S> | ReadonlyArray.Infer<T>>
+  /**
+   * Prepends the specified prefix array (or iterable) to the beginning of the specified array (or iterable).
+   * If either array is non-empty, the result is also a non-empty array.
+   *
+   * @example
+   * import { Array } from "effect"
+   *
+   * const prefix = [0, 1];
+   * const array = [2, 3];
+   * const result = Array.prependAll(array, prefix);
+   * assert.deepStrictEqual(result, [0, 1, 2, 3]);
+   *
+   * @category concatenating
+   * @since 2.0.0
+   */
   <A, B>(self: Iterable<A>, that: NonEmptyReadonlyArray<B>): NonEmptyArray<A | B>
+  /**
+   * Prepends the specified prefix array (or iterable) to the beginning of the specified array (or iterable).
+   * If either array is non-empty, the result is also a non-empty array.
+   *
+   * @example
+   * import { Array } from "effect"
+   *
+   * const prefix = [0, 1];
+   * const array = [2, 3];
+   * const result = Array.prependAll(array, prefix);
+   * assert.deepStrictEqual(result, [0, 1, 2, 3]);
+   *
+   * @category concatenating
+   * @since 2.0.0
+   */
   <A, B>(self: NonEmptyReadonlyArray<A>, that: Iterable<B>): NonEmptyArray<A | B>
+  /**
+   * Prepends the specified prefix array (or iterable) to the beginning of the specified array (or iterable).
+   * If either array is non-empty, the result is also a non-empty array.
+   *
+   * @example
+   * import { Array } from "effect"
+   *
+   * const prefix = [0, 1];
+   * const array = [2, 3];
+   * const result = Array.prependAll(array, prefix);
+   * assert.deepStrictEqual(result, [0, 1, 2, 3]);
+   *
+   * @category concatenating
+   * @since 2.0.0
+   */
   <A, B>(self: Iterable<A>, that: Iterable<B>): Array<A | B>
 } = dual(
   2,
@@ -366,7 +574,33 @@ export const prependAll: {
  * @since 2.0.0
  */
 export const append: {
+  /**
+   * Append an element to the end of an `Iterable`, creating a new `NonEmptyArray`.
+   *
+   * @example
+   * import { Array } from "effect"
+   *
+   * const original = [1, 2, 3];
+   * const result = Array.append(original, 4);
+   * assert.deepStrictEqual(result, [1, 2, 3, 4]);
+   *
+   * @category concatenating
+   * @since 2.0.0
+   */
   <B>(last: B): <A>(self: Iterable<A>) => NonEmptyArray<A | B>
+  /**
+   * Append an element to the end of an `Iterable`, creating a new `NonEmptyArray`.
+   *
+   * @example
+   * import { Array } from "effect"
+   *
+   * const original = [1, 2, 3];
+   * const result = Array.append(original, 4);
+   * assert.deepStrictEqual(result, [1, 2, 3, 4]);
+   *
+   * @category concatenating
+   * @since 2.0.0
+   */
   <A, B>(self: Iterable<A>, last: B): NonEmptyArray<A | B>
 } = dual(2, <A, B>(self: Iterable<A>, last: B): Array<A | B> => [...self, last])
 
@@ -378,11 +612,39 @@ export const append: {
  * @since 2.0.0
  */
 export const appendAll: {
+  /**
+   * Concatenates two arrays (or iterables), combining their elements.
+   * If either array is non-empty, the result is also a non-empty array.
+   *
+   * @category concatenating
+   * @since 2.0.0
+   */
   <S extends Iterable<any>, T extends Iterable<any>>(
     that: T
   ): (self: S) => ReadonlyArray.OrNonEmpty<S, T, ReadonlyArray.Infer<S> | ReadonlyArray.Infer<T>>
+  /**
+   * Concatenates two arrays (or iterables), combining their elements.
+   * If either array is non-empty, the result is also a non-empty array.
+   *
+   * @category concatenating
+   * @since 2.0.0
+   */
   <A, B>(self: Iterable<A>, that: NonEmptyReadonlyArray<B>): NonEmptyArray<A | B>
+  /**
+   * Concatenates two arrays (or iterables), combining their elements.
+   * If either array is non-empty, the result is also a non-empty array.
+   *
+   * @category concatenating
+   * @since 2.0.0
+   */
   <A, B>(self: NonEmptyReadonlyArray<A>, that: Iterable<B>): NonEmptyArray<A | B>
+  /**
+   * Concatenates two arrays (or iterables), combining their elements.
+   * If either array is non-empty, the result is also a non-empty array.
+   *
+   * @category concatenating
+   * @since 2.0.0
+   */
   <A, B>(self: Iterable<A>, that: Iterable<B>): Array<A | B>
 } = dual(
   2,
@@ -411,7 +673,49 @@ export const appendAll: {
  * @since 2.0.0
  */
 export const scan: {
+  /**
+   * Accumulates values from an `Iterable` starting from the left, storing
+   * each intermediate result in an array. Useful for tracking the progression of
+   * a value through a series of transformations.
+   *
+   * @example
+   * import { Array } from "effect";
+   *
+   * const numbers = [1, 2, 3, 4]
+   * const result = Array.scan(numbers, 0, (acc, value) => acc + value)
+   * assert.deepStrictEqual(result, [0, 1, 3, 6, 10])
+   *
+   * // Explanation:
+   * // This function starts with the initial value (0 in this case)
+   * // and adds each element of the array to this accumulator one by one,
+   * // keeping track of the cumulative sum after each addition.
+   * // Each of these sums is captured in the resulting array.
+   *
+   * @category folding
+   * @since 2.0.0
+   */
   <B, A>(b: B, f: (b: B, a: A) => B): (self: Iterable<A>) => NonEmptyArray<B>
+  /**
+   * Accumulates values from an `Iterable` starting from the left, storing
+   * each intermediate result in an array. Useful for tracking the progression of
+   * a value through a series of transformations.
+   *
+   * @example
+   * import { Array } from "effect";
+   *
+   * const numbers = [1, 2, 3, 4]
+   * const result = Array.scan(numbers, 0, (acc, value) => acc + value)
+   * assert.deepStrictEqual(result, [0, 1, 3, 6, 10])
+   *
+   * // Explanation:
+   * // This function starts with the initial value (0 in this case)
+   * // and adds each element of the array to this accumulator one by one,
+   * // keeping track of the cumulative sum after each addition.
+   * // Each of these sums is captured in the resulting array.
+   *
+   * @category folding
+   * @since 2.0.0
+   */
   <A, B>(self: Iterable<A>, b: B, f: (b: B, a: A) => B): NonEmptyArray<B>
 } = dual(3, <A, B>(self: Iterable<A>, b: B, f: (b: B, a: A) => B): NonEmptyArray<B> => {
   const out: NonEmptyArray<B> = [b]
@@ -439,7 +743,37 @@ export const scan: {
  * @since 2.0.0
  */
 export const scanRight: {
+  /**
+   * Accumulates values from an `Iterable` starting from the right, storing
+   * each intermediate result in an array. Useful for tracking the progression of
+   * a value through a series of transformations.
+   *
+   * @example
+   * import { Array } from "effect";
+   *
+   * const numbers = [1, 2, 3, 4]
+   * const result = Array.scanRight(numbers, 0, (acc, value) => acc + value)
+   * assert.deepStrictEqual(result, [10, 9, 7, 4, 0])
+   *
+   * @category folding
+   * @since 2.0.0
+   */
   <B, A>(b: B, f: (b: B, a: A) => B): (self: Iterable<A>) => NonEmptyArray<B>
+  /**
+   * Accumulates values from an `Iterable` starting from the right, storing
+   * each intermediate result in an array. Useful for tracking the progression of
+   * a value through a series of transformations.
+   *
+   * @example
+   * import { Array } from "effect";
+   *
+   * const numbers = [1, 2, 3, 4]
+   * const result = Array.scanRight(numbers, 0, (acc, value) => acc + value)
+   * assert.deepStrictEqual(result, [10, 9, 7, 4, 0])
+   *
+   * @category folding
+   * @since 2.0.0
+   */
   <A, B>(self: Iterable<A>, b: B, f: (b: B, a: A) => B): NonEmptyArray<B>
 } = dual(3, <A, B>(self: Iterable<A>, b: B, f: (b: B, a: A) => B): NonEmptyArray<B> => {
   const input = fromIterable(self)
@@ -466,7 +800,35 @@ export const scanRight: {
  * @since 2.0.0
  */
 export const isArray: {
+  /**
+   * Determine if `unknown` is an Array.
+   *
+   * @param self - The value to check.
+   *
+   * @example
+   * import { isArray } from "effect/Array"
+   *
+   * assert.deepStrictEqual(isArray(null), false);
+   * assert.deepStrictEqual(isArray([1, 2, 3]), true);
+   *
+   * @category guards
+   * @since 2.0.0
+   */
   (self: unknown): self is Array<unknown>
+  /**
+   * Determine if `unknown` is an Array.
+   *
+   * @param self - The value to check.
+   *
+   * @example
+   * import { isArray } from "effect/Array"
+   *
+   * assert.deepStrictEqual(isArray(null), false);
+   * assert.deepStrictEqual(isArray([1, 2, 3]), true);
+   *
+   * @category guards
+   * @since 2.0.0
+   */
   <T>(self: T): self is Extract<T, ReadonlyArray<any>>
 } = Array.isArray
 
@@ -558,7 +920,19 @@ const clamp = <A>(i: number, as: ReadonlyArray<A>): number => Math.floor(Math.mi
  * @since 2.0.0
  */
 export const get: {
+  /**
+   * This function provides a safe way to read a value at a particular index from a `ReadonlyArray`.
+   *
+   * @category getters
+   * @since 2.0.0
+   */
   (index: number): <A>(self: ReadonlyArray<A>) => Option<A>
+  /**
+   * This function provides a safe way to read a value at a particular index from a `ReadonlyArray`.
+   *
+   * @category getters
+   * @since 2.0.0
+   */
   <A>(self: ReadonlyArray<A>, index: number): Option<A>
 } = dual(2, <A>(self: ReadonlyArray<A>, index: number): Option<A> => {
   const i = Math.floor(index)
@@ -572,7 +946,19 @@ export const get: {
  * @category unsafe
  */
 export const unsafeGet: {
+  /**
+   * Gets an element unsafely, will throw on out of bounds.
+   *
+   * @since 2.0.0
+   * @category unsafe
+   */
   (index: number): <A>(self: ReadonlyArray<A>) => A
+  /**
+   * Gets an element unsafely, will throw on out of bounds.
+   *
+   * @since 2.0.0
+   * @category unsafe
+   */
   <A>(self: ReadonlyArray<A>, index: number): A
 } = dual(2, <A>(self: ReadonlyArray<A>, index: number): A => {
   const i = Math.floor(index)
@@ -725,7 +1111,37 @@ export const initNonEmpty = <A>(self: NonEmptyReadonlyArray<A>): Array<A> => sel
  * @since 2.0.0
  */
 export const take: {
+  /**
+   * Keep only a max number of elements from the start of an `Iterable`, creating a new `Array`.
+   *
+   * **Note**. `n` is normalized to a non negative integer.
+   *
+   * @example
+   * import { Array } from "effect"
+   *
+   * const numbers = [1, 2, 3, 4, 5]
+   * const result = Array.take(numbers, 3)
+   * assert.deepStrictEqual(result, [1, 2, 3])
+   *
+   * @category getters
+   * @since 2.0.0
+   */
   (n: number): <A>(self: Iterable<A>) => Array<A>
+  /**
+   * Keep only a max number of elements from the start of an `Iterable`, creating a new `Array`.
+   *
+   * **Note**. `n` is normalized to a non negative integer.
+   *
+   * @example
+   * import { Array } from "effect"
+   *
+   * const numbers = [1, 2, 3, 4, 5]
+   * const result = Array.take(numbers, 3)
+   * assert.deepStrictEqual(result, [1, 2, 3])
+   *
+   * @category getters
+   * @since 2.0.0
+   */
   <A>(self: Iterable<A>, n: number): Array<A>
 } = dual(2, <A>(self: Iterable<A>, n: number): Array<A> => {
   const input = fromIterable(self)
@@ -748,7 +1164,37 @@ export const take: {
  * @since 2.0.0
  */
 export const takeRight: {
+  /**
+   * Keep only a max number of elements from the end of an `Iterable`, creating a new `Array`.
+   *
+   * **Note**. `n` is normalized to a non negative integer.
+   *
+   * @example
+   * import { Array } from "effect"
+   *
+   * const numbers = [1, 2, 3, 4, 5]
+   * const result = Array.takeRight(numbers, 3)
+   * assert.deepStrictEqual(result, [3, 4, 5])
+   *
+   * @category getters
+   * @since 2.0.0
+   */
   (n: number): <A>(self: Iterable<A>) => Array<A>
+  /**
+   * Keep only a max number of elements from the end of an `Iterable`, creating a new `Array`.
+   *
+   * **Note**. `n` is normalized to a non negative integer.
+   *
+   * @example
+   * import { Array } from "effect"
+   *
+   * const numbers = [1, 2, 3, 4, 5]
+   * const result = Array.takeRight(numbers, 3)
+   * assert.deepStrictEqual(result, [3, 4, 5])
+   *
+   * @category getters
+   * @since 2.0.0
+   */
   <A>(self: Iterable<A>, n: number): Array<A>
 } = dual(2, <A>(self: Iterable<A>, n: number): Array<A> => {
   const input = fromIterable(self)
@@ -776,9 +1222,85 @@ export const takeRight: {
  * @since 2.0.0
  */
 export const takeWhile: {
+  /**
+   * Calculate the longest initial subarray for which all element satisfy the specified predicate, creating a new `Array`.
+   *
+   * @example
+   * import { Array } from "effect"
+   *
+   * const numbers = [1, 3, 2, 4, 1, 2]
+   * const result = Array.takeWhile(numbers, x => x < 4)
+   * assert.deepStrictEqual(result, [1, 3, 2])
+   *
+   * // Explanation:
+   * // - The function starts with the first element (`1`), which is less than `4`, so it adds `1` to the result.
+   * // - The next element (`3`) is also less than `4`, so it adds `3`.
+   * // - The next element (`2`) is again less than `4`, so it adds `2`.
+   * // - The function then encounters `4`, which is not less than `4`. At this point, it stops checking further elements and finalizes the result.
+   *
+   * @category getters
+   * @since 2.0.0
+   */
   <A, B extends A>(refinement: (a: NoInfer<A>, i: number) => a is B): (self: Iterable<A>) => Array<B>
+  /**
+   * Calculate the longest initial subarray for which all element satisfy the specified predicate, creating a new `Array`.
+   *
+   * @example
+   * import { Array } from "effect"
+   *
+   * const numbers = [1, 3, 2, 4, 1, 2]
+   * const result = Array.takeWhile(numbers, x => x < 4)
+   * assert.deepStrictEqual(result, [1, 3, 2])
+   *
+   * // Explanation:
+   * // - The function starts with the first element (`1`), which is less than `4`, so it adds `1` to the result.
+   * // - The next element (`3`) is also less than `4`, so it adds `3`.
+   * // - The next element (`2`) is again less than `4`, so it adds `2`.
+   * // - The function then encounters `4`, which is not less than `4`. At this point, it stops checking further elements and finalizes the result.
+   *
+   * @category getters
+   * @since 2.0.0
+   */
   <A>(predicate: (a: NoInfer<A>, i: number) => boolean): (self: Iterable<A>) => Array<A>
+  /**
+   * Calculate the longest initial subarray for which all element satisfy the specified predicate, creating a new `Array`.
+   *
+   * @example
+   * import { Array } from "effect"
+   *
+   * const numbers = [1, 3, 2, 4, 1, 2]
+   * const result = Array.takeWhile(numbers, x => x < 4)
+   * assert.deepStrictEqual(result, [1, 3, 2])
+   *
+   * // Explanation:
+   * // - The function starts with the first element (`1`), which is less than `4`, so it adds `1` to the result.
+   * // - The next element (`3`) is also less than `4`, so it adds `3`.
+   * // - The next element (`2`) is again less than `4`, so it adds `2`.
+   * // - The function then encounters `4`, which is not less than `4`. At this point, it stops checking further elements and finalizes the result.
+   *
+   * @category getters
+   * @since 2.0.0
+   */
   <A, B extends A>(self: Iterable<A>, refinement: (a: A, i: number) => a is B): Array<B>
+  /**
+   * Calculate the longest initial subarray for which all element satisfy the specified predicate, creating a new `Array`.
+   *
+   * @example
+   * import { Array } from "effect"
+   *
+   * const numbers = [1, 3, 2, 4, 1, 2]
+   * const result = Array.takeWhile(numbers, x => x < 4)
+   * assert.deepStrictEqual(result, [1, 3, 2])
+   *
+   * // Explanation:
+   * // - The function starts with the first element (`1`), which is less than `4`, so it adds `1` to the result.
+   * // - The next element (`3`) is also less than `4`, so it adds `3`.
+   * // - The next element (`2`) is again less than `4`, so it adds `2`.
+   * // - The function then encounters `4`, which is not less than `4`. At this point, it stops checking further elements and finalizes the result.
+   *
+   * @category getters
+   * @since 2.0.0
+   */
   <A>(self: Iterable<A>, predicate: (a: A, i: number) => boolean): Array<A>
 } = dual(2, <A>(self: Iterable<A>, predicate: (a: A, i: number) => boolean): Array<A> => {
   let i = 0
@@ -814,14 +1336,50 @@ const spanIndex = <A>(self: Iterable<A>, predicate: (a: A, i: number) => boolean
  * @since 2.0.0
  */
 export const span: {
+  /**
+   * Split an `Iterable` into two parts:
+   *
+   * 1. the longest initial subarray for which all elements satisfy the specified predicate
+   * 2. the remaining elements
+   *
+   * @category splitting
+   * @since 2.0.0
+   */
   <A, B extends A>(
     refinement: (a: NoInfer<A>, i: number) => a is B
   ): (self: Iterable<A>) => [init: Array<B>, rest: Array<Exclude<A, B>>]
+  /**
+   * Split an `Iterable` into two parts:
+   *
+   * 1. the longest initial subarray for which all elements satisfy the specified predicate
+   * 2. the remaining elements
+   *
+   * @category splitting
+   * @since 2.0.0
+   */
   <A>(predicate: (a: NoInfer<A>, i: number) => boolean): (self: Iterable<A>) => [init: Array<A>, rest: Array<A>]
+  /**
+   * Split an `Iterable` into two parts:
+   *
+   * 1. the longest initial subarray for which all elements satisfy the specified predicate
+   * 2. the remaining elements
+   *
+   * @category splitting
+   * @since 2.0.0
+   */
   <A, B extends A>(
     self: Iterable<A>,
     refinement: (a: A, i: number) => a is B
   ): [init: Array<B>, rest: Array<Exclude<A, B>>]
+  /**
+   * Split an `Iterable` into two parts:
+   *
+   * 1. the longest initial subarray for which all elements satisfy the specified predicate
+   * 2. the remaining elements
+   *
+   * @category splitting
+   * @since 2.0.0
+   */
   <A>(self: Iterable<A>, predicate: (a: A, i: number) => boolean): [init: Array<A>, rest: Array<A>]
 } = dual(
   2,
@@ -845,7 +1403,37 @@ export const span: {
  * @since 2.0.0
  */
 export const drop: {
+  /**
+   * Drop a max number of elements from the start of an `Iterable`, creating a new `Array`.
+   *
+   * **Note**. `n` is normalized to a non negative integer.
+   *
+   * @example
+   * import { Array } from "effect"
+   *
+   * const numbers = [1, 2, 3, 4, 5]
+   * const result = Array.drop(numbers, 2)
+   * assert.deepStrictEqual(result, [3, 4, 5])
+   *
+   * @category getters
+   * @since 2.0.0
+   */
   (n: number): <A>(self: Iterable<A>) => Array<A>
+  /**
+   * Drop a max number of elements from the start of an `Iterable`, creating a new `Array`.
+   *
+   * **Note**. `n` is normalized to a non negative integer.
+   *
+   * @example
+   * import { Array } from "effect"
+   *
+   * const numbers = [1, 2, 3, 4, 5]
+   * const result = Array.drop(numbers, 2)
+   * assert.deepStrictEqual(result, [3, 4, 5])
+   *
+   * @category getters
+   * @since 2.0.0
+   */
   <A>(self: Iterable<A>, n: number): Array<A>
 } = dual(2, <A>(self: Iterable<A>, n: number): Array<A> => {
   const input = fromIterable(self)
@@ -868,7 +1456,37 @@ export const drop: {
  * @since 2.0.0
  */
 export const dropRight: {
+  /**
+   * Drop a max number of elements from the end of an `Iterable`, creating a new `Array`.
+   *
+   * **Note**. `n` is normalized to a non negative integer.
+   *
+   * @example
+   * import { Array } from "effect"
+   *
+   * const numbers = [1, 2, 3, 4, 5]
+   * const result = Array.dropRight(numbers, 2)
+   * assert.deepStrictEqual(result, [1, 2, 3])
+   *
+   * @category getters
+   * @since 2.0.0
+   */
   (n: number): <A>(self: Iterable<A>) => Array<A>
+  /**
+   * Drop a max number of elements from the end of an `Iterable`, creating a new `Array`.
+   *
+   * **Note**. `n` is normalized to a non negative integer.
+   *
+   * @example
+   * import { Array } from "effect"
+   *
+   * const numbers = [1, 2, 3, 4, 5]
+   * const result = Array.dropRight(numbers, 2)
+   * assert.deepStrictEqual(result, [1, 2, 3])
+   *
+   * @category getters
+   * @since 2.0.0
+   */
   <A>(self: Iterable<A>, n: number): Array<A>
 } = dual(2, <A>(self: Iterable<A>, n: number): Array<A> => {
   const input = fromIterable(self)
@@ -889,7 +1507,33 @@ export const dropRight: {
  * @since 2.0.0
  */
 export const dropWhile: {
+  /**
+   * Remove the longest initial subarray for which all element satisfy the specified predicate, creating a new `Array`.
+   *
+   * @example
+   * import { Array } from "effect"
+   *
+   * const numbers = [1, 2, 3, 4, 5]
+   * const result = Array.dropWhile(numbers, x => x < 4)
+   * assert.deepStrictEqual(result, [4, 5])
+   *
+   * @category getters
+   * @since 2.0.0
+   */
   <A>(predicate: (a: NoInfer<A>, i: number) => boolean): (self: Iterable<A>) => Array<A>
+  /**
+   * Remove the longest initial subarray for which all element satisfy the specified predicate, creating a new `Array`.
+   *
+   * @example
+   * import { Array } from "effect"
+   *
+   * const numbers = [1, 2, 3, 4, 5]
+   * const result = Array.dropWhile(numbers, x => x < 4)
+   * assert.deepStrictEqual(result, [4, 5])
+   *
+   * @category getters
+   * @since 2.0.0
+   */
   <A>(self: Iterable<A>, predicate: (a: A, i: number) => boolean): Array<A>
 } = dual(
   2,
@@ -911,7 +1555,33 @@ export const dropWhile: {
  * @since 2.0.0
  */
 export const findFirstIndex: {
+  /**
+   * Return the first index for which a predicate holds.
+   *
+   * @example
+   * import { Array, Option } from "effect"
+   *
+   * const numbers = [5, 3, 8, 9]
+   * const result = Array.findFirstIndex(numbers, x => x > 5)
+   * assert.deepStrictEqual(result, Option.some(2))
+   *
+   * @category elements
+   * @since 2.0.0
+   */
   <A>(predicate: (a: NoInfer<A>, i: number) => boolean): (self: Iterable<A>) => Option<number>
+  /**
+   * Return the first index for which a predicate holds.
+   *
+   * @example
+   * import { Array, Option } from "effect"
+   *
+   * const numbers = [5, 3, 8, 9]
+   * const result = Array.findFirstIndex(numbers, x => x > 5)
+   * assert.deepStrictEqual(result, Option.some(2))
+   *
+   * @category elements
+   * @since 2.0.0
+   */
   <A>(self: Iterable<A>, predicate: (a: A, i: number) => boolean): Option<number>
 } = dual(2, <A>(self: Iterable<A>, predicate: (a: A, i: number) => boolean): Option<number> => {
   let i = 0
@@ -938,7 +1608,33 @@ export const findFirstIndex: {
  * @since 2.0.0
  */
 export const findLastIndex: {
+  /**
+   * Return the last index for which a predicate holds.
+   *
+   * @example
+   * import { Array, Option } from "effect"
+   *
+   * const numbers = [1, 3, 8, 9]
+   * const result = Array.findLastIndex(numbers, x => x < 5)
+   * assert.deepStrictEqual(result, Option.some(1))
+   *
+   * @category elements
+   * @since 2.0.0
+   */
   <A>(predicate: (a: NoInfer<A>, i: number) => boolean): (self: Iterable<A>) => Option<number>
+  /**
+   * Return the last index for which a predicate holds.
+   *
+   * @example
+   * import { Array, Option } from "effect"
+   *
+   * const numbers = [1, 3, 8, 9]
+   * const result = Array.findLastIndex(numbers, x => x < 5)
+   * assert.deepStrictEqual(result, Option.some(1))
+   *
+   * @category elements
+   * @since 2.0.0
+   */
   <A>(self: Iterable<A>, predicate: (a: A, i: number) => boolean): Option<number>
 } = dual(2, <A>(self: Iterable<A>, predicate: (a: A, i: number) => boolean): Option<number> => {
   const input = fromIterable(self)
@@ -965,11 +1661,95 @@ export const findLastIndex: {
  * @since 2.0.0
  */
 export const findFirst: {
+  /**
+   * Returns the first element that satisfies the specified
+   * predicate, or `None` if no such element exists.
+   *
+   * @example
+   * import { Array, Option } from "effect"
+   *
+   * const numbers = [1, 2, 3, 4, 5]
+   * const result = Array.findFirst(numbers, x => x > 3)
+   * assert.deepStrictEqual(result, Option.some(4))
+   *
+   * @category elements
+   * @since 2.0.0
+   */
   <A, B>(f: (a: NoInfer<A>, i: number) => Option<B>): (self: Iterable<A>) => Option<B>
+  /**
+   * Returns the first element that satisfies the specified
+   * predicate, or `None` if no such element exists.
+   *
+   * @example
+   * import { Array, Option } from "effect"
+   *
+   * const numbers = [1, 2, 3, 4, 5]
+   * const result = Array.findFirst(numbers, x => x > 3)
+   * assert.deepStrictEqual(result, Option.some(4))
+   *
+   * @category elements
+   * @since 2.0.0
+   */
   <A, B extends A>(refinement: (a: NoInfer<A>, i: number) => a is B): (self: Iterable<A>) => Option<B>
+  /**
+   * Returns the first element that satisfies the specified
+   * predicate, or `None` if no such element exists.
+   *
+   * @example
+   * import { Array, Option } from "effect"
+   *
+   * const numbers = [1, 2, 3, 4, 5]
+   * const result = Array.findFirst(numbers, x => x > 3)
+   * assert.deepStrictEqual(result, Option.some(4))
+   *
+   * @category elements
+   * @since 2.0.0
+   */
   <A>(predicate: (a: NoInfer<A>, i: number) => boolean): (self: Iterable<A>) => Option<A>
+  /**
+   * Returns the first element that satisfies the specified
+   * predicate, or `None` if no such element exists.
+   *
+   * @example
+   * import { Array, Option } from "effect"
+   *
+   * const numbers = [1, 2, 3, 4, 5]
+   * const result = Array.findFirst(numbers, x => x > 3)
+   * assert.deepStrictEqual(result, Option.some(4))
+   *
+   * @category elements
+   * @since 2.0.0
+   */
   <A, B>(self: Iterable<A>, f: (a: A, i: number) => Option<B>): Option<B>
+  /**
+   * Returns the first element that satisfies the specified
+   * predicate, or `None` if no such element exists.
+   *
+   * @example
+   * import { Array, Option } from "effect"
+   *
+   * const numbers = [1, 2, 3, 4, 5]
+   * const result = Array.findFirst(numbers, x => x > 3)
+   * assert.deepStrictEqual(result, Option.some(4))
+   *
+   * @category elements
+   * @since 2.0.0
+   */
   <A, B extends A>(self: Iterable<A>, refinement: (a: A, i: number) => a is B): Option<B>
+  /**
+   * Returns the first element that satisfies the specified
+   * predicate, or `None` if no such element exists.
+   *
+   * @example
+   * import { Array, Option } from "effect"
+   *
+   * const numbers = [1, 2, 3, 4, 5]
+   * const result = Array.findFirst(numbers, x => x > 3)
+   * assert.deepStrictEqual(result, Option.some(4))
+   *
+   * @category elements
+   * @since 2.0.0
+   */
   <A>(self: Iterable<A>, predicate: (a: A, i: number) => boolean): Option<A>
 } = EffectIterable.findFirst
 
@@ -988,11 +1768,95 @@ export const findFirst: {
  * @since 2.0.0
  */
 export const findLast: {
+  /**
+   * Finds the last element in an iterable collection that satisfies the given predicate or refinement.
+   * Returns an `Option` containing the found element, or `Option.none` if no element matches.
+   *
+   * @example
+   * import { Array, Option } from "effect"
+   *
+   * const numbers = [1, 2, 3, 4, 5]
+   * const result = Array.findLast(numbers, n => n % 2 === 0)
+   * assert.deepStrictEqual(result, Option.some(4))
+   *
+   * @category elements
+   * @since 2.0.0
+   */
   <A, B>(f: (a: NoInfer<A>, i: number) => Option<B>): (self: Iterable<A>) => Option<B>
+  /**
+   * Finds the last element in an iterable collection that satisfies the given predicate or refinement.
+   * Returns an `Option` containing the found element, or `Option.none` if no element matches.
+   *
+   * @example
+   * import { Array, Option } from "effect"
+   *
+   * const numbers = [1, 2, 3, 4, 5]
+   * const result = Array.findLast(numbers, n => n % 2 === 0)
+   * assert.deepStrictEqual(result, Option.some(4))
+   *
+   * @category elements
+   * @since 2.0.0
+   */
   <A, B extends A>(refinement: (a: NoInfer<A>, i: number) => a is B): (self: Iterable<A>) => Option<B>
+  /**
+   * Finds the last element in an iterable collection that satisfies the given predicate or refinement.
+   * Returns an `Option` containing the found element, or `Option.none` if no element matches.
+   *
+   * @example
+   * import { Array, Option } from "effect"
+   *
+   * const numbers = [1, 2, 3, 4, 5]
+   * const result = Array.findLast(numbers, n => n % 2 === 0)
+   * assert.deepStrictEqual(result, Option.some(4))
+   *
+   * @category elements
+   * @since 2.0.0
+   */
   <A>(predicate: (a: NoInfer<A>, i: number) => boolean): (self: Iterable<A>) => Option<A>
+  /**
+   * Finds the last element in an iterable collection that satisfies the given predicate or refinement.
+   * Returns an `Option` containing the found element, or `Option.none` if no element matches.
+   *
+   * @example
+   * import { Array, Option } from "effect"
+   *
+   * const numbers = [1, 2, 3, 4, 5]
+   * const result = Array.findLast(numbers, n => n % 2 === 0)
+   * assert.deepStrictEqual(result, Option.some(4))
+   *
+   * @category elements
+   * @since 2.0.0
+   */
   <A, B>(self: Iterable<A>, f: (a: A, i: number) => Option<B>): Option<B>
+  /**
+   * Finds the last element in an iterable collection that satisfies the given predicate or refinement.
+   * Returns an `Option` containing the found element, or `Option.none` if no element matches.
+   *
+   * @example
+   * import { Array, Option } from "effect"
+   *
+   * const numbers = [1, 2, 3, 4, 5]
+   * const result = Array.findLast(numbers, n => n % 2 === 0)
+   * assert.deepStrictEqual(result, Option.some(4))
+   *
+   * @category elements
+   * @since 2.0.0
+   */
   <A, B extends A>(self: Iterable<A>, refinement: (a: A, i: number) => a is B): Option<B>
+  /**
+   * Finds the last element in an iterable collection that satisfies the given predicate or refinement.
+   * Returns an `Option` containing the found element, or `Option.none` if no element matches.
+   *
+   * @example
+   * import { Array, Option } from "effect"
+   *
+   * const numbers = [1, 2, 3, 4, 5]
+   * const result = Array.findLast(numbers, n => n % 2 === 0)
+   * assert.deepStrictEqual(result, Option.some(4))
+   *
+   * @category elements
+   * @since 2.0.0
+   */
   <A>(self: Iterable<A>, predicate: (a: A, i: number) => boolean): Option<A>
 } = dual(
   2,
@@ -1029,7 +1893,33 @@ export const findLast: {
  * @since 2.0.0
  */
 export const insertAt: {
+  /**
+   * Insert an element at the specified index, creating a new `NonEmptyArray`,
+   * or return `None` if the index is out of bounds.
+   *
+   * @example
+   * import { Array, Option } from "effect"
+   *
+   * const letters = ['a', 'b', 'c', 'e']
+   * const result = Array.insertAt(letters, 3, 'd')
+   * assert.deepStrictEqual(result, Option.some(['a', 'b', 'c', 'd', 'e']))
+   *
+   * @since 2.0.0
+   */
   <B>(i: number, b: B): <A>(self: Iterable<A>) => Option<NonEmptyArray<A | B>>
+  /**
+   * Insert an element at the specified index, creating a new `NonEmptyArray`,
+   * or return `None` if the index is out of bounds.
+   *
+   * @example
+   * import { Array, Option } from "effect"
+   *
+   * const letters = ['a', 'b', 'c', 'e']
+   * const result = Array.insertAt(letters, 3, 'd')
+   * assert.deepStrictEqual(result, Option.some(['a', 'b', 'c', 'd', 'e']))
+   *
+   * @since 2.0.0
+   */
   <A, B>(self: Iterable<A>, i: number, b: B): Option<NonEmptyArray<A | B>>
 } = dual(3, <A, B>(self: Iterable<A>, i: number, b: B): Option<NonEmptyArray<A | B>> => {
   const out: Array<A | B> = Array.from(self)
@@ -1055,12 +1945,35 @@ export const insertAt: {
  * @since 2.0.0
  */
 export const replace: {
-  <B>(
-    i: number,
-    b: B
-  ): <A, S extends Iterable<A> = Iterable<A>>(
+  /**
+   * Change the element at the specified index, creating a new `Array`,
+   * or return a copy of the input if the index is out of bounds.
+   *
+   * @example
+   * import { Array } from "effect"
+   *
+   * const letters = ['a', 'b', 'c', 'd']
+   * const result = Array.replace(letters, 1, 'z')
+   * assert.deepStrictEqual(result, ['a', 'z', 'c', 'd'])
+   *
+   * @since 2.0.0
+   */
+  <B>(i: number, b: B): <A, S extends Iterable<A> = Iterable<A>>(
     self: S
   ) => ReadonlyArray.With<S, ReadonlyArray.Infer<S> | B>
+  /**
+   * Change the element at the specified index, creating a new `Array`,
+   * or return a copy of the input if the index is out of bounds.
+   *
+   * @example
+   * import { Array } from "effect"
+   *
+   * const letters = ['a', 'b', 'c', 'd']
+   * const result = Array.replace(letters, 1, 'z')
+   * assert.deepStrictEqual(result, ['a', 'z', 'c', 'd'])
+   *
+   * @since 2.0.0
+   */
   <A, B, S extends Iterable<A> = Iterable<A>>(
     self: S,
     i: number,
@@ -1081,10 +1994,34 @@ export const replace: {
  * @since 2.0.0
  */
 export const replaceOption: {
+  /**
+   * Replaces an element in an array with the given value, returning an option of the updated array.
+   *
+   * @example
+   * import { Array, Option } from "effect"
+   *
+   * const numbers = [1, 2, 3]
+   * const result = Array.replaceOption(numbers, 1, 4)
+   * assert.deepStrictEqual(result, Option.some([1, 4, 3]))
+   *
+   * @since 2.0.0
+   */
   <B>(
     i: number,
     b: B
   ): <A, S extends Iterable<A> = Iterable<A>>(self: S) => Option<ReadonlyArray.With<S, ReadonlyArray.Infer<S> | B>>
+  /**
+   * Replaces an element in an array with the given value, returning an option of the updated array.
+   *
+   * @example
+   * import { Array, Option } from "effect"
+   *
+   * const numbers = [1, 2, 3]
+   * const result = Array.replaceOption(numbers, 1, 4)
+   * assert.deepStrictEqual(result, Option.some([1, 4, 3]))
+   *
+   * @since 2.0.0
+   */
   <A, B, S extends Iterable<A> = Iterable<A>>(
     self: S,
     i: number,
@@ -1109,10 +2046,36 @@ export const replaceOption: {
  * @since 2.0.0
  */
 export const modify: {
+  /**
+   * Apply a function to the element at the specified index, creating a new `Array`,
+   * or return a copy of the input if the index is out of bounds.
+   *
+   * @example
+   * import { Array } from "effect"
+   *
+   * const numbers = [1, 2, 3, 4]
+   * const result = Array.modify(numbers, 2, (n) => n * 2)
+   * assert.deepStrictEqual(result, [1, 2, 6, 4])
+   *
+   * @since 2.0.0
+   */
   <A, B, S extends Iterable<A> = Iterable<A>>(
     i: number,
     f: (a: ReadonlyArray.Infer<S>) => B
   ): (self: S) => ReadonlyArray.With<S, ReadonlyArray.Infer<S> | B>
+  /**
+   * Apply a function to the element at the specified index, creating a new `Array`,
+   * or return a copy of the input if the index is out of bounds.
+   *
+   * @example
+   * import { Array } from "effect"
+   *
+   * const numbers = [1, 2, 3, 4]
+   * const result = Array.modify(numbers, 2, (n) => n * 2)
+   * assert.deepStrictEqual(result, [1, 2, 6, 4])
+   *
+   * @since 2.0.0
+   */
   <A, B, S extends Iterable<A> = Iterable<A>>(
     self: S,
     i: number,
@@ -1141,10 +2104,42 @@ export const modify: {
  * @since 2.0.0
  */
 export const modifyOption: {
+  /**
+   * Apply a function to the element at the specified index, creating a new `Array`,
+   * or return `None` if the index is out of bounds.
+   *
+   * @example
+   * import { Array, Option } from "effect"
+   *
+   * const numbers = [1, 2, 3, 4]
+   * const result = Array.modifyOption(numbers, 2, (n) => n * 2)
+   * assert.deepStrictEqual(result, Option.some([1, 2, 6, 4]))
+   *
+   * const outOfBoundsResult = Array.modifyOption(numbers, 5, (n) => n * 2)
+   * assert.deepStrictEqual(outOfBoundsResult, Option.none())
+   *
+   * @since 2.0.0
+   */
   <A, B, S extends Iterable<A> = Iterable<A>>(
     i: number,
     f: (a: ReadonlyArray.Infer<S>) => B
   ): (self: S) => Option<ReadonlyArray.With<S, ReadonlyArray.Infer<S> | B>>
+  /**
+   * Apply a function to the element at the specified index, creating a new `Array`,
+   * or return `None` if the index is out of bounds.
+   *
+   * @example
+   * import { Array, Option } from "effect"
+   *
+   * const numbers = [1, 2, 3, 4]
+   * const result = Array.modifyOption(numbers, 2, (n) => n * 2)
+   * assert.deepStrictEqual(result, Option.some([1, 2, 6, 4]))
+   *
+   * const outOfBoundsResult = Array.modifyOption(numbers, 5, (n) => n * 2)
+   * assert.deepStrictEqual(outOfBoundsResult, Option.none())
+   *
+   * @since 2.0.0
+   */
   <A, B, S extends Iterable<A> = Iterable<A>>(
     self: S,
     i: number,
@@ -1178,9 +2173,41 @@ export const modifyOption: {
  * @since 2.0.0
  */
 export const remove: {
-  (i: number): <A>(self: Iterable<A>) => Array<A>
-  <A>(self: Iterable<A>, i: number): Array<A>
-} = dual(2, <A>(self: Iterable<A>, i: number): Array<A> => {
+  /**
+   * Delete the element at the specified index, creating a new `Array`,
+   * or return a copy of the input if the index is out of bounds.
+   *
+   * @example
+   * import { Array } from "effect"
+   *
+   * const numbers = [1, 2, 3, 4]
+   * const result = Array.remove(numbers, 2)
+   * assert.deepStrictEqual(result, [1, 2, 4])
+   *
+   * const outOfBoundsResult = Array.remove(numbers, 5)
+   * assert.deepStrictEqual(outOfBoundsResult, [1, 2, 3, 4])
+   *
+   * @since 2.0.0
+   */
+  (i: number): <A>(self: Iterable<A>) => Array<A>
+  /**
+   * Delete the element at the specified index, creating a new `Array`,
+   * or return a copy of the input if the index is out of bounds.
+   *
+   * @example
+   * import { Array } from "effect"
+   *
+   * const numbers = [1, 2, 3, 4]
+   * const result = Array.remove(numbers, 2)
+   * assert.deepStrictEqual(result, [1, 2, 4])
+   *
+   * const outOfBoundsResult = Array.remove(numbers, 5)
+   * assert.deepStrictEqual(outOfBoundsResult, [1, 2, 3, 4])
+   *
+   * @since 2.0.0
+   */
+  <A>(self: Iterable<A>, i: number): Array<A>
+} = dual(2, <A>(self: Iterable<A>, i: number): Array<A> => {
   const out = Array.from(self)
   if (isOutOfBound(i, out)) {
     return out
@@ -1215,10 +2242,31 @@ export const reverse = <S extends Iterable<any> | NonEmptyReadonlyArray<any>>(
  * @since 2.0.0
  */
 export const sort: {
+  /**
+   * Create a new array with elements sorted in increasing order based on the specified comparator.
+   * If the input is a `NonEmptyReadonlyArray`, the output will also be a `NonEmptyReadonlyArray`.
+   *
+   * @category sorting
+   * @since 2.0.0
+   */
   <B>(
     O: Order.Order<B>
   ): <A extends B, S extends ReadonlyArray<A> | Iterable<A>>(self: S) => ReadonlyArray.With<S, ReadonlyArray.Infer<S>>
+  /**
+   * Create a new array with elements sorted in increasing order based on the specified comparator.
+   * If the input is a `NonEmptyReadonlyArray`, the output will also be a `NonEmptyReadonlyArray`.
+   *
+   * @category sorting
+   * @since 2.0.0
+   */
   <A extends B, B>(self: NonEmptyReadonlyArray<A>, O: Order.Order<B>): NonEmptyArray<A>
+  /**
+   * Create a new array with elements sorted in increasing order based on the specified comparator.
+   * If the input is a `NonEmptyReadonlyArray`, the output will also be a `NonEmptyReadonlyArray`.
+   *
+   * @category sorting
+   * @since 2.0.0
+   */
   <A extends B, B>(self: Iterable<A>, O: Order.Order<B>): Array<A>
 } = dual(2, <A extends B, B>(self: Iterable<A>, O: Order.Order<B>): Array<A> => {
   const out = Array.from(self)
@@ -1247,11 +2295,71 @@ export const sort: {
  * @category elements
  */
 export const sortWith: {
+  /**
+   * Sorts an array based on a provided mapping function and order. The mapping
+   * function transforms the elements into a value that can be compared, and the
+   * order defines how those values should be sorted.
+   *
+   * @example
+   * import { Array, Order } from "effect"
+   *
+   * const strings = ["aaa", "b", "cc"]
+   * const result = Array.sortWith(strings, (s) => s.length, Order.number)
+   * assert.deepStrictEqual(result, ["b", "cc", "aaa"])
+   *
+   * // Explanation:
+   * // The array of strings is sorted based on their lengths. The mapping function `(s) => s.length`
+   * // converts each string into its length, and the `Order.number` specifies that the lengths should
+   * // be sorted in ascending order.
+   *
+   * @since 2.0.0
+   * @category elements
+   */
   <S extends Iterable<any> | NonEmptyReadonlyArray<any>, B>(
     f: (a: ReadonlyArray.Infer<S>) => B,
     order: Order.Order<B>
   ): (self: S) => ReadonlyArray.With<S, ReadonlyArray.Infer<S>>
+  /**
+   * Sorts an array based on a provided mapping function and order. The mapping
+   * function transforms the elements into a value that can be compared, and the
+   * order defines how those values should be sorted.
+   *
+   * @example
+   * import { Array, Order } from "effect"
+   *
+   * const strings = ["aaa", "b", "cc"]
+   * const result = Array.sortWith(strings, (s) => s.length, Order.number)
+   * assert.deepStrictEqual(result, ["b", "cc", "aaa"])
+   *
+   * // Explanation:
+   * // The array of strings is sorted based on their lengths. The mapping function `(s) => s.length`
+   * // converts each string into its length, and the `Order.number` specifies that the lengths should
+   * // be sorted in ascending order.
+   *
+   * @since 2.0.0
+   * @category elements
+   */
   <A, B>(self: NonEmptyReadonlyArray<A>, f: (a: A) => B, O: Order.Order<B>): NonEmptyArray<A>
+  /**
+   * Sorts an array based on a provided mapping function and order. The mapping
+   * function transforms the elements into a value that can be compared, and the
+   * order defines how those values should be sorted.
+   *
+   * @example
+   * import { Array, Order } from "effect"
+   *
+   * const strings = ["aaa", "b", "cc"]
+   * const result = Array.sortWith(strings, (s) => s.length, Order.number)
+   * assert.deepStrictEqual(result, ["b", "cc", "aaa"])
+   *
+   * // Explanation:
+   * // The array of strings is sorted based on their lengths. The mapping function `(s) => s.length`
+   * // converts each string into its length, and the `Order.number` specifies that the lengths should
+   * // be sorted in ascending order.
+   *
+   * @since 2.0.0
+   * @category elements
+   */
   <A, B>(self: Iterable<A>, f: (a: A) => B, order: Order.Order<B>): Array<A>
 } = dual(
   3,
@@ -1323,9 +2431,73 @@ export const sortBy = <S extends Iterable<any> | NonEmptyReadonlyArray<any>>(
  * @since 2.0.0
  */
 export const zip: {
+  /**
+   * Takes two `Iterable`s and returns an `Array` of corresponding pairs.
+   * If one input `Iterable` is short, excess elements of the
+   * longer `Iterable` are discarded.
+   *
+   * @example
+   * import { Array } from "effect"
+   *
+   * const array1 = [1, 2, 3]
+   * const array2 = ['a', 'b']
+   * const result = Array.zip(array1, array2)
+   * assert.deepStrictEqual(result, [[1, 'a'], [2, 'b']])
+   *
+   * @category zipping
+   * @since 2.0.0
+   */
   <B>(that: NonEmptyReadonlyArray<B>): <A>(self: NonEmptyReadonlyArray<A>) => NonEmptyArray<[A, B]>
+  /**
+   * Takes two `Iterable`s and returns an `Array` of corresponding pairs.
+   * If one input `Iterable` is short, excess elements of the
+   * longer `Iterable` are discarded.
+   *
+   * @example
+   * import { Array } from "effect"
+   *
+   * const array1 = [1, 2, 3]
+   * const array2 = ['a', 'b']
+   * const result = Array.zip(array1, array2)
+   * assert.deepStrictEqual(result, [[1, 'a'], [2, 'b']])
+   *
+   * @category zipping
+   * @since 2.0.0
+   */
   <B>(that: Iterable<B>): <A>(self: Iterable<A>) => Array<[A, B]>
+  /**
+   * Takes two `Iterable`s and returns an `Array` of corresponding pairs.
+   * If one input `Iterable` is short, excess elements of the
+   * longer `Iterable` are discarded.
+   *
+   * @example
+   * import { Array } from "effect"
+   *
+   * const array1 = [1, 2, 3]
+   * const array2 = ['a', 'b']
+   * const result = Array.zip(array1, array2)
+   * assert.deepStrictEqual(result, [[1, 'a'], [2, 'b']])
+   *
+   * @category zipping
+   * @since 2.0.0
+   */
   <A, B>(self: NonEmptyReadonlyArray<A>, that: NonEmptyReadonlyArray<B>): NonEmptyArray<[A, B]>
+  /**
+   * Takes two `Iterable`s and returns an `Array` of corresponding pairs.
+   * If one input `Iterable` is short, excess elements of the
+   * longer `Iterable` are discarded.
+   *
+   * @example
+   * import { Array } from "effect"
+   *
+   * const array1 = [1, 2, 3]
+   * const array2 = ['a', 'b']
+   * const result = Array.zip(array1, array2)
+   * assert.deepStrictEqual(result, [[1, 'a'], [2, 'b']])
+   *
+   * @category zipping
+   * @since 2.0.0
+   */
   <A, B>(self: Iterable<A>, that: Iterable<B>): Array<[A, B]>
 } = dual(
   2,
@@ -1348,9 +2520,73 @@ export const zip: {
  * @since 2.0.0
  */
 export const zipWith: {
+  /**
+   * Apply a function to pairs of elements at the same index in two `Iterable`s, collecting the results in a new `Array`. If one
+   * input `Iterable` is short, excess elements of the longer `Iterable` are discarded.
+   *
+   * @example
+   * import { Array } from "effect"
+   *
+   * const array1 = [1, 2, 3]
+   * const array2 = [4, 5, 6]
+   * const result = Array.zipWith(array1, array2, (a, b) => a + b)
+   * assert.deepStrictEqual(result, [5, 7, 9])
+   *
+   * @category zipping
+   * @since 2.0.0
+   */
   <B, A, C>(that: NonEmptyReadonlyArray<B>, f: (a: A, b: B) => C): (self: NonEmptyReadonlyArray<A>) => NonEmptyArray<C>
+  /**
+   * Apply a function to pairs of elements at the same index in two `Iterable`s, collecting the results in a new `Array`. If one
+   * input `Iterable` is short, excess elements of the longer `Iterable` are discarded.
+   *
+   * @example
+   * import { Array } from "effect"
+   *
+   * const array1 = [1, 2, 3]
+   * const array2 = [4, 5, 6]
+   * const result = Array.zipWith(array1, array2, (a, b) => a + b)
+   * assert.deepStrictEqual(result, [5, 7, 9])
+   *
+   * @category zipping
+   * @since 2.0.0
+   */
   <B, A, C>(that: Iterable<B>, f: (a: A, b: B) => C): (self: Iterable<A>) => Array<C>
-  <A, B, C>(self: NonEmptyReadonlyArray<A>, that: NonEmptyReadonlyArray<B>, f: (a: A, b: B) => C): NonEmptyArray<C>
+  /**
+   * Apply a function to pairs of elements at the same index in two `Iterable`s, collecting the results in a new `Array`. If one
+   * input `Iterable` is short, excess elements of the longer `Iterable` are discarded.
+   *
+   * @example
+   * import { Array } from "effect"
+   *
+   * const array1 = [1, 2, 3]
+   * const array2 = [4, 5, 6]
+   * const result = Array.zipWith(array1, array2, (a, b) => a + b)
+   * assert.deepStrictEqual(result, [5, 7, 9])
+   *
+   * @category zipping
+   * @since 2.0.0
+   */
+  <A, B, C>(
+    self: NonEmptyReadonlyArray<A>,
+    that: NonEmptyReadonlyArray<B>,
+    f: (a: A, b: B) => C
+  ): NonEmptyArray<C>
+  /**
+   * Apply a function to pairs of elements at the same index in two `Iterable`s, collecting the results in a new `Array`. If one
+   * input `Iterable` is short, excess elements of the longer `Iterable` are discarded.
+   *
+   * @example
+   * import { Array } from "effect"
+   *
+   * const array1 = [1, 2, 3]
+   * const array2 = [4, 5, 6]
+   * const result = Array.zipWith(array1, array2, (a, b) => a + b)
+   * assert.deepStrictEqual(result, [5, 7, 9])
+   *
+   * @category zipping
+   * @since 2.0.0
+   */
   <B, A, C>(self: Iterable<A>, that: Iterable<B>, f: (a: A, b: B) => C): Array<C>
 } = dual(3, <B, A, C>(self: Iterable<A>, that: Iterable<B>, f: (a: A, b: B) => C): Array<C> => {
   const as = fromIterable(self)
@@ -1409,10 +2645,47 @@ export const unzip: <S extends Iterable<readonly [any, any]> | NonEmptyReadonlyA
  * @since 2.0.0
  */
 export const intersperse: {
-  <B>(
-    middle: B
-  ): <S extends Iterable<any>>(self: S) => ReadonlyArray.With<S, ReadonlyArray.Infer<S> | B>
+  /**
+   * 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
+   * import { Array } from "effect"
+   *
+   * const numbers = [1, 2, 3]
+   * const result = Array.intersperse(numbers, 0)
+   * assert.deepStrictEqual(result, [1, 0, 2, 0, 3])
+   *
+   * @since 2.0.0
+   */
+  <B>(middle: B): <S extends Iterable<any>>(self: S) => ReadonlyArray.With<S, ReadonlyArray.Infer<S> | B>
+  /**
+   * 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
+   * import { Array } from "effect"
+   *
+   * const numbers = [1, 2, 3]
+   * const result = Array.intersperse(numbers, 0)
+   * assert.deepStrictEqual(result, [1, 0, 2, 0, 3])
+   *
+   * @since 2.0.0
+   */
   <A, B>(self: NonEmptyReadonlyArray<A>, middle: B): NonEmptyArray<A | B>
+  /**
+   * 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
+   * import { Array } from "effect"
+   *
+   * const numbers = [1, 2, 3]
+   * const result = Array.intersperse(numbers, 0)
+   * assert.deepStrictEqual(result, [1, 0, 2, 0, 3])
+   *
+   * @since 2.0.0
+   */
   <A, B>(self: Iterable<A>, middle: B): Array<A | B>
 } = dual(2, <A, B>(self: Iterable<A>, middle: B): Array<A | B> => {
   const input = fromIterable(self)
@@ -1442,7 +2715,29 @@ export const intersperse: {
  * @since 2.0.0
  */
 export const modifyNonEmptyHead: {
+  /**
+   * Apply a function to the head, creating a new `NonEmptyReadonlyArray`.
+   *
+   * @example
+   * import { Array } from "effect"
+   *
+   * const result = Array.modifyNonEmptyHead([1, 2, 3], n => n * 10)
+   * assert.deepStrictEqual(result, [10, 2, 3])
+   *
+   * @since 2.0.0
+   */
   <A, B>(f: (a: A) => B): (self: NonEmptyReadonlyArray<A>) => NonEmptyArray<A | B>
+  /**
+   * Apply a function to the head, creating a new `NonEmptyReadonlyArray`.
+   *
+   * @example
+   * import { Array } from "effect"
+   *
+   * const result = Array.modifyNonEmptyHead([1, 2, 3], n => n * 10)
+   * assert.deepStrictEqual(result, [10, 2, 3])
+   *
+   * @since 2.0.0
+   */
   <A, B>(self: NonEmptyReadonlyArray<A>, f: (a: A) => B): NonEmptyArray<A | B>
 } = dual(
   2,
@@ -1464,7 +2759,29 @@ export const modifyNonEmptyHead: {
  * @since 2.0.0
  */
 export const setNonEmptyHead: {
+  /**
+   * Change the head, creating a new `NonEmptyReadonlyArray`.
+   *
+   * @example
+   * import { Array } from "effect"
+   *
+   * const result = Array.setNonEmptyHead([1, 2, 3], 10)
+   * assert.deepStrictEqual(result, [10, 2, 3])
+   *
+   * @since 2.0.0
+   */
   <B>(b: B): <A>(self: NonEmptyReadonlyArray<A>) => NonEmptyArray<A | B>
+  /**
+   * Change the head, creating a new `NonEmptyReadonlyArray`.
+   *
+   * @example
+   * import { Array } from "effect"
+   *
+   * const result = Array.setNonEmptyHead([1, 2, 3], 10)
+   * assert.deepStrictEqual(result, [10, 2, 3])
+   *
+   * @since 2.0.0
+   */
   <A, B>(self: NonEmptyReadonlyArray<A>, b: B): NonEmptyArray<A | B>
 } = dual(
   2,
@@ -1483,7 +2800,29 @@ export const setNonEmptyHead: {
  * @since 2.0.0
  */
 export const modifyNonEmptyLast: {
+  /**
+   * Apply a function to the last element, creating a new `NonEmptyReadonlyArray`.
+   *
+   * @example
+   * import { Array } from "effect"
+   *
+   * const result = Array.modifyNonEmptyLast([1, 2, 3], n => n * 2)
+   * assert.deepStrictEqual(result, [1, 2, 6])
+   *
+   * @since 2.0.0
+   */
   <A, B>(f: (a: A) => B): (self: NonEmptyReadonlyArray<A>) => NonEmptyArray<A | B>
+  /**
+   * Apply a function to the last element, creating a new `NonEmptyReadonlyArray`.
+   *
+   * @example
+   * import { Array } from "effect"
+   *
+   * const result = Array.modifyNonEmptyLast([1, 2, 3], n => n * 2)
+   * assert.deepStrictEqual(result, [1, 2, 6])
+   *
+   * @since 2.0.0
+   */
   <A, B>(self: NonEmptyReadonlyArray<A>, f: (a: A) => B): NonEmptyArray<A | B>
 } = dual(
   2,
@@ -1503,7 +2842,29 @@ export const modifyNonEmptyLast: {
  * @since 2.0.0
  */
 export const setNonEmptyLast: {
+  /**
+   * Change the last element, creating a new `NonEmptyReadonlyArray`.
+   *
+   * @example
+   * import { Array } from "effect"
+   *
+   * const result = Array.setNonEmptyLast([1, 2, 3], 4)
+   * assert.deepStrictEqual(result, [1, 2, 4])
+   *
+   * @since 2.0.0
+   */
   <B>(b: B): <A>(self: NonEmptyReadonlyArray<A>) => NonEmptyArray<A | B>
+  /**
+   * Change the last element, creating a new `NonEmptyReadonlyArray`.
+   *
+   * @example
+   * import { Array } from "effect"
+   *
+   * const result = Array.setNonEmptyLast([1, 2, 3], 4)
+   * assert.deepStrictEqual(result, [1, 2, 4])
+   *
+   * @since 2.0.0
+   */
   <A, B>(self: NonEmptyReadonlyArray<A>, b: B): NonEmptyArray<A | B>
 } = dual(
   2,
@@ -1524,8 +2885,47 @@ export const setNonEmptyLast: {
  * @since 2.0.0
  */
 export const rotate: {
+  /**
+   * Rotate an `Iterable` by `n` steps.
+   * If the input is a non-empty array, the result is also a non-empty array.
+   *
+   * @example
+   * import { Array } from "effect"
+   *
+   * const letters = ['a', 'b', 'c', 'd']
+   * const result = Array.rotate(letters, 2)
+   * assert.deepStrictEqual(result, ['c', 'd', 'a', 'b'])
+   *
+   * @since 2.0.0
+   */
   (n: number): <S extends Iterable<any>>(self: S) => ReadonlyArray.With<S, ReadonlyArray.Infer<S>>
+  /**
+   * Rotate an `Iterable` by `n` steps.
+   * If the input is a non-empty array, the result is also a non-empty array.
+   *
+   * @example
+   * import { Array } from "effect"
+   *
+   * const letters = ['a', 'b', 'c', 'd']
+   * const result = Array.rotate(letters, 2)
+   * assert.deepStrictEqual(result, ['c', 'd', 'a', 'b'])
+   *
+   * @since 2.0.0
+   */
   <A>(self: NonEmptyReadonlyArray<A>, n: number): NonEmptyArray<A>
+  /**
+   * Rotate an `Iterable` by `n` steps.
+   * If the input is a non-empty array, the result is also a non-empty array.
+   *
+   * @example
+   * import { Array } from "effect"
+   *
+   * const letters = ['a', 'b', 'c', 'd']
+   * const result = Array.rotate(letters, 2)
+   * assert.deepStrictEqual(result, ['c', 'd', 'a', 'b'])
+   *
+   * @since 2.0.0
+   */
   <A>(self: Iterable<A>, n: number): Array<A>
 } = dual(2, <A>(self: Iterable<A>, n: number): Array<A> => {
   const input = fromIterable(self)
@@ -1589,7 +2989,33 @@ const _equivalence = Equal.equivalence()
  * @since 2.0.0
  */
 export const contains: {
+  /**
+   * Returns a function that checks if a `ReadonlyArray` contains a given value using the default `Equivalence`.
+   *
+   * @example
+   * import { Array } from "effect"
+   *
+   * const letters = ['a', 'b', 'c', 'd']
+   * const result = Array.contains('c')(letters)
+   * assert.deepStrictEqual(result, true)
+   *
+   * @category elements
+   * @since 2.0.0
+   */
   <A>(a: A): (self: Iterable<A>) => boolean
+  /**
+   * Returns a function that checks if a `ReadonlyArray` contains a given value using the default `Equivalence`.
+   *
+   * @example
+   * import { Array } from "effect"
+   *
+   * const letters = ['a', 'b', 'c', 'd']
+   * const result = Array.contains('c')(letters)
+   * assert.deepStrictEqual(result, true)
+   *
+   * @category elements
+   * @since 2.0.0
+   */
   <A>(self: Iterable<A>, a: A): boolean
 } = containsWith(_equivalence)
 
@@ -1613,13 +3039,70 @@ export const contains: {
  * @since 2.0.0
  */
 export const chop: {
+  /**
+   * A useful recursion pattern for processing an `Iterable` to produce a new `Array`, often used for "chopping" up the input
+   * `Iterable`. Typically chop is called with some function that will consume an initial prefix of the `Iterable` and produce a
+   * value and the rest of the `Array`.
+   *
+   * @example
+   * import { Array } from "effect"
+   *
+   * const numbers = [1, 2, 3, 4, 5]
+   * const result = Array.chop(numbers, (as): [number, Array<number>] => [as[0] * 2, as.slice(1)])
+   * assert.deepStrictEqual(result, [2, 4, 6, 8, 10])
+   *
+   * // Explanation:
+   * // The `chopFunction` takes the first element of the array, doubles it, and then returns it along with the rest of the array.
+   * // The `chop` function applies this `chopFunction` recursively to the input array `[1, 2, 3, 4, 5]`,
+   * // resulting in a new array `[2, 4, 6, 8, 10]`.
+   *
+   * @since 2.0.0
+   */
   <S extends Iterable<any>, B>(
     f: (as: NonEmptyReadonlyArray<ReadonlyArray.Infer<S>>) => readonly [B, ReadonlyArray<ReadonlyArray.Infer<S>>]
   ): (self: S) => ReadonlyArray.With<S, ReadonlyArray.Infer<S>>
+  /**
+   * A useful recursion pattern for processing an `Iterable` to produce a new `Array`, often used for "chopping" up the input
+   * `Iterable`. Typically chop is called with some function that will consume an initial prefix of the `Iterable` and produce a
+   * value and the rest of the `Array`.
+   *
+   * @example
+   * import { Array } from "effect"
+   *
+   * const numbers = [1, 2, 3, 4, 5]
+   * const result = Array.chop(numbers, (as): [number, Array<number>] => [as[0] * 2, as.slice(1)])
+   * assert.deepStrictEqual(result, [2, 4, 6, 8, 10])
+   *
+   * // Explanation:
+   * // The `chopFunction` takes the first element of the array, doubles it, and then returns it along with the rest of the array.
+   * // The `chop` function applies this `chopFunction` recursively to the input array `[1, 2, 3, 4, 5]`,
+   * // resulting in a new array `[2, 4, 6, 8, 10]`.
+   *
+   * @since 2.0.0
+   */
   <A, B>(
     self: NonEmptyReadonlyArray<A>,
     f: (as: NonEmptyReadonlyArray<A>) => readonly [B, ReadonlyArray<A>]
   ): NonEmptyArray<B>
+  /**
+   * A useful recursion pattern for processing an `Iterable` to produce a new `Array`, often used for "chopping" up the input
+   * `Iterable`. Typically chop is called with some function that will consume an initial prefix of the `Iterable` and produce a
+   * value and the rest of the `Array`.
+   *
+   * @example
+   * import { Array } from "effect"
+   *
+   * const numbers = [1, 2, 3, 4, 5]
+   * const result = Array.chop(numbers, (as): [number, Array<number>] => [as[0] * 2, as.slice(1)])
+   * assert.deepStrictEqual(result, [2, 4, 6, 8, 10])
+   *
+   * // Explanation:
+   * // The `chopFunction` takes the first element of the array, doubles it, and then returns it along with the rest of the array.
+   * // The `chop` function applies this `chopFunction` recursively to the input array `[1, 2, 3, 4, 5]`,
+   * // resulting in a new array `[2, 4, 6, 8, 10]`.
+   *
+   * @since 2.0.0
+   */
   <A, B>(
     self: Iterable<A>,
     f: (as: NonEmptyReadonlyArray<A>) => readonly [B, ReadonlyArray<A>]
@@ -1658,12 +3141,40 @@ export const chop: {
  * @since 2.0.0
  */
 export const splitAt: {
-  (n: number): <A>(self: Iterable<A>) => [beforeIndex: Array<A>, fromIndex: Array<A>]
-  <A>(self: Iterable<A>, n: number): [beforeIndex: Array<A>, fromIndex: Array<A>]
-} = dual(2, <A>(self: Iterable<A>, n: number): [Array<A>, Array<A>] => {
-  const input = Array.from(self)
-  const _n = Math.floor(n)
-  if (isNonEmptyReadonlyArray(input)) {
+  /**
+   * Splits an `Iterable` into two segments, with the first segment containing a maximum of `n` elements.
+   * The value of `n` can be `0`.
+   *
+   * @example
+   * import { Array } from "effect"
+   *
+   * const numbers = [1, 2, 3, 4, 5]
+   * const result = Array.splitAt(numbers, 3)
+   * assert.deepStrictEqual(result, [[1, 2, 3], [4, 5]])
+   *
+   * @category splitting
+   * @since 2.0.0
+   */
+  (n: number): <A>(self: Iterable<A>) => [beforeIndex: Array<A>, fromIndex: Array<A>]
+  /**
+   * Splits an `Iterable` into two segments, with the first segment containing a maximum of `n` elements.
+   * The value of `n` can be `0`.
+   *
+   * @example
+   * import { Array } from "effect"
+   *
+   * const numbers = [1, 2, 3, 4, 5]
+   * const result = Array.splitAt(numbers, 3)
+   * assert.deepStrictEqual(result, [[1, 2, 3], [4, 5]])
+   *
+   * @category splitting
+   * @since 2.0.0
+   */
+  <A>(self: Iterable<A>, n: number): [beforeIndex: Array<A>, fromIndex: Array<A>]
+} = dual(2, <A>(self: Iterable<A>, n: number): [Array<A>, Array<A>] => {
+  const input = Array.from(self)
+  const _n = Math.floor(n)
+  if (isNonEmptyReadonlyArray(input)) {
     if (_n >= 1) {
       return splitNonEmptyAt(input, _n)
     }
@@ -1686,7 +3197,33 @@ export const splitAt: {
  * @since 2.0.0
  */
 export const splitNonEmptyAt: {
+  /**
+   * Splits a `NonEmptyReadonlyArray` into two segments, with the first segment containing a maximum of `n` elements.
+   * The value of `n` must be `>= 1`.
+   *
+   * @example
+   * import { Array } from "effect"
+   *
+   * const result = Array.splitNonEmptyAt(["a", "b", "c", "d", "e"], 3)
+   * assert.deepStrictEqual(result, [["a", "b", "c"], ["d", "e"]])
+   *
+   * @category splitting
+   * @since 2.0.0
+   */
   (n: number): <A>(self: NonEmptyReadonlyArray<A>) => [beforeIndex: NonEmptyArray<A>, fromIndex: Array<A>]
+  /**
+   * Splits a `NonEmptyReadonlyArray` into two segments, with the first segment containing a maximum of `n` elements.
+   * The value of `n` must be `>= 1`.
+   *
+   * @example
+   * import { Array } from "effect"
+   *
+   * const result = Array.splitNonEmptyAt(["a", "b", "c", "d", "e"], 3)
+   * assert.deepStrictEqual(result, [["a", "b", "c"], ["d", "e"]])
+   *
+   * @category splitting
+   * @since 2.0.0
+   */
   <A>(self: NonEmptyReadonlyArray<A>, n: number): [beforeIndex: NonEmptyArray<A>, fromIndex: Array<A>]
 } = dual(2, <A>(self: NonEmptyReadonlyArray<A>, n: number): [NonEmptyArray<A>, Array<A>] => {
   const _n = Math.max(1, Math.floor(n))
@@ -1709,7 +3246,33 @@ export const splitNonEmptyAt: {
  * @category splitting
  */
 export const split: {
+  /**
+   * Splits this iterable into `n` equally sized arrays.
+   *
+   * @example
+   * import { Array } from "effect"
+   *
+   * const numbers = [1, 2, 3, 4, 5, 6, 7, 8]
+   * const result = Array.split(numbers, 3)
+   * assert.deepStrictEqual(result, [[1, 2, 3], [4, 5, 6], [7, 8]])
+   *
+   * @since 2.0.0
+   * @category splitting
+   */
   (n: number): <A>(self: Iterable<A>) => Array<Array<A>>
+  /**
+   * Splits this iterable into `n` equally sized arrays.
+   *
+   * @example
+   * import { Array } from "effect"
+   *
+   * const numbers = [1, 2, 3, 4, 5, 6, 7, 8]
+   * const result = Array.split(numbers, 3)
+   * assert.deepStrictEqual(result, [[1, 2, 3], [4, 5, 6], [7, 8]])
+   *
+   * @since 2.0.0
+   * @category splitting
+   */
   <A>(self: Iterable<A>, n: number): Array<Array<A>>
 } = dual(2, <A>(self: Iterable<A>, n: number) => {
   const input = fromIterable(self)
@@ -1731,9 +3294,37 @@ export const split: {
  * @since 2.0.0
  */
 export const splitWhere: {
+  /**
+   * Splits this iterable on the first element that matches this predicate.
+   * Returns a tuple containing two arrays: the first one is before the match, and the second one is from the match onward.
+   *
+   * @example
+   * import { Array } from "effect"
+   *
+   * const numbers = [1, 2, 3, 4, 5]
+   * const result = Array.splitWhere(numbers, n => n > 3)
+   * assert.deepStrictEqual(result, [[1, 2, 3], [4, 5]])
+   *
+   * @category splitting
+   * @since 2.0.0
+   */
   <A>(
     predicate: (a: NoInfer<A>, i: number) => boolean
   ): (self: Iterable<A>) => [beforeMatch: Array<A>, fromMatch: Array<A>]
+  /**
+   * Splits this iterable on the first element that matches this predicate.
+   * Returns a tuple containing two arrays: the first one is before the match, and the second one is from the match onward.
+   *
+   * @example
+   * import { Array } from "effect"
+   *
+   * const numbers = [1, 2, 3, 4, 5]
+   * const result = Array.splitWhere(numbers, n => n > 3)
+   * assert.deepStrictEqual(result, [[1, 2, 3], [4, 5]])
+   *
+   * @category splitting
+   * @since 2.0.0
+   */
   <A>(self: Iterable<A>, predicate: (a: A, i: number) => boolean): [beforeMatch: Array<A>, fromMatch: Array<A>]
 } = dual(
   2,
@@ -1754,10 +3345,94 @@ export const splitWhere: {
  * @since 2.0.0
  */
 export const copy: {
+  /**
+   * Copies an array.
+   *
+   * @example
+   * import { Array } from "effect"
+   *
+   * const numbers = [1, 2, 3]
+   * const copy = Array.copy(numbers)
+   * assert.deepStrictEqual(copy, [1, 2, 3])
+   *
+   * @since 2.0.0
+   */
   <A>(self: NonEmptyReadonlyArray<A>): NonEmptyArray<A>
+  /**
+   * Copies an array.
+   *
+   * @example
+   * import { Array } from "effect"
+   *
+   * const numbers = [1, 2, 3]
+   * const copy = Array.copy(numbers)
+   * assert.deepStrictEqual(copy, [1, 2, 3])
+   *
+   * @since 2.0.0
+   */
   <A>(self: ReadonlyArray<A>): Array<A>
 } = (<A>(self: ReadonlyArray<A>): Array<A> => self.slice()) as any
 
+/**
+ * Pads an array.
+ * Returns a new array of length `n` with the elements of `array` followed by `fill` elements if `array` is shorter than `n`.
+ * If `array` is longer than `n`, the returned array will be a slice of `array` containing the `n` first elements of `array`.
+ * If `n` is less than or equal to 0, the returned array will be an empty array.
+ *
+ * @example
+ * import { Array } from "effect"
+ *
+ * const arr = [1, 2, 3]
+ * const result = Array.pad(arr, 6, 0)
+ * assert.deepStrictEqual(result, [1, 2, 3, 0, 0, 0])
+ *
+ * @since 3.8.4
+ */
+export const pad: {
+  /**
+   * Pads an array.
+   * Returns a new array of length `n` with the elements of `array` followed by `fill` elements if `array` is shorter than `n`.
+   * If `array` is longer than `n`, the returned array will be a slice of `array` containing the `n` first elements of `array`.
+   * If `n` is less than or equal to 0, the returned array will be an empty array.
+   *
+   * @example
+   * import { Array } from "effect"
+   *
+   * const arr = [1, 2, 3]
+   * const result = Array.pad(arr, 6, 0)
+   * assert.deepStrictEqual(result, [1, 2, 3, 0, 0, 0])
+   *
+   * @since 3.8.4
+   */
+  <A, T>(n: number, fill: T): (
+    self: Array<A>
+  ) => Array<A | T>
+  /**
+   * Pads an array.
+   * Returns a new array of length `n` with the elements of `array` followed by `fill` elements if `array` is shorter than `n`.
+   * If `array` is longer than `n`, the returned array will be a slice of `array` containing the `n` first elements of `array`.
+   * If `n` is less than or equal to 0, the returned array will be an empty array.
+   *
+   * @example
+   * import { Array } from "effect"
+   *
+   * const arr = [1, 2, 3]
+   * const result = Array.pad(arr, 6, 0)
+   * assert.deepStrictEqual(result, [1, 2, 3, 0, 0, 0])
+   *
+   * @since 3.8.4
+   */
+  <A, T>(self: Array<A>, n: number, fill: T): Array<A | T>
+} = dual(3, <A, T>(self: Array<A>, n: number, fill: T): Array<A | T> => {
+  if (self.length >= n) {
+    return take(self, n)
+  }
+  return appendAll(
+    self,
+    makeBy(n - self.length, () => fill)
+  )
+})
+
 /**
  * Splits an `Iterable` into length-`n` pieces. The last piece will be shorter if `n` does not evenly divide the length of
  * the `Iterable`. Note that `chunksOf(n)([])` is `[]`, not `[[]]`. This is intentional, and is consistent with a recursive
@@ -1786,12 +3461,91 @@ export const copy: {
  * @since 2.0.0
  */
 export const chunksOf: {
-  (
-    n: number
-  ): <S extends Iterable<any>>(
+  /**
+   * Splits an `Iterable` into length-`n` pieces. The last piece will be shorter if `n` does not evenly divide the length of
+   * the `Iterable`. Note that `chunksOf(n)([])` is `[]`, not `[[]]`. This is intentional, and is consistent with a recursive
+   * definition of `chunksOf`; it satisfies the property that
+   *
+   * ```ts
+   * chunksOf(n)(xs).concat(chunksOf(n)(ys)) == chunksOf(n)(xs.concat(ys)))
+   * ```
+   *
+   * whenever `n` evenly divides the length of `self`.
+   *
+   * @example
+   * import { Array } from "effect"
+   *
+   * const numbers = [1, 2, 3, 4, 5]
+   * const result = Array.chunksOf(numbers, 2)
+   * assert.deepStrictEqual(result, [[1, 2], [3, 4], [5]])
+   *
+   * // Explanation:
+   * // The `chunksOf` function takes an array of numbers `[1, 2, 3, 4, 5]` and a number `2`.
+   * // It splits the array into chunks of length 2. Since the array length is not evenly divisible by 2,
+   * // the last chunk contains the remaining elements.
+   * // The result is `[[1, 2], [3, 4], [5]]`.
+   *
+   * @category splitting
+   * @since 2.0.0
+   */
+  (n: number): <S extends Iterable<any>>(
     self: S
   ) => ReadonlyArray.With<S, NonEmptyArray<ReadonlyArray.Infer<S>>>
+  /**
+   * Splits an `Iterable` into length-`n` pieces. The last piece will be shorter if `n` does not evenly divide the length of
+   * the `Iterable`. Note that `chunksOf(n)([])` is `[]`, not `[[]]`. This is intentional, and is consistent with a recursive
+   * definition of `chunksOf`; it satisfies the property that
+   *
+   * ```ts
+   * chunksOf(n)(xs).concat(chunksOf(n)(ys)) == chunksOf(n)(xs.concat(ys)))
+   * ```
+   *
+   * whenever `n` evenly divides the length of `self`.
+   *
+   * @example
+   * import { Array } from "effect"
+   *
+   * const numbers = [1, 2, 3, 4, 5]
+   * const result = Array.chunksOf(numbers, 2)
+   * assert.deepStrictEqual(result, [[1, 2], [3, 4], [5]])
+   *
+   * // Explanation:
+   * // The `chunksOf` function takes an array of numbers `[1, 2, 3, 4, 5]` and a number `2`.
+   * // It splits the array into chunks of length 2. Since the array length is not evenly divisible by 2,
+   * // the last chunk contains the remaining elements.
+   * // The result is `[[1, 2], [3, 4], [5]]`.
+   *
+   * @category splitting
+   * @since 2.0.0
+   */
   <A>(self: NonEmptyReadonlyArray<A>, n: number): NonEmptyArray<NonEmptyArray<A>>
+  /**
+   * Splits an `Iterable` into length-`n` pieces. The last piece will be shorter if `n` does not evenly divide the length of
+   * the `Iterable`. Note that `chunksOf(n)([])` is `[]`, not `[[]]`. This is intentional, and is consistent with a recursive
+   * definition of `chunksOf`; it satisfies the property that
+   *
+   * ```ts
+   * chunksOf(n)(xs).concat(chunksOf(n)(ys)) == chunksOf(n)(xs.concat(ys)))
+   * ```
+   *
+   * whenever `n` evenly divides the length of `self`.
+   *
+   * @example
+   * import { Array } from "effect"
+   *
+   * const numbers = [1, 2, 3, 4, 5]
+   * const result = Array.chunksOf(numbers, 2)
+   * assert.deepStrictEqual(result, [[1, 2], [3, 4], [5]])
+   *
+   * // Explanation:
+   * // The `chunksOf` function takes an array of numbers `[1, 2, 3, 4, 5]` and a number `2`.
+   * // It splits the array into chunks of length 2. Since the array length is not evenly divisible by 2,
+   * // the last chunk contains the remaining elements.
+   * // The result is `[[1, 2], [3, 4], [5]]`.
+   *
+   * @category splitting
+   * @since 2.0.0
+   */
   <A>(self: Iterable<A>, n: number): Array<NonEmptyArray<A>>
 } = dual(2, <A>(self: Iterable<A>, n: number): Array<NonEmptyArray<A>> => {
   const input = fromIterable(self)
@@ -1814,8 +3568,35 @@ export const chunksOf: {
  * @since 2.0.0
  */
 export const groupWith: {
+  /**
+   * Group equal, consecutive elements of a `NonEmptyReadonlyArray` into `NonEmptyArray`s using the provided `isEquivalent` function.
+   *
+   * @example
+   * import { Array } from "effect"
+   *
+   * const result = Array.groupWith(["a", "a", "b", "b", "b", "c", "a"], (x, y) => x === y)
+   * assert.deepStrictEqual(result, [["a", "a"], ["b", "b", "b"], ["c"], ["a"]])
+   *
+   * @category grouping
+   * @since 2.0.0
+   */
   <A>(isEquivalent: (self: A, that: A) => boolean): (self: NonEmptyReadonlyArray<A>) => NonEmptyArray<NonEmptyArray<A>>
-  <A>(self: NonEmptyReadonlyArray<A>, isEquivalent: (self: A, that: A) => boolean): NonEmptyArray<NonEmptyArray<A>>
+  /**
+   * Group equal, consecutive elements of a `NonEmptyReadonlyArray` into `NonEmptyArray`s using the provided `isEquivalent` function.
+   *
+   * @example
+   * import { Array } from "effect"
+   *
+   * const result = Array.groupWith(["a", "a", "b", "b", "b", "c", "a"], (x, y) => x === y)
+   * assert.deepStrictEqual(result, [["a", "a"], ["b", "b", "b"], ["c"], ["a"]])
+   *
+   * @category grouping
+   * @since 2.0.0
+   */
+  <A>(
+    self: NonEmptyReadonlyArray<A>,
+    isEquivalent: (self: A, that: A) => boolean
+  ): NonEmptyArray<NonEmptyArray<A>>
 } = dual(
   2,
   <A>(self: NonEmptyReadonlyArray<A>, isEquivalent: (self: A, that: A) => boolean): NonEmptyArray<NonEmptyArray<A>> =>
@@ -1873,9 +3654,51 @@ export const group: <A>(self: NonEmptyReadonlyArray<A>) => NonEmptyArray<NonEmpt
  * @since 2.0.0
  */
 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
+   *
+   * @example
+   * import { Array } from "effect"
+   *
+   * const people = [
+   *   { name: "Alice", group: "A" },
+   *   { name: "Bob", group: "B" },
+   *   { name: "Charlie", group: "A" }
+   * ]
+   * const result = Array.groupBy(people, person => person.group)
+   * assert.deepStrictEqual(result, {
+   *   A: [{ name: "Alice", group: "A" }, { name: "Charlie", group: "A" }],
+   *   B: [{ name: "Bob", group: "B" }]
+   * })
+   *
+   * @category grouping
+   * @since 2.0.0
+   */
   <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
+   *
+   * @example
+   * import { Array } from "effect"
+   *
+   * const people = [
+   *   { name: "Alice", group: "A" },
+   *   { name: "Bob", group: "B" },
+   *   { name: "Charlie", group: "A" }
+   * ]
+   * const result = Array.groupBy(people, person => person.group)
+   * assert.deepStrictEqual(result, {
+   *   A: [{ name: "Alice", group: "A" }, { name: "Charlie", group: "A" }],
+   *   B: [{ name: "Bob", group: "B" }]
+   * })
+   *
+   * @category grouping
+   * @since 2.0.0
+   */
   <A, K extends string | symbol>(
     self: Iterable<A>,
     f: (a: A) => K
@@ -1910,21 +3733,77 @@ export const groupBy: {
  * @since 2.0.0
  */
 export const unionWith: {
+  /**
+   * Calculates the union of two arrays using the provided equivalence relation.
+   *
+   * @example
+   * import { Array } from "effect"
+   *
+   * const array1 = [1, 2]
+   * const array2 = [2, 3]
+   * const union = Array.unionWith(array1, array2, (a, b) => a === b)
+   * assert.deepStrictEqual(union, [1, 2, 3])
+   *
+   * @since 2.0.0
+   */
   <S extends Iterable<any>, T extends Iterable<any>>(
     that: T,
     isEquivalent: (self: ReadonlyArray.Infer<S>, that: ReadonlyArray.Infer<T>) => boolean
   ): (self: S) => ReadonlyArray.OrNonEmpty<S, T, ReadonlyArray.Infer<S> | ReadonlyArray.Infer<T>>
+  /**
+   * Calculates the union of two arrays using the provided equivalence relation.
+   *
+   * @example
+   * import { Array } from "effect"
+   *
+   * const array1 = [1, 2]
+   * const array2 = [2, 3]
+   * const union = Array.unionWith(array1, array2, (a, b) => a === b)
+   * assert.deepStrictEqual(union, [1, 2, 3])
+   *
+   * @since 2.0.0
+   */
   <A, B>(
     self: NonEmptyReadonlyArray<A>,
     that: Iterable<B>,
     isEquivalent: (self: A, that: B) => boolean
   ): NonEmptyArray<A | B>
+  /**
+   * Calculates the union of two arrays using the provided equivalence relation.
+   *
+   * @example
+   * import { Array } from "effect"
+   *
+   * const array1 = [1, 2]
+   * const array2 = [2, 3]
+   * const union = Array.unionWith(array1, array2, (a, b) => a === b)
+   * assert.deepStrictEqual(union, [1, 2, 3])
+   *
+   * @since 2.0.0
+   */
   <A, B>(
     self: Iterable<A>,
     that: NonEmptyReadonlyArray<B>,
     isEquivalent: (self: A, that: B) => boolean
   ): NonEmptyArray<A | B>
-  <A, B>(self: Iterable<A>, that: Iterable<B>, isEquivalent: (self: A, that: B) => boolean): Array<A | B>
+  /**
+   * Calculates the union of two arrays using the provided equivalence relation.
+   *
+   * @example
+   * import { Array } from "effect"
+   *
+   * const array1 = [1, 2]
+   * const array2 = [2, 3]
+   * const union = Array.unionWith(array1, array2, (a, b) => a === b)
+   * assert.deepStrictEqual(union, [1, 2, 3])
+   *
+   * @since 2.0.0
+   */
+  <A, B>(
+    self: Iterable<A>,
+    that: Iterable<B>,
+    isEquivalent: (self: A, that: B) => boolean
+  ): Array<A | B>
 } = dual(3, <A>(self: Iterable<A>, that: Iterable<A>, isEquivalent: (self: A, that: A) => boolean): Array<A> => {
   const a = fromIterable(self)
   const b = fromIterable(that)
@@ -1952,13 +3831,63 @@ export const unionWith: {
  * @since 2.0.0
  */
 export const union: {
-  <T extends Iterable<any>>(
-    that: T
-  ): <S extends Iterable<any>>(
+  /**
+   * Creates a union of two arrays, removing duplicates.
+   *
+   * @example
+   * import { Array } from "effect"
+   *
+   * const array1 = [1, 2]
+   * const array2 = [2, 3]
+   * const result = Array.union(array1, array2)
+   * assert.deepStrictEqual(result, [1, 2, 3])
+   *
+   * @since 2.0.0
+   */
+  <T extends Iterable<any>>(that: T): <S extends Iterable<any>>(
     self: S
   ) => ReadonlyArray.OrNonEmpty<S, T, ReadonlyArray.Infer<S> | ReadonlyArray.Infer<T>>
+  /**
+   * Creates a union of two arrays, removing duplicates.
+   *
+   * @example
+   * import { Array } from "effect"
+   *
+   * const array1 = [1, 2]
+   * const array2 = [2, 3]
+   * const result = Array.union(array1, array2)
+   * assert.deepStrictEqual(result, [1, 2, 3])
+   *
+   * @since 2.0.0
+   */
   <A, B>(self: NonEmptyReadonlyArray<A>, that: ReadonlyArray<B>): NonEmptyArray<A | B>
+  /**
+   * Creates a union of two arrays, removing duplicates.
+   *
+   * @example
+   * import { Array } from "effect"
+   *
+   * const array1 = [1, 2]
+   * const array2 = [2, 3]
+   * const result = Array.union(array1, array2)
+   * assert.deepStrictEqual(result, [1, 2, 3])
+   *
+   * @since 2.0.0
+   */
   <A, B>(self: ReadonlyArray<A>, that: NonEmptyReadonlyArray<B>): NonEmptyArray<A | B>
+  /**
+   * Creates a union of two arrays, removing duplicates.
+   *
+   * @example
+   * import { Array } from "effect"
+   *
+   * const array1 = [1, 2]
+   * const array2 = [2, 3]
+   * const result = Array.union(array1, array2)
+   * assert.deepStrictEqual(result, [1, 2, 3])
+   *
+   * @since 2.0.0
+   */
   <A, B>(self: Iterable<A>, that: Iterable<B>): Array<A | B>
 } = dual(2, <A, B>(self: Iterable<A>, that: Iterable<B>): Array<A | B> => unionWith(self, that, _equivalence))
 
@@ -2003,7 +3932,35 @@ export const intersectionWith = <A>(isEquivalent: (self: A, that: A) => boolean)
  * @since 2.0.0
  */
 export const intersection: {
+  /**
+   * Creates an `Array` of unique values that are included in all given `Iterable`s.
+   * The order and references of result values are determined by the first `Iterable`.
+   *
+   * @example
+   * import { Array } from "effect"
+   *
+   * const array1 = [1, 2, 3]
+   * const array2 = [3, 4, 1]
+   * const result = Array.intersection(array1, array2)
+   * assert.deepStrictEqual(result, [1, 3])
+   *
+   * @since 2.0.0
+   */
   <B>(that: Iterable<B>): <A>(self: Iterable<A>) => Array<A & B>
+  /**
+   * Creates an `Array` of unique values that are included in all given `Iterable`s.
+   * The order and references of result values are determined by the first `Iterable`.
+   *
+   * @example
+   * import { Array } from "effect"
+   *
+   * const array1 = [1, 2, 3]
+   * const array2 = [3, 4, 1]
+   * const result = Array.intersection(array1, array2)
+   * assert.deepStrictEqual(result, [1, 3])
+   *
+   * @since 2.0.0
+   */
   <A, B>(self: Iterable<A>, that: Iterable<B>): Array<A & B>
 } = intersectionWith(_equivalence)
 
@@ -2047,7 +4004,35 @@ export const differenceWith = <A>(isEquivalent: (self: A, that: A) => boolean):
  * @since 2.0.0
  */
 export const difference: {
+  /**
+   * Creates a `Array` of values not included in the other given `Iterable`.
+   * The order and references of result values are determined by the first `Iterable`.
+   *
+   * @example
+   * import { Array } from "effect"
+   *
+   * const array1 = [1, 2, 3]
+   * const array2 = [2, 3, 4]
+   * const difference = Array.difference(array1, array2)
+   * assert.deepStrictEqual(difference, [1])
+   *
+   * @since 2.0.0
+   */
   <A>(that: Iterable<A>): (self: Iterable<A>) => Array<A>
+  /**
+   * Creates a `Array` of values not included in the other given `Iterable`.
+   * The order and references of result values are determined by the first `Iterable`.
+   *
+   * @example
+   * import { Array } from "effect"
+   *
+   * const array1 = [1, 2, 3]
+   * const array2 = [2, 3, 4]
+   * const difference = Array.difference(array1, array2)
+   * assert.deepStrictEqual(difference, [1])
+   *
+   * @since 2.0.0
+   */
   <A>(self: Iterable<A>, that: Iterable<A>): Array<A>
 } = differenceWith(_equivalence)
 
@@ -2118,9 +4103,17 @@ export declare namespace ReadonlyArray {
  * @since 2.0.0
  */
 export const map: {
+  /**
+   * @category mapping
+   * @since 2.0.0
+   */
   <S extends ReadonlyArray<any>, B>(
     f: (a: ReadonlyArray.Infer<S>, i: number) => B
   ): (self: S) => ReadonlyArray.With<S, B>
+  /**
+   * @category mapping
+   * @since 2.0.0
+   */
   <S extends ReadonlyArray<any>, B>(self: S, f: (a: ReadonlyArray.Infer<S>, i: number) => B): ReadonlyArray.With<S, B>
 } = dual(2, <A, B>(self: ReadonlyArray<A>, f: (a: A, i: number) => B): Array<B> => self.map(f))
 
@@ -2131,10 +4124,31 @@ export const map: {
  * @since 2.0.0
  */
 export const flatMap: {
-  <S extends ReadonlyArray<any>, T extends ReadonlyArray<any>>(
-    f: (a: ReadonlyArray.Infer<S>, i: number) => T
+  /**
+   * Applies a function to each element in an array and returns a new array containing the concatenated mapped elements.
+   *
+   * @category sequencing
+   * @since 2.0.0
+   */
+  <S extends ReadonlyArray<any>, T extends ReadonlyArray<any>>(
+    f: (a: ReadonlyArray.Infer<S>, i: number) => T
   ): (self: S) => ReadonlyArray.AndNonEmpty<S, T, ReadonlyArray.Infer<T>>
-  <A, B>(self: NonEmptyReadonlyArray<A>, f: (a: A, i: number) => NonEmptyReadonlyArray<B>): NonEmptyArray<B>
+  /**
+   * Applies a function to each element in an array and returns a new array containing the concatenated mapped elements.
+   *
+   * @category sequencing
+   * @since 2.0.0
+   */
+  <A, B>(
+    self: NonEmptyReadonlyArray<A>,
+    f: (a: A, i: number) => NonEmptyReadonlyArray<B>
+  ): NonEmptyArray<B>
+  /**
+   * Applies a function to each element in an array and returns a new array containing the concatenated mapped elements.
+   *
+   * @category sequencing
+   * @since 2.0.0
+   */
   <A, B>(self: ReadonlyArray<A>, f: (a: A, i: number) => ReadonlyArray<B>): Array<B>
 } = dual(
   2,
@@ -2190,7 +4204,39 @@ export const flatten: <S extends ReadonlyArray<ReadonlyArray<any>>>(self: S) =>
  * @since 2.0.0
  */
 export const filterMap: {
+  /**
+   * Applies a function to each element of the `Iterable` and filters based on the result, keeping the transformed values where the function returns `Some`.
+   * This method combines filtering and mapping functionalities, allowing transformations and filtering of elements based on a single function pass.
+   *
+   * @example
+   * import { Array, Option } from "effect";
+   *
+   * const data = [1, 2, 3, 4, 5];
+   * const evenSquares = (x: number) => x % 2 === 0 ? Option.some(x * x) : Option.none();
+   * const result = Array.filterMap(data, evenSquares);
+   *
+   * assert.deepStrictEqual(result, [4, 16]);
+   *
+   * @category filtering
+   * @since 2.0.0
+   */
   <A, B>(f: (a: A, i: number) => Option<B>): (self: Iterable<A>) => Array<B>
+  /**
+   * Applies a function to each element of the `Iterable` and filters based on the result, keeping the transformed values where the function returns `Some`.
+   * This method combines filtering and mapping functionalities, allowing transformations and filtering of elements based on a single function pass.
+   *
+   * @example
+   * import { Array, Option } from "effect";
+   *
+   * const data = [1, 2, 3, 4, 5];
+   * const evenSquares = (x: number) => x % 2 === 0 ? Option.some(x * x) : Option.none();
+   * const result = Array.filterMap(data, evenSquares);
+   *
+   * assert.deepStrictEqual(result, [4, 16]);
+   *
+   * @category filtering
+   * @since 2.0.0
+   */
   <A, B>(self: Iterable<A>, f: (a: A, i: number) => Option<B>): Array<B>
 } = dual(
   2,
@@ -2225,7 +4271,41 @@ export const filterMap: {
  * @since 2.0.0
  */
 export const filterMapWhile: {
+  /**
+   * Applies a function to each element of the array and filters based on the result, stopping when a condition is not met.
+   * This method combines filtering and mapping in a single pass, and short-circuits, i.e., stops processing, as soon as the function returns `None`.
+   * This is useful when you need to transform an array but only up to the point where a certain condition holds true.
+   *
+   * @example
+   * import { Array, Option } from "effect";
+   *
+   * const data = [2, 4, 5];
+   * const toSquareTillOdd = (x: number) => x % 2 === 0 ? Option.some(x * x) : Option.none();
+   * const result = Array.filterMapWhile(data, toSquareTillOdd);
+   *
+   * assert.deepStrictEqual(result, [4, 16]);
+   *
+   * @category filtering
+   * @since 2.0.0
+   */
   <A, B>(f: (a: A, i: number) => Option<B>): (self: Iterable<A>) => Array<B>
+  /**
+   * Applies a function to each element of the array and filters based on the result, stopping when a condition is not met.
+   * This method combines filtering and mapping in a single pass, and short-circuits, i.e., stops processing, as soon as the function returns `None`.
+   * This is useful when you need to transform an array but only up to the point where a certain condition holds true.
+   *
+   * @example
+   * import { Array, Option } from "effect";
+   *
+   * const data = [2, 4, 5];
+   * const toSquareTillOdd = (x: number) => x % 2 === 0 ? Option.some(x * x) : Option.none();
+   * const result = Array.filterMapWhile(data, toSquareTillOdd);
+   *
+   * assert.deepStrictEqual(result, [4, 16]);
+   *
+   * @category filtering
+   * @since 2.0.0
+   */
   <A, B>(self: Iterable<A>, f: (a: A, i: number) => Option<B>): Array<B>
 } = dual(2, <A, B>(self: Iterable<A>, f: (a: A, i: number) => Option<B>) => {
   let i = 0
@@ -2266,7 +4346,53 @@ export const filterMapWhile: {
  * @since 2.0.0
  */
 export const partitionMap: {
+  /**
+   * Applies a function to each element of the `Iterable`, categorizing the results into two separate arrays.
+   * This function is particularly useful for operations where each element can result in two possible types,
+   * and you want to separate these types into different collections. For instance, separating validation results
+   * into successes and failures.
+   *
+   * @example
+   * import { Array, Either } from "effect";
+   *
+   * const data = [1, 2, 3, 4, 5]
+   * const isEven = (x: number) => x % 2 === 0
+   * const partitioned = Array.partitionMap(data, x =>
+   *   isEven(x) ? Either.right(x) : Either.left(x)
+   * )
+   *
+   * assert.deepStrictEqual(partitioned, [
+   *   [1, 3, 5],
+   *   [2, 4]
+   * ])
+   *
+   * @category filtering
+   * @since 2.0.0
+   */
   <A, B, C>(f: (a: A, i: number) => array_<C, B>): (self: Iterable<A>) => [left: Array<B>, right: Array<C>]
+  /**
+   * Applies a function to each element of the `Iterable`, categorizing the results into two separate arrays.
+   * This function is particularly useful for operations where each element can result in two possible types,
+   * and you want to separate these types into different collections. For instance, separating validation results
+   * into successes and failures.
+   *
+   * @example
+   * import { Array, Either } from "effect";
+   *
+   * const data = [1, 2, 3, 4, 5]
+   * const isEven = (x: number) => x % 2 === 0
+   * const partitioned = Array.partitionMap(data, x =>
+   *   isEven(x) ? Either.right(x) : Either.left(x)
+   * )
+   *
+   * assert.deepStrictEqual(partitioned, [
+   *   [1, 3, 5],
+   *   [2, 4]
+   * ])
+   *
+   * @category filtering
+   * @since 2.0.0
+   */
   <A, B, C>(self: Iterable<A>, f: (a: A, i: number) => array_<C, B>): [left: Array<B>, right: Array<C>]
 } = dual(
   2,
@@ -2362,9 +4488,25 @@ export const getRights = <T extends Iterable<array_<any, any>>>(
  * @since 2.0.0
  */
 export const filter: {
+  /**
+   * @category filtering
+   * @since 2.0.0
+   */
   <A, B extends A>(refinement: (a: NoInfer<A>, i: number) => a is B): (self: Iterable<A>) => Array<B>
+  /**
+   * @category filtering
+   * @since 2.0.0
+   */
   <A>(predicate: (a: NoInfer<A>, i: number) => boolean): (self: Iterable<A>) => Array<A>
+  /**
+   * @category filtering
+   * @since 2.0.0
+   */
   <A, B extends A>(self: Iterable<A>, refinement: (a: A, i: number) => a is B): Array<B>
+  /**
+   * @category filtering
+   * @since 2.0.0
+   */
   <A>(self: Iterable<A>, predicate: (a: A, i: number) => boolean): Array<A>
 } = dual(
   2,
@@ -2387,16 +4529,40 @@ export const filter: {
  * @since 2.0.0
  */
 export const partition: {
+  /**
+   * Separate elements based on a predicate that also exposes the index of the element.
+   *
+   * @category filtering
+   * @since 2.0.0
+   */
   <A, B extends A>(refinement: (a: NoInfer<A>, i: number) => a is B): (
     self: Iterable<A>
   ) => [excluded: Array<Exclude<A, B>>, satisfying: Array<B>]
+  /**
+   * Separate elements based on a predicate that also exposes the index of the element.
+   *
+   * @category filtering
+   * @since 2.0.0
+   */
   <A>(
     predicate: (a: NoInfer<A>, i: number) => boolean
   ): (self: Iterable<A>) => [excluded: Array<A>, satisfying: Array<A>]
+  /**
+   * Separate elements based on a predicate that also exposes the index of the element.
+   *
+   * @category filtering
+   * @since 2.0.0
+   */
   <A, B extends A>(
     self: Iterable<A>,
     refinement: (a: A, i: number) => a is B
   ): [excluded: Array<Exclude<A, B>>, satisfying: Array<B>]
+  /**
+   * Separate elements based on a predicate that also exposes the index of the element.
+   *
+   * @category filtering
+   * @since 2.0.0
+   */
   <A>(self: Iterable<A>, predicate: (a: A, i: number) => boolean): [excluded: Array<A>, satisfying: Array<A>]
 } = dual(
   2,
@@ -2448,7 +4614,33 @@ export const separate: <T extends Iterable<array_<any, any>>>(
  * @since 2.0.0
  */
 export const reduce: {
+  /**
+   * Reduces an array from the left.
+   *
+   * @example
+   * import { Array } from "effect"
+   *
+   * const numbers = [1, 2, 3]
+   * const result = Array.reduce(numbers, 0, (acc, n) => acc + n)
+   * assert.deepStrictEqual(result, 6)
+   *
+   * @category folding
+   * @since 2.0.0
+   */
   <B, A>(b: B, f: (b: B, a: A, i: number) => B): (self: Iterable<A>) => B
+  /**
+   * Reduces an array from the left.
+   *
+   * @example
+   * import { Array } from "effect"
+   *
+   * const numbers = [1, 2, 3]
+   * const result = Array.reduce(numbers, 0, (acc, n) => acc + n)
+   * assert.deepStrictEqual(result, 6)
+   *
+   * @category folding
+   * @since 2.0.0
+   */
   <A, B>(self: Iterable<A>, b: B, f: (b: B, a: A, i: number) => B): B
 } = dual(
   3,
@@ -2470,7 +4662,33 @@ export const reduce: {
  * @since 2.0.0
  */
 export const reduceRight: {
+  /**
+   * Reduces an array from the right.
+   *
+   * @example
+   * import { Array } from "effect"
+   *
+   * const numbers = [1, 2, 3]
+   * const result = Array.reduceRight(numbers, 0, (acc, n) => acc + n)
+   * assert.deepStrictEqual(result, 6)
+   *
+   * @category folding
+   * @since 2.0.0
+   */
   <B, A>(b: B, f: (b: B, a: A, i: number) => B): (self: Iterable<A>) => B
+  /**
+   * Reduces an array from the right.
+   *
+   * @example
+   * import { Array } from "effect"
+   *
+   * const numbers = [1, 2, 3]
+   * const result = Array.reduceRight(numbers, 0, (acc, n) => acc + n)
+   * assert.deepStrictEqual(result, 6)
+   *
+   * @category folding
+   * @since 2.0.0
+   */
   <A, B>(self: Iterable<A>, b: B, f: (b: B, a: A, i: number) => B): B
 } = dual(
   3,
@@ -2494,6 +4712,20 @@ export const reduceRight: {
  */
 export const liftPredicate: { // Note: I intentionally avoid using the NoInfer pattern here.
   <A, B extends A>(refinement: Refinement<A, B>): (a: A) => Array<B>
+  /**
+   * Lifts a predicate into an array.
+   *
+   * @example
+   * import { Array } from "effect"
+   *
+   * const isEven = (n: number) => n % 2 === 0
+   * const to = Array.liftPredicate(isEven)
+   * assert.deepStrictEqual(to(1), [])
+   * assert.deepStrictEqual(to(2), [2])
+   *
+   * @category lifting
+   * @since 2.0.0
+   */
   <A>(predicate: Predicate<A>): <B extends A>(b: B) => Array<B>
 } = <A>(predicate: Predicate<A>) => <B extends A>(b: B): Array<B> => predicate(b) ? [b] : []
 
@@ -2540,7 +4772,43 @@ export const liftNullable = <A extends Array<unknown>, B>(
  * @since 2.0.0
  */
 export const flatMapNullable: {
+  /**
+   * Maps over an array and flattens the result, removing null and undefined values.
+   *
+   * @example
+   * import { Array } from "effect"
+   *
+   * const numbers = [1, 2, 3]
+   * const result = Array.flatMapNullable(numbers, n => (n % 2 === 0 ? null : n))
+   * assert.deepStrictEqual(result, [1, 3])
+   *
+   * // Explanation:
+   * // The array of numbers [1, 2, 3] is mapped with a function that returns null for even numbers
+   * // and the number itself for odd numbers. The resulting array [1, null, 3] is then flattened
+   * // to remove null values, resulting in [1, 3].
+   *
+   * @category sequencing
+   * @since 2.0.0
+   */
   <A, B>(f: (a: A) => B | null | undefined): (self: ReadonlyArray<A>) => Array<NonNullable<B>>
+  /**
+   * Maps over an array and flattens the result, removing null and undefined values.
+   *
+   * @example
+   * import { Array } from "effect"
+   *
+   * const numbers = [1, 2, 3]
+   * const result = Array.flatMapNullable(numbers, n => (n % 2 === 0 ? null : n))
+   * assert.deepStrictEqual(result, [1, 3])
+   *
+   * // Explanation:
+   * // The array of numbers [1, 2, 3] is mapped with a function that returns null for even numbers
+   * // and the number itself for odd numbers. The resulting array [1, null, 3] is then flattened
+   * // to remove null values, resulting in [1, 3].
+   *
+   * @category sequencing
+   * @since 2.0.0
+   */
   <A, B>(self: ReadonlyArray<A>, f: (a: A) => B | null | undefined): Array<NonNullable<B>>
 } = dual(
   2,
@@ -2590,11 +4858,35 @@ export const liftEither = <A extends Array<unknown>, E, B>(
  * @since 2.0.0
  */
 export const every: {
+  /**
+   * Check if a predicate holds true for every `ReadonlyArray` element.
+   *
+   * @category elements
+   * @since 2.0.0
+   */
   <A, B extends A>(
     refinement: (a: NoInfer<A>, i: number) => a is B
   ): (self: ReadonlyArray<A>) => self is ReadonlyArray<B>
+  /**
+   * Check if a predicate holds true for every `ReadonlyArray` element.
+   *
+   * @category elements
+   * @since 2.0.0
+   */
   <A>(predicate: (a: NoInfer<A>, i: number) => boolean): (self: ReadonlyArray<A>) => boolean
+  /**
+   * Check if a predicate holds true for every `ReadonlyArray` element.
+   *
+   * @category elements
+   * @since 2.0.0
+   */
   <A, B extends A>(self: ReadonlyArray<A>, refinement: (a: A, i: number) => a is B): self is ReadonlyArray<B>
+  /**
+   * Check if a predicate holds true for every `ReadonlyArray` element.
+   *
+   * @category elements
+   * @since 2.0.0
+   */
   <A>(self: ReadonlyArray<A>, predicate: (a: A, i: number) => boolean): boolean
 } = dual(
   2,
@@ -2609,9 +4901,19 @@ export const every: {
  * @since 2.0.0
  */
 export const some: {
-  <A>(
-    predicate: (a: NoInfer<A>, i: number) => boolean
-  ): (self: ReadonlyArray<A>) => self is NonEmptyReadonlyArray<A>
+  /**
+   * Check if a predicate holds true for some `ReadonlyArray` element.
+   *
+   * @category elements
+   * @since 2.0.0
+   */
+  <A>(predicate: (a: NoInfer<A>, i: number) => boolean): (self: ReadonlyArray<A>) => self is NonEmptyReadonlyArray<A>
+  /**
+   * Check if a predicate holds true for some `ReadonlyArray` element.
+   *
+   * @category elements
+   * @since 2.0.0
+   */
   <A>(self: ReadonlyArray<A>, predicate: (a: A, i: number) => boolean): self is NonEmptyReadonlyArray<A>
 } = dual(
   2,
@@ -2638,7 +4940,43 @@ export const some: {
  * @since 2.0.0
  */
 export const extend: {
+  /**
+   * Extends an array with a function that maps each subarray to a value.
+   *
+   * @example
+   * import { Array } from "effect"
+   *
+   * const numbers = [1, 2, 3]
+   * const result = Array.extend(numbers, as => as.length)
+   * assert.deepStrictEqual(result, [3, 2, 1])
+   *
+   * // Explanation:
+   * // The function maps each subarray starting from each element to its length.
+   * // The subarrays are: [1, 2, 3], [2, 3], [3].
+   * // The lengths are: 3, 2, 1.
+   * // Therefore, the result is [3, 2, 1].
+   *
+   * @since 2.0.0
+   */
   <A, B>(f: (as: ReadonlyArray<A>) => B): (self: ReadonlyArray<A>) => Array<B>
+  /**
+   * Extends an array with a function that maps each subarray to a value.
+   *
+   * @example
+   * import { Array } from "effect"
+   *
+   * const numbers = [1, 2, 3]
+   * const result = Array.extend(numbers, as => as.length)
+   * assert.deepStrictEqual(result, [3, 2, 1])
+   *
+   * // Explanation:
+   * // The function maps each subarray starting from each element to its length.
+   * // The subarrays are: [1, 2, 3], [2, 3], [3].
+   * // The lengths are: 3, 2, 1.
+   * // Therefore, the result is [3, 2, 1].
+   *
+   * @since 2.0.0
+   */
   <A, B>(self: ReadonlyArray<A>, f: (as: ReadonlyArray<A>) => B): Array<B>
 } = dual(
   2,
@@ -2657,7 +4995,29 @@ export const extend: {
  * @since 2.0.0
  */
 export const min: {
+  /**
+   * Finds the minimum element in an array based on a comparator.
+   *
+   * @example
+   * import { Array, Order } from "effect"
+   *
+   * const min = Array.min([3, 1, 2], Order.number)
+   * assert.deepStrictEqual(min, 1)
+   *
+   * @since 2.0.0
+   */
   <A>(O: Order.Order<A>): (self: NonEmptyReadonlyArray<A>) => A
+  /**
+   * Finds the minimum element in an array based on a comparator.
+   *
+   * @example
+   * import { Array, Order } from "effect"
+   *
+   * const min = Array.min([3, 1, 2], Order.number)
+   * assert.deepStrictEqual(min, 1)
+   *
+   * @since 2.0.0
+   */
   <A>(self: NonEmptyReadonlyArray<A>, O: Order.Order<A>): A
 } = dual(2, <A>(self: NonEmptyReadonlyArray<A>, O: Order.Order<A>): A => self.reduce(Order.min(O)))
 
@@ -2673,7 +5033,29 @@ export const min: {
  * @since 2.0.0
  */
 export const max: {
+  /**
+   * Finds the maximum element in an array based on a comparator.
+   *
+   * @example
+   * import { Array, Order } from "effect"
+   *
+   * const max = Array.max([3, 1, 2], Order.number)
+   * assert.deepStrictEqual(max, 3)
+   *
+   * @since 2.0.0
+   */
   <A>(O: Order.Order<A>): (self: NonEmptyReadonlyArray<A>) => A
+  /**
+   * Finds the maximum element in an array based on a comparator.
+   *
+   * @example
+   * import { Array, Order } from "effect"
+   *
+   * const max = Array.max([3, 1, 2], Order.number)
+   * assert.deepStrictEqual(max, 3)
+   *
+   * @since 2.0.0
+   */
   <A>(self: NonEmptyReadonlyArray<A>, O: Order.Order<A>): A
 } = dual(2, <A>(self: NonEmptyReadonlyArray<A>, O: Order.Order<A>): A => self.reduce(Order.max(O)))
 
@@ -2734,7 +5116,29 @@ export const getEquivalence: <A>(
  * @since 2.0.0
  */
 export const forEach: {
+  /**
+   * Performs a side-effect for each element of the `Iterable`.
+   *
+   * @example
+   * import { Array } from "effect"
+   *
+   * const numbers = [1, 2, 3]
+   * Array.forEach(numbers, n => console.log(n)) // 1, 2, 3
+   *
+   * @since 2.0.0
+   */
   <A>(f: (a: A, i: number) => void): (self: Iterable<A>) => void
+  /**
+   * Performs a side-effect for each element of the `Iterable`.
+   *
+   * @example
+   * import { Array } from "effect"
+   *
+   * const numbers = [1, 2, 3]
+   * Array.forEach(numbers, n => console.log(n)) // 1, 2, 3
+   *
+   * @since 2.0.0
+   */
   <A>(self: Iterable<A>, f: (a: A, i: number) => void): void
 } = dual(2, <A>(self: Iterable<A>, f: (a: A, i: number) => void): void => fromIterable(self).forEach((a, i) => f(a, i)))
 
@@ -2752,10 +5156,52 @@ export const forEach: {
  * @since 2.0.0
  */
 export const dedupeWith: {
+  /**
+   * Remove duplicates from an `Iterable` using the provided `isEquivalent` function,
+   * preserving the order of the first occurrence of each element.
+   *
+   * @example
+   * import { Array } from "effect"
+   *
+   * const numbers = [1, 2, 2, 3, 3, 3]
+   * const unique = Array.dedupeWith(numbers, (a, b) => a === b)
+   * assert.deepStrictEqual(unique, [1, 2, 3])
+   *
+   * @since 2.0.0
+   */
   <S extends Iterable<any>>(
     isEquivalent: (self: ReadonlyArray.Infer<S>, that: ReadonlyArray.Infer<S>) => boolean
   ): (self: S) => ReadonlyArray.With<S, ReadonlyArray.Infer<S>>
-  <A>(self: NonEmptyReadonlyArray<A>, isEquivalent: (self: A, that: A) => boolean): NonEmptyArray<A>
+  /**
+   * Remove duplicates from an `Iterable` using the provided `isEquivalent` function,
+   * preserving the order of the first occurrence of each element.
+   *
+   * @example
+   * import { Array } from "effect"
+   *
+   * const numbers = [1, 2, 2, 3, 3, 3]
+   * const unique = Array.dedupeWith(numbers, (a, b) => a === b)
+   * assert.deepStrictEqual(unique, [1, 2, 3])
+   *
+   * @since 2.0.0
+   */
+  <A>(
+    self: NonEmptyReadonlyArray<A>,
+    isEquivalent: (self: A, that: A) => boolean
+  ): NonEmptyArray<A>
+  /**
+   * Remove duplicates from an `Iterable` using the provided `isEquivalent` function,
+   * preserving the order of the first occurrence of each element.
+   *
+   * @example
+   * import { Array } from "effect"
+   *
+   * const numbers = [1, 2, 2, 3, 3, 3]
+   * const unique = Array.dedupeWith(numbers, (a, b) => a === b)
+   * assert.deepStrictEqual(unique, [1, 2, 3])
+   *
+   * @since 2.0.0
+   */
   <A>(self: Iterable<A>, isEquivalent: (self: A, that: A) => boolean): Array<A>
 } = dual(
   2,
@@ -2799,7 +5245,31 @@ export const dedupe = <S extends Iterable<any> | NonEmptyReadonlyArray<any>>(
  * @since 2.0.0
  */
 export const dedupeAdjacentWith: {
+  /**
+   * Deduplicates adjacent elements that are identical using the provided `isEquivalent` function.
+   *
+   * @example
+   * import { Array } from "effect"
+   *
+   * const numbers = [1, 1, 2, 2, 3, 3]
+   * const unique = Array.dedupeAdjacentWith(numbers, (a, b) => a === b)
+   * assert.deepStrictEqual(unique, [1, 2, 3])
+   *
+   * @since 2.0.0
+   */
   <A>(isEquivalent: (self: A, that: A) => boolean): (self: Iterable<A>) => Array<A>
+  /**
+   * Deduplicates adjacent elements that are identical using the provided `isEquivalent` function.
+   *
+   * @example
+   * import { Array } from "effect"
+   *
+   * const numbers = [1, 1, 2, 2, 3, 3]
+   * const unique = Array.dedupeAdjacentWith(numbers, (a, b) => a === b)
+   * assert.deepStrictEqual(unique, [1, 2, 3])
+   *
+   * @since 2.0.0
+   */
   <A>(self: Iterable<A>, isEquivalent: (self: A, that: A) => boolean): Array<A>
 } = dual(2, <A>(self: Iterable<A>, isEquivalent: (self: A, that: A) => boolean): Array<A> => {
   const out: Array<A> = []
@@ -2841,7 +5311,33 @@ export const dedupeAdjacent: <A>(self: Iterable<A>) => Array<A> = dedupeAdjacent
  * @category folding
  */
 export const join: {
+  /**
+   * Joins the elements together with "sep" in the middle.
+   *
+   * @example
+   * import { Array } from "effect"
+   *
+   * const strings = ["a", "b", "c"]
+   * const joined = Array.join(strings, "-")
+   * assert.deepStrictEqual(joined, "a-b-c")
+   *
+   * @since 2.0.0
+   * @category folding
+   */
   (sep: string): (self: Iterable<string>) => string
+  /**
+   * Joins the elements together with "sep" in the middle.
+   *
+   * @example
+   * import { Array } from "effect"
+   *
+   * const strings = ["a", "b", "c"]
+   * const joined = Array.join(strings, "-")
+   * assert.deepStrictEqual(joined, "a-b-c")
+   *
+   * @since 2.0.0
+   * @category folding
+   */
   (self: Iterable<string>, sep: string): string
 } = dual(2, (self: Iterable<string>, sep: string): string => fromIterable(self).join(sep))
 
@@ -2859,11 +5355,41 @@ export const join: {
  * @category folding
  */
 export const mapAccum: {
-  <S, A, B>(
+  /**
+   * Statefully maps over the chunk, producing new elements of type `B`.
+   *
+   * @example
+   * import { Array } from "effect"
+   *
+   * const numbers = [1, 2, 3]
+   * const result = Array.mapAccum(numbers, 0, (acc, n) => [acc + n, acc + n])
+   * assert.deepStrictEqual(result, [6, [1, 3, 6]])
+   *
+   * @since 2.0.0
+   * @category folding
+   */
+  <S, A, B, I extends Iterable<A> = Iterable<A>>(
     s: S,
-    f: (s: S, a: A, i: number) => readonly [S, B]
-  ): (self: Iterable<A>) => [state: S, mappedArray: Array<B>]
-  <S, A, B>(self: Iterable<A>, s: S, f: (s: S, a: A, i: number) => readonly [S, B]): [state: S, mappedArray: Array<B>]
+    f: (s: S, a: ReadonlyArray.Infer<I>, i: number) => readonly [S, B]
+  ): (self: I) => [state: S, mappedArray: ReadonlyArray.With<I, B>]
+  /**
+   * Statefully maps over the chunk, producing new elements of type `B`.
+   *
+   * @example
+   * import { Array } from "effect"
+   *
+   * const numbers = [1, 2, 3]
+   * const result = Array.mapAccum(numbers, 0, (acc, n) => [acc + n, acc + n])
+   * assert.deepStrictEqual(result, [6, [1, 3, 6]])
+   *
+   * @since 2.0.0
+   * @category folding
+   */
+  <S, A, B, I extends Iterable<A> = Iterable<A>>(
+    self: I,
+    s: S,
+    f: (s: S, a: ReadonlyArray.Infer<I>, i: number) => readonly [S, B]
+  ): [state: S, mappedArray: ReadonlyArray.With<I, B>]
 } = dual(
   3,
   <S, A, B>(self: Iterable<A>, s: S, f: (s: S, a: A, i: number) => [S, B]): [state: S, mappedArray: Array<B>] => {
@@ -2895,7 +5421,35 @@ export const mapAccum: {
  * @category elements
  */
 export const cartesianWith: {
+  /**
+   * Zips this chunk crosswise with the specified chunk using the specified combiner.
+   *
+   * @example
+   * import { Array } from "effect"
+   *
+   * const array1 = [1, 2]
+   * const array2 = ["a", "b"]
+   * const product = Array.cartesianWith(array1, array2, (a, b) => `${a}-${b}`)
+   * assert.deepStrictEqual(product, ["1-a", "1-b", "2-a", "2-b"])
+   *
+   * @since 2.0.0
+   * @category elements
+   */
   <A, B, C>(that: ReadonlyArray<B>, f: (a: A, b: B) => C): (self: ReadonlyArray<A>) => Array<C>
+  /**
+   * Zips this chunk crosswise with the specified chunk using the specified combiner.
+   *
+   * @example
+   * import { Array } from "effect"
+   *
+   * const array1 = [1, 2]
+   * const array2 = ["a", "b"]
+   * const product = Array.cartesianWith(array1, array2, (a, b) => `${a}-${b}`)
+   * assert.deepStrictEqual(product, ["1-a", "1-b", "2-a", "2-b"])
+   *
+   * @since 2.0.0
+   * @category elements
+   */
   <A, B, C>(self: ReadonlyArray<A>, that: ReadonlyArray<B>, f: (a: A, b: B) => C): Array<C>
 } = dual(
   3,
@@ -2918,7 +5472,35 @@ export const cartesianWith: {
  * @category elements
  */
 export const cartesian: {
+  /**
+   * Zips this chunk crosswise with the specified chunk.
+   *
+   * @example
+   * import { Array } from "effect"
+   *
+   * const array1 = [1, 2]
+   * const array2 = ["a", "b"]
+   * const product = Array.cartesian(array1, array2)
+   * assert.deepStrictEqual(product, [[1, "a"], [1, "b"], [2, "a"], [2, "b"]])
+   *
+   * @since 2.0.0
+   * @category elements
+   */
   <B>(that: ReadonlyArray<B>): <A>(self: ReadonlyArray<A>) => Array<[A, B]>
+  /**
+   * Zips this chunk crosswise with the specified chunk.
+   *
+   * @example
+   * import { Array } from "effect"
+   *
+   * const array1 = [1, 2]
+   * const array2 = ["a", "b"]
+   * const product = Array.cartesian(array1, array2)
+   * assert.deepStrictEqual(product, [[1, "a"], [1, "b"], [2, "a"], [2, "b"]])
+   *
+   * @since 2.0.0
+   * @category elements
+   */
   <A, B>(self: ReadonlyArray<A>, that: ReadonlyArray<B>): Array<[A, B]>
 } = dual(
   2,
@@ -3018,12 +5600,95 @@ export const Do: ReadonlyArray<{}> = of({})
  * @since 3.2.0
  */
 export const bind: {
-  <A extends object, N extends string, B>(
-    tag: Exclude<N, keyof A>,
-    f: (a: A) => ReadonlyArray<B>
-  ): (
+  /**
+   * The "do simulation" for array allows you to sequentially apply operations to the elements of arrays, just as nested loops allow you to go through all combinations of elements in an arrays.
+   *
+   * It can be used to simulate "array comprehension".
+   * It's a technique that allows you to create new arrays by iterating over existing ones and applying specific **conditions** or **transformations** to the elements. It's like assembling a new collection from pieces of other collections based on certain rules.
+   *
+   * Here's how the do simulation works:
+   *
+   * 1. Start the do simulation using the `Do` value
+   * 2. Within the do simulation scope, you can use the `bind` function to define variables and bind them to `Array` values
+   * 3. You can accumulate multiple `bind` statements to define multiple variables within the scope
+   * 4. Inside the do simulation scope, you can also use the `let` function to define variables and bind them to simple values
+   * 5. Regular `Option` functions like `map` and `filter` can still be used within the do simulation. These functions will receive the accumulated variables as arguments within the scope
+   *
+   * @see {@link bindTo}
+   * @see {@link Do}
+   * @see {@link let_ let}
+   *
+   * @example
+   * import { Array as Arr, pipe } from "effect"
+   * const doResult = pipe(
+   *   Arr.Do,
+   *   Arr.bind("x", () => [1, 3, 5]),
+   *   Arr.bind("y", () => [2, 4, 6]),
+   *   Arr.filter(({ x, y }) => x < y), // condition
+   *   Arr.map(({ x, y }) => [x, y] as const) // transformation
+   * )
+   * assert.deepStrictEqual(doResult, [[1, 2], [1, 4], [1, 6], [3, 4], [3, 6], [5, 6]])
+   *
+   * // equivalent
+   * const x = [1, 3, 5],
+   *       y = [2, 4, 6],
+   *       result = [];
+   * for(let i = 0; i < x.length; i++) {
+   *   for(let j = 0; j < y.length; j++) {
+   *     const _x = x[i], _y = y[j];
+   *     if(_x < _y) result.push([_x, _y] as const)
+   *   }
+   * }
+   *
+   * @category do notation
+   * @since 3.2.0
+   */
+  <A extends object, N extends string, B>(tag: Exclude<N, keyof A>, f: (a: A) => ReadonlyArray<B>): (
     self: ReadonlyArray<A>
   ) => Array<{ [K in N | keyof A]: K extends keyof A ? A[K] : B }>
+  /**
+   * The "do simulation" for array allows you to sequentially apply operations to the elements of arrays, just as nested loops allow you to go through all combinations of elements in an arrays.
+   *
+   * It can be used to simulate "array comprehension".
+   * It's a technique that allows you to create new arrays by iterating over existing ones and applying specific **conditions** or **transformations** to the elements. It's like assembling a new collection from pieces of other collections based on certain rules.
+   *
+   * Here's how the do simulation works:
+   *
+   * 1. Start the do simulation using the `Do` value
+   * 2. Within the do simulation scope, you can use the `bind` function to define variables and bind them to `Array` values
+   * 3. You can accumulate multiple `bind` statements to define multiple variables within the scope
+   * 4. Inside the do simulation scope, you can also use the `let` function to define variables and bind them to simple values
+   * 5. Regular `Option` functions like `map` and `filter` can still be used within the do simulation. These functions will receive the accumulated variables as arguments within the scope
+   *
+   * @see {@link bindTo}
+   * @see {@link Do}
+   * @see {@link let_ let}
+   *
+   * @example
+   * import { Array as Arr, pipe } from "effect"
+   * const doResult = pipe(
+   *   Arr.Do,
+   *   Arr.bind("x", () => [1, 3, 5]),
+   *   Arr.bind("y", () => [2, 4, 6]),
+   *   Arr.filter(({ x, y }) => x < y), // condition
+   *   Arr.map(({ x, y }) => [x, y] as const) // transformation
+   * )
+   * assert.deepStrictEqual(doResult, [[1, 2], [1, 4], [1, 6], [3, 4], [3, 6], [5, 6]])
+   *
+   * // equivalent
+   * const x = [1, 3, 5],
+   *       y = [2, 4, 6],
+   *       result = [];
+   * for(let i = 0; i < x.length; i++) {
+   *   for(let j = 0; j < y.length; j++) {
+   *     const _x = x[i], _y = y[j];
+   *     if(_x < _y) result.push([_x, _y] as const)
+   *   }
+   * }
+   *
+   * @category do notation
+   * @since 3.2.0
+   */
   <A extends object, N extends string, B>(
     self: ReadonlyArray<A>,
     tag: Exclude<N, keyof A>,
@@ -3075,7 +5740,93 @@ export const bind: {
  * @since 3.2.0
  */
 export const bindTo: {
+  /**
+   * The "do simulation" for array allows you to sequentially apply operations to the elements of arrays, just as nested loops allow you to go through all combinations of elements in an arrays.
+   *
+   * It can be used to simulate "array comprehension".
+   * It's a technique that allows you to create new arrays by iterating over existing ones and applying specific **conditions** or **transformations** to the elements. It's like assembling a new collection from pieces of other collections based on certain rules.
+   *
+   * Here's how the do simulation works:
+   *
+   * 1. Start the do simulation using the `Do` value
+   * 2. Within the do simulation scope, you can use the `bind` function to define variables and bind them to `Array` values
+   * 3. You can accumulate multiple `bind` statements to define multiple variables within the scope
+   * 4. Inside the do simulation scope, you can also use the `let` function to define variables and bind them to simple values
+   * 5. Regular `Option` functions like `map` and `filter` can still be used within the do simulation. These functions will receive the accumulated variables as arguments within the scope
+   *
+   * @see {@link bindTo}
+   * @see {@link Do}
+   * @see {@link let_ let}
+   *
+   * @example
+   * import { Array as Arr, pipe } from "effect"
+   * const doResult = pipe(
+   *   Arr.Do,
+   *   Arr.bind("x", () => [1, 3, 5]),
+   *   Arr.bind("y", () => [2, 4, 6]),
+   *   Arr.filter(({ x, y }) => x < y), // condition
+   *   Arr.map(({ x, y }) => [x, y] as const) // transformation
+   * )
+   * assert.deepStrictEqual(doResult, [[1, 2], [1, 4], [1, 6], [3, 4], [3, 6], [5, 6]])
+   *
+   * // equivalent
+   * const x = [1, 3, 5],
+   *       y = [2, 4, 6],
+   *       result = [];
+   * for(let i = 0; i < x.length; i++) {
+   *   for(let j = 0; j < y.length; j++) {
+   *     const _x = x[i], _y = y[j];
+   *     if(_x < _y) result.push([_x, _y] as const)
+   *   }
+   * }
+   *
+   * @category do notation
+   * @since 3.2.0
+   */
   <N extends string>(tag: N): <A>(self: ReadonlyArray<A>) => Array<{ [K in N]: A }>
+  /**
+   * The "do simulation" for array allows you to sequentially apply operations to the elements of arrays, just as nested loops allow you to go through all combinations of elements in an arrays.
+   *
+   * It can be used to simulate "array comprehension".
+   * It's a technique that allows you to create new arrays by iterating over existing ones and applying specific **conditions** or **transformations** to the elements. It's like assembling a new collection from pieces of other collections based on certain rules.
+   *
+   * Here's how the do simulation works:
+   *
+   * 1. Start the do simulation using the `Do` value
+   * 2. Within the do simulation scope, you can use the `bind` function to define variables and bind them to `Array` values
+   * 3. You can accumulate multiple `bind` statements to define multiple variables within the scope
+   * 4. Inside the do simulation scope, you can also use the `let` function to define variables and bind them to simple values
+   * 5. Regular `Option` functions like `map` and `filter` can still be used within the do simulation. These functions will receive the accumulated variables as arguments within the scope
+   *
+   * @see {@link bindTo}
+   * @see {@link Do}
+   * @see {@link let_ let}
+   *
+   * @example
+   * import { Array as Arr, pipe } from "effect"
+   * const doResult = pipe(
+   *   Arr.Do,
+   *   Arr.bind("x", () => [1, 3, 5]),
+   *   Arr.bind("y", () => [2, 4, 6]),
+   *   Arr.filter(({ x, y }) => x < y), // condition
+   *   Arr.map(({ x, y }) => [x, y] as const) // transformation
+   * )
+   * assert.deepStrictEqual(doResult, [[1, 2], [1, 4], [1, 6], [3, 4], [3, 6], [5, 6]])
+   *
+   * // equivalent
+   * const x = [1, 3, 5],
+   *       y = [2, 4, 6],
+   *       result = [];
+   * for(let i = 0; i < x.length; i++) {
+   *   for(let j = 0; j < y.length; j++) {
+   *     const _x = x[i], _y = y[j];
+   *     if(_x < _y) result.push([_x, _y] as const)
+   *   }
+   * }
+   *
+   * @category do notation
+   * @since 3.2.0
+   */
   <A, N extends string>(self: ReadonlyArray<A>, tag: N): Array<{ [K in N]: A }>
 } = doNotation.bindTo<ReadonlyArrayTypeLambda>(map) as any