effect 4.0.0-beta.74 → 4.0.0-beta.75

package/src/Option.ts

@@ -276,7 +276,8 @@ export interface OptionUnifyIgnore {}
  *
  * **When to use**
  *
- * Use to represent `Option` in higher-kinded type operations.
+ * Use when defining higher-kinded abstractions that must accept optional-value
+ * types as one of their type-lambda inputs.
  *
  * @category type lambdas
  * @since 2.0.0
@@ -323,7 +324,7 @@ export const none = <A = never>(): Option<A> => option.none
  *
  * **When to use**
  *
- * Use to wrap a known-present value as `Option`
+ * Use to wrap a known present value as `Option`
  * - Returning a successful result from a partial function
  *
  * **Details**
@@ -392,7 +393,7 @@ export const isOption: (input: unknown) => input is Option<unknown> = option.isO
  *
  * **When to use**
  *
- * Use when branching on absence before accessing `.value`
+ * Use when you need to branch on an absent `Option` before accessing `.value`.
  *
  * **Details**
  *
@@ -422,7 +423,7 @@ export const isNone: <A>(self: Option<A>) => self is None<A> = option.isNone
  *
  * **When to use**
  *
- * Use when branching on presence before accessing `.value`
+ * Use when you need to branch on a present `Option` before accessing `.value`.
  *
  * **Details**
  *
@@ -452,8 +453,8 @@ export const isSome: <A>(self: Option<A>) => self is Some<A> = option.isSome
  *
  * **When to use**
  *
- * Use when exhaustively handling both branches in one expression
- * - Transforming an `Option` into a plain value
+ * Use when you need to handle both `Some` and `None` in one expression and
+ * transform an `Option` into a plain value.
  *
  * **Details**
  *
@@ -486,8 +487,8 @@ export const match: {
    *
    * **When to use**
    *
-   * Use when exhaustively handling both branches in one expression
-   * - Transforming an `Option` into a plain value
+   * Use when you need to handle both `Some` and `None` in one expression and
+   * transform an `Option` into a plain value.
    *
    * **Details**
    *
@@ -525,8 +526,8 @@ export const match: {
    *
    * **When to use**
    *
-   * Use when exhaustively handling both branches in one expression
-   * - Transforming an `Option` into a plain value
+   * Use when you need to handle both `Some` and `None` in one expression and
+   * transform an `Option` into a plain value.
    *
    * **Details**
    *
@@ -573,8 +574,8 @@ export const match: {
  *
  * **When to use**
  *
- * Use when turning a parsing function into a type-narrowing predicate
- * - Filtering arrays with `Array.prototype.filter`
+ * Use when you need to turn an `Option`-returning parser into a type-narrowing
+ * predicate, such as for `Array.prototype.filter`.
  *
  * **Details**
  *
@@ -616,8 +617,8 @@ export const toRefinement = <A, B extends A>(f: (a: A) => Option<B>): (a: A) =>
  *
  * **When to use**
  *
- * Use when safely extracting the head of a collection
- * - Working with generators or lazy iterables
+ * Use when you need to safely extract the head of a collection, including
+ * generators or lazy iterables.
  *
  * **Details**
  *
@@ -653,7 +654,8 @@ export const fromIterable = <A>(collection: Iterable<A>): Option<A> => {
  *
  * **When to use**
  *
- * Use when discarding the failure channel when you only care about success
+ * Use when you need to discard a `Result` failure and keep only the success
+ * value as an `Option`.
  *
  * **Details**
  *
@@ -684,7 +686,8 @@ export const getSuccess: <A, E>(self: Result<A, E>) => Option<A> = result.getSuc
  *
  * **When to use**
  *
- * Use to extract the failure when you do not need the success value
+ * Use when you need to discard a `Result` success and keep only the failure
+ * value as an `Option`.
  *
  * **Details**
  *
@@ -822,8 +825,8 @@ export const getOrElse: {
  *
  * **When to use**
  *
- * Use when chaining fallback `Option` computations
- * - Building priority chains of optional values
+ * Use when you need a lazy fallback `Option`, such as when building priority
+ * chains of optional values.
  *
  * **Details**
  *
@@ -855,8 +858,8 @@ export const orElse: {
    *
    * **When to use**
    *
-   * Use when chaining fallback `Option` computations
-   * - Building priority chains of optional values
+   * Use when you need a lazy fallback `Option`, such as when building priority
+   * chains of optional values.
    *
    * **Details**
    *
@@ -888,8 +891,8 @@ export const orElse: {
    *
    * **When to use**
    *
-   * Use when chaining fallback `Option` computations
-   * - Building priority chains of optional values
+   * Use when you need a lazy fallback `Option`, such as when building priority
+   * chains of optional values.
    *
    * **Details**
    *
@@ -1024,8 +1027,8 @@ export const orElseSome: {
  *
  * **When to use**
  *
- * Use when distinguishing whether a value came from the primary or fallback
- * `Option`.
+ * Use when you need to know whether a present value came from the primary or
+ * fallback `Option`.
  *
  * **Details**
  *
@@ -1056,8 +1059,8 @@ export const orElseResult: {
    *
    * **When to use**
    *
-   * Use when distinguishing whether a value came from the primary or fallback
-   * `Option`.
+   * Use when you need to know whether a present value came from the primary or
+   * fallback `Option`.
    *
    * **Details**
    *
@@ -1088,8 +1091,8 @@ export const orElseResult: {
    *
    * **When to use**
    *
-   * Use when distinguishing whether a value came from the primary or fallback
-   * `Option`.
+   * Use when you need to know whether a present value came from the primary or
+   * fallback `Option`.
    *
    * **Details**
    *
@@ -1127,7 +1130,7 @@ export const orElseResult: {
  *
  * **When to use**
  *
- * Use when searching for the first available value in a priority list
+ * Use when you need the first available `Some` value from a priority list.
  *
  * **Details**
  *
@@ -1169,8 +1172,8 @@ export const firstSomeOf = <T, C extends Iterable<Option<T>> = Iterable<Option<T
  *
  * **When to use**
  *
- * Use when bridging from nullable APIs to `Option`
- * - Wrapping values that may be `null` or `undefined`
+ * Use when you need JavaScript nullish values to become absence at an API
+ * boundary while all other values, including falsy ones, remain present.
  *
  * **Details**
  *
@@ -1209,7 +1212,8 @@ export const fromNullishOr = <A>(
  *
  * **When to use**
  *
- * Use when when `null` is a meaningful value but `undefined` means absent
+ * Use when you want to treat only `undefined` as absent while preserving `null`
+ * as a meaningful value.
  *
  * **Details**
  *
@@ -1247,7 +1251,8 @@ export const fromUndefinedOr = <A>(
  *
  * **When to use**
  *
- * Use when when `undefined` is a meaningful value but `null` means absent
+ * Use when you want to treat only `null` as absent while preserving
+ * `undefined` as a meaningful value.
  *
  * **Details**
  *
@@ -1327,7 +1332,7 @@ export const liftNullishOr = <A extends ReadonlyArray<unknown>, B>(
  *
  * **When to use**
  *
- * Use when interoping with APIs that use `null` for missing values
+ * Use when you need to pass absent `Option` values to APIs that expect `null`.
  *
  * **Details**
  *
@@ -1359,7 +1364,8 @@ export const getOrNull: <A>(self: Option<A>) => A | null = getOrElse(constNull)
  *
  * **When to use**
  *
- * Use when interoping with APIs that use `undefined` for missing values
+ * Use when you need to pass absent `Option` values to APIs that expect
+ * `undefined`.
  *
  * **Details**
  *
@@ -1433,8 +1439,8 @@ export const liftThrowable = <A extends ReadonlyArray<unknown>, B>(
  *
  * **When to use**
  *
- * Use when fail-fast unwrapping when absence is unexpected
- * - Providing a descriptive error for debugging
+ * Use when you need fail-fast unwrapping of an `Option` for unexpected absence
+ * and want to provide a descriptive debugging error.
  *
  * **Details**
  *
@@ -1465,8 +1471,8 @@ export const getOrThrowWith: {
    *
    * **When to use**
    *
-   * Use when fail-fast unwrapping when absence is unexpected
-   * - Providing a descriptive error for debugging
+   * Use when you need fail-fast unwrapping of an `Option` for unexpected absence
+   * and want to provide a descriptive debugging error.
    *
    * **Details**
    *
@@ -1497,8 +1503,8 @@ export const getOrThrowWith: {
    *
    * **When to use**
    *
-   * Use when fail-fast unwrapping when absence is unexpected
-   * - Providing a descriptive error for debugging
+   * Use when you need fail-fast unwrapping of an `Option` for unexpected absence
+   * and want to provide a descriptive debugging error.
    *
    * **Details**
    *
@@ -1536,7 +1542,8 @@ export const getOrThrowWith: {
  *
  * **When to use**
  *
- * Use when quick fail-fast unwrapping when a generic error is acceptable
+ * Use when you need quick fail-fast unwrapping of an `Option` and a generic
+ * error is acceptable.
  *
  * **Details**
  *
@@ -1569,8 +1576,8 @@ export const getOrThrow: <A>(self: Option<A>) => A = getOrThrowWith(() => new Er
  *
  * **When to use**
  *
- * Use to apply a pure transformation to an optional value, especially when
- * chaining transformations in a pipeline.
+ * Use to apply a pure transformation to an `Option`'s present value, especially
+ * when chaining transformations in a pipeline.
  *
  * **Details**
  *
@@ -1602,8 +1609,8 @@ export const map: {
    *
    * **When to use**
    *
-   * Use to apply a pure transformation to an optional value, especially when
-   * chaining transformations in a pipeline.
+   * Use to apply a pure transformation to an `Option`'s present value, especially
+   * when chaining transformations in a pipeline.
    *
    * **Details**
    *
@@ -1635,8 +1642,8 @@ export const map: {
    *
    * **When to use**
    *
-   * Use to apply a pure transformation to an optional value, especially when
-   * chaining transformations in a pipeline.
+   * Use to apply a pure transformation to an `Option`'s present value, especially
+   * when chaining transformations in a pipeline.
    *
    * **Details**
    *
@@ -1672,12 +1679,8 @@ export const map: {
  *
  * **When to use**
  *
- * Use when preserving presence/absence while discarding the original value
- *
- * **Details**
- *
- * - `Some` → `Some(b)`
- * - `None` → `None`
+ * Use when you need to replace a present `Option` value while preserving
+ * whether it was `Some` or `None`.
  *
  * **Example** (Replacing a value)
  *
@@ -1703,12 +1706,8 @@ export const as: {
    *
    * **When to use**
    *
-   * Use when preserving presence/absence while discarding the original value
-   *
-   * **Details**
-   *
-   * - `Some` → `Some(b)`
-   * - `None` → `None`
+   * Use when you need to replace a present `Option` value while preserving
+   * whether it was `Some` or `None`.
    *
    * **Example** (Replacing a value)
    *
@@ -1734,12 +1733,8 @@ export const as: {
    *
    * **When to use**
    *
-   * Use when preserving presence/absence while discarding the original value
-   *
-   * **Details**
-   *
-   * - `Some` → `Some(b)`
-   * - `None` → `None`
+   * Use when you need to replace a present `Option` value while preserving
+   * whether it was `Some` or `None`.
    *
    * **Example** (Replacing a value)
    *
@@ -1768,12 +1763,8 @@ export const as: {
  *
  * **When to use**
  *
- * Use when discarding the value while preserving presence/absence
- *
- * **Details**
- *
- * - `Some` → `Some(undefined)`
- * - `None` → `None`
+ * Use when you need to discard a present `Option` value while preserving
+ * whether it was `Some` or `None`.
  *
  * **Example** (Voiding the value)
  *
@@ -1826,8 +1817,8 @@ export {
  *
  * **When to use**
  *
- * Use when chaining dependent optional computations where each step may return
- * `None`.
+ * Use when you need to chain dependent `Option` computations where each step
+ * may return `None`.
  *
  * **Details**
  *
@@ -1872,8 +1863,8 @@ export const flatMap: {
    *
    * **When to use**
    *
-   * Use when chaining dependent optional computations where each step may return
-   * `None`.
+   * Use when you need to chain dependent `Option` computations where each step
+   * may return `None`.
    *
    * **Details**
    *
@@ -1918,8 +1909,8 @@ export const flatMap: {
    *
    * **When to use**
    *
-   * Use when chaining dependent optional computations where each step may return
-   * `None`.
+   * Use when you need to chain dependent `Option` computations where each step
+   * may return `None`.
    *
    * **Details**
    *
@@ -1969,8 +1960,8 @@ export const flatMap: {
  *
  * **When to use**
  *
- * Use when flexible chaining where the next step may return `Option`, a plain value,
- *   or a function
+ * Use when you need to chain an `Option` with a next step that may be another
+ * `Option`, a plain value, or a function.
  *
  * **Details**
  *
@@ -2010,8 +2001,8 @@ export const andThen: {
    *
    * **When to use**
    *
-   * Use when flexible chaining where the next step may return `Option`, a plain value,
-   *   or a function
+   * Use when you need to chain an `Option` with a next step that may be another
+   * `Option`, a plain value, or a function.
    *
    * **Details**
    *
@@ -2051,8 +2042,8 @@ export const andThen: {
    *
    * **When to use**
    *
-   * Use when flexible chaining where the next step may return `Option`, a plain value,
-   *   or a function
+   * Use when you need to chain an `Option` with a next step that may be another
+   * `Option`, a plain value, or a function.
    *
    * **Details**
    *
@@ -2092,8 +2083,8 @@ export const andThen: {
    *
    * **When to use**
    *
-   * Use when flexible chaining where the next step may return `Option`, a plain value,
-   *   or a function
+   * Use when you need to chain an `Option` with a next step that may be another
+   * `Option`, a plain value, or a function.
    *
    * **Details**
    *
@@ -2133,8 +2124,8 @@ export const andThen: {
    *
    * **When to use**
    *
-   * Use when flexible chaining where the next step may return `Option`, a plain value,
-   *   or a function
+   * Use when you need to chain an `Option` with a next step that may be another
+   * `Option`, a plain value, or a function.
    *
    * **Details**
    *
@@ -2174,8 +2165,8 @@ export const andThen: {
    *
    * **When to use**
    *
-   * Use when flexible chaining where the next step may return `Option`, a plain value,
-   *   or a function
+   * Use when you need to chain an `Option` with a next step that may be another
+   * `Option`, a plain value, or a function.
    *
    * **Details**
    *
@@ -2215,8 +2206,8 @@ export const andThen: {
    *
    * **When to use**
    *
-   * Use when flexible chaining where the next step may return `Option`, a plain value,
-   *   or a function
+   * Use when you need to chain an `Option` with a next step that may be another
+   * `Option`, a plain value, or a function.
    *
    * **Details**
    *
@@ -2256,8 +2247,8 @@ export const andThen: {
    *
    * **When to use**
    *
-   * Use when flexible chaining where the next step may return `Option`, a plain value,
-   *   or a function
+   * Use when you need to chain an `Option` with a next step that may be another
+   * `Option`, a plain value, or a function.
    *
    * **Details**
    *
@@ -2297,8 +2288,8 @@ export const andThen: {
    *
    * **When to use**
    *
-   * Use when flexible chaining where the next step may return `Option`, a plain value,
-   *   or a function
+   * Use when you need to chain an `Option` with a next step that may be another
+   * `Option`, a plain value, or a function.
    *
    * **Details**
    *
@@ -2347,8 +2338,8 @@ export const andThen: {
  *
  * **When to use**
  *
- * Use when chaining with functions that use `null`/`undefined` instead of `Option`
- * - Navigating deeply nested optional properties
+ * Use when you need to chain optional computations that use `null` or
+ * `undefined` instead of `Option`, such as nested property access.
  *
  * **Details**
  *
@@ -2389,8 +2380,8 @@ export const flatMapNullishOr: {
    *
    * **When to use**
    *
-   * Use when chaining with functions that use `null`/`undefined` instead of `Option`
-   * - Navigating deeply nested optional properties
+   * Use when you need to chain optional computations that use `null` or
+   * `undefined` instead of `Option`, such as nested property access.
    *
    * **Details**
    *
@@ -2431,8 +2422,8 @@ export const flatMapNullishOr: {
    *
    * **When to use**
    *
-   * Use when chaining with functions that use `null`/`undefined` instead of `Option`
-   * - Navigating deeply nested optional properties
+   * Use when you need to chain optional computations that use `null` or
+   * `undefined` instead of `Option`, such as nested property access.
    *
    * **Details**
    *
@@ -2478,7 +2469,7 @@ export const flatMapNullishOr: {
  *
  * **When to use**
  *
- * Use when removing one layer of `Option` nesting
+ * Use when you need to remove one layer of nested `Option`.
  *
  * **Details**
  *
@@ -2510,7 +2501,8 @@ export const flatten: <A>(self: Option<Option<A>>) => Option<A> = flatMap(identi
  *
  * **When to use**
  *
- * Use to run a side-condition that must succeed, then using the second value
+ * Use when you need two `Option` values to both be `Some`, then keep only the
+ * second value.
  *
  * **Details**
  *
@@ -2541,7 +2533,8 @@ export const zipRight: {
    *
    * **When to use**
    *
-   * Use to run a side-condition that must succeed, then using the second value
+   * Use when you need two `Option` values to both be `Some`, then keep only the
+   * second value.
    *
    * **Details**
    *
@@ -2572,7 +2565,8 @@ export const zipRight: {
    *
    * **When to use**
    *
-   * Use to run a side-condition that must succeed, then using the second value
+   * Use when you need two `Option` values to both be `Some`, then keep only the
+   * second value.
    *
    * **Details**
    *
@@ -2605,7 +2599,8 @@ export const zipRight: {
  *
  * **When to use**
  *
- * Use to run a validation that must succeed, but keeping the original value
+ * Use when you need two `Option` values to both be `Some`, then keep only the
+ * first value.
  *
  * **Details**
  *
@@ -2636,7 +2631,8 @@ export const zipLeft: {
    *
    * **When to use**
    *
-   * Use to run a validation that must succeed, but keeping the original value
+   * Use when you need two `Option` values to both be `Some`, then keep only the
+   * first value.
    *
    * **Details**
    *
@@ -2667,7 +2663,8 @@ export const zipLeft: {
    *
    * **When to use**
    *
-   * Use to run a validation that must succeed, but keeping the original value
+   * Use when you need two `Option` values to both be `Some`, then keep only the
+   * first value.
    *
    * **Details**
    *
@@ -2701,7 +2698,8 @@ export const zipLeft: {
  *
  * **When to use**
  *
- * Use to build pipelines of partial functions (Kleisli composition)
+ * Use when you need to compose two functions that each return an `Option`, so
+ * `None` short-circuits without calling the next function.
  *
  * **Details**
  *
@@ -2740,7 +2738,8 @@ export const composeK: {
    *
    * **When to use**
    *
-   * Use to build pipelines of partial functions (Kleisli composition)
+   * Use when you need to compose two functions that each return an `Option`, so
+   * `None` short-circuits without calling the next function.
    *
    * **Details**
    *
@@ -2779,7 +2778,8 @@ export const composeK: {
    *
    * **When to use**
    *
-   * Use to build pipelines of partial functions (Kleisli composition)
+   * Use when you need to compose two functions that each return an `Option`, so
+   * `None` short-circuits without calling the next function.
    *
    * **Details**
    *
@@ -2821,8 +2821,8 @@ export const composeK: {
  *
  * **When to use**
  *
- * Use to validate a value without transforming it
- * - Adding a side-condition check in a pipeline
+ * Use to validate an `Option`'s present value without transforming it, such as
+ * adding a side-condition check in a pipeline.
  *
  * **Details**
  *
@@ -2858,8 +2858,8 @@ export const tap: {
    *
    * **When to use**
    *
-   * Use to validate a value without transforming it
-   * - Adding a side-condition check in a pipeline
+   * Use to validate an `Option`'s present value without transforming it, such as
+   * adding a side-condition check in a pipeline.
    *
    * **Details**
    *
@@ -2895,8 +2895,8 @@ export const tap: {
    *
    * **When to use**
    *
-   * Use to validate a value without transforming it
-   * - Adding a side-condition check in a pipeline
+   * Use to validate an `Option`'s present value without transforming it, such as
+   * adding a side-condition check in a pipeline.
    *
    * **Details**
    *
@@ -2933,7 +2933,8 @@ export const tap: {
  *
  * **When to use**
  *
- * Use when pairing two optional values together
+ * Use when you need to require two `Option` values to both be `Some` and keep
+ * both values as a tuple.
  *
  * **Details**
  *
@@ -2967,7 +2968,8 @@ export const product = <A, B>(self: Option<A>, that: Option<B>): Option<[A, B]>
  *
  * **When to use**
  *
- * Use when collecting several `Option`s of the same type into a non-empty tuple
+ * Use when you need several `Option` values of the same type to all be `Some`
+ * and return them as a non-empty tuple.
  *
  * **Details**
  *
@@ -3018,8 +3020,8 @@ export const productMany = <A>(
  *
  * **When to use**
  *
- * Use when collecting multiple `Option`s into one, preserving the input shape
- * - "All or nothing" combination — any `None` makes the result `None`
+ * Use when you need to combine multiple `Option` values into one while
+ * preserving the input shape, with any `None` making the result `None`.
  *
  * **Details**
  *
@@ -3094,7 +3096,8 @@ export const all: <const I extends Iterable<Option<any>> | Record<string, Option
  *
  * **When to use**
  *
- * Use when merging two optional values into a computed result
+ * Use when you need to combine two present `Option` values into a computed
+ * result.
  *
  * **Details**
  *
@@ -3129,7 +3132,8 @@ export const zipWith: {
    *
    * **When to use**
    *
-   * Use when merging two optional values into a computed result
+   * Use when you need to combine two present `Option` values into a computed
+   * result.
    *
    * **Details**
    *
@@ -3164,7 +3168,8 @@ export const zipWith: {
    *
    * **When to use**
    *
-   * Use when merging two optional values into a computed result
+   * Use when you need to combine two present `Option` values into a computed
+   * result.
    *
    * **Details**
    *
@@ -3205,7 +3210,8 @@ export const zipWith: {
  *
  * **When to use**
  *
- * Use when aggregating values from a collection where some may be absent
+ * Use when you need to aggregate values from a collection where some may be
+ * absent.
  *
  * **Details**
  *
@@ -3233,7 +3239,8 @@ export const reduceCompact: {
    *
    * **When to use**
    *
-   * Use when aggregating values from a collection where some may be absent
+   * Use when you need to aggregate values from a collection where some may be
+   * absent.
    *
    * **Details**
    *
@@ -3261,7 +3268,8 @@ export const reduceCompact: {
    *
    * **When to use**
    *
-   * Use when aggregating values from a collection where some may be absent
+   * Use when you need to aggregate values from a collection where some may be
+   * absent.
    *
    * **Details**
    *
@@ -3302,8 +3310,8 @@ export const reduceCompact: {
  *
  * **When to use**
  *
- * Use when interfacing with array-based APIs
- * - Spreading optional values into collections
+ * Use when you need to pass an `Option` to array-based APIs or spread optional
+ * values into collections.
  *
  * **Details**
  *
@@ -3334,7 +3342,8 @@ export const toArray = <A>(self: Option<A>): Array<A> => isNone(self) ? [] : [se
  *
  * **When to use**
  *
- * Use when categorizing an optional value into "left" (failure) and "right" (success) channels
+ * Use when you need to split an optional value into "left" and "right"
+ * channels using a `Result`-returning function.
  *
  * **Details**
  *
@@ -3373,7 +3382,8 @@ export const partitionMap: {
    *
    * **When to use**
    *
-   * Use when categorizing an optional value into "left" (failure) and "right" (success) channels
+   * Use when you need to split an optional value into "left" and "right"
+   * channels using a `Result`-returning function.
    *
    * **Details**
    *
@@ -3412,7 +3422,8 @@ export const partitionMap: {
    *
    * **When to use**
    *
-   * Use when categorizing an optional value into "left" (failure) and "right" (success) channels
+   * Use when you need to split an optional value into "left" and "right"
+   * channels using a `Result`-returning function.
    *
    * **Details**
    *
@@ -3462,7 +3473,8 @@ export const partitionMap: {
  *
  * **When to use**
  *
- * Use to transform a present value and discard it when the `Filter` fails.
+ * Use to transform an `Option`'s present value and discard it when the `Filter`
+ * fails.
  *
  * **Details**
  *
@@ -3492,7 +3504,8 @@ export const filterMap: {
    *
    * **When to use**
    *
-   * Use to transform a present value and discard it when the `Filter` fails.
+   * Use to transform an `Option`'s present value and discard it when the `Filter`
+   * fails.
    *
    * **Details**
    *
@@ -3522,7 +3535,8 @@ export const filterMap: {
    *
    * **When to use**
    *
-   * Use to transform a present value and discard it when the `Filter` fails.
+   * Use to transform an `Option`'s present value and discard it when the `Filter`
+   * fails.
    *
    * **Details**
    *
@@ -3561,8 +3575,8 @@ export const filterMap: {
  *
  * **When to use**
  *
- * Use when discarding values that don't meet a condition
- * - Narrowing the type via a refinement predicate
+ * Use when you need to discard an `Option`'s present value when it does not
+ * meet a condition, while narrowing the type via a refinement predicate.
  *
  * **Details**
  *
@@ -3602,8 +3616,8 @@ export const filter: {
    *
    * **When to use**
    *
-   * Use when discarding values that don't meet a condition
-   * - Narrowing the type via a refinement predicate
+   * Use when you need to discard an `Option`'s present value when it does not
+   * meet a condition, while narrowing the type via a refinement predicate.
    *
    * **Details**
    *
@@ -3643,8 +3657,8 @@ export const filter: {
    *
    * **When to use**
    *
-   * Use when discarding values that don't meet a condition
-   * - Narrowing the type via a refinement predicate
+   * Use when you need to discard an `Option`'s present value when it does not
+   * meet a condition, while narrowing the type via a refinement predicate.
    *
    * **Details**
    *
@@ -3684,8 +3698,8 @@ export const filter: {
    *
    * **When to use**
    *
-   * Use when discarding values that don't meet a condition
-   * - Narrowing the type via a refinement predicate
+   * Use when you need to discard an `Option`'s present value when it does not
+   * meet a condition, while narrowing the type via a refinement predicate.
    *
    * **Details**
    *
@@ -3725,8 +3739,8 @@ export const filter: {
    *
    * **When to use**
    *
-   * Use when discarding values that don't meet a condition
-   * - Narrowing the type via a refinement predicate
+   * Use when you need to discard an `Option`'s present value when it does not
+   * meet a condition, while narrowing the type via a refinement predicate.
    *
    * **Details**
    *
@@ -3771,7 +3785,8 @@ export const filter: {
  *
  * **When to use**
  *
- * Use to compare two `Option` values for structural equality
+ * Use when you need equality to treat two `None` values as equal and compare
+ * two `Some` values with a supplied equality rule.
  *
  * **Details**
  *
@@ -3807,7 +3822,9 @@ export const makeEquivalence = <A>(isEquivalent: Equivalence.Equivalence<A>): Eq
  *
  * **When to use**
  *
- * Use to sort collections of `Option` values
+ * Use when you need to sort `Some` and `None` values, with `None` ordered
+ * before present values and present values compared by a supplied ordering
+ * rule.
  *
  * **Details**
  *
@@ -3843,7 +3860,8 @@ export const makeOrder = <A>(O: Order<A>): Order<Option<A>> =>
  *
  * **When to use**
  *
- * Use when reusing an existing binary function in an `Option` context
+ * Use when you need to reuse an existing binary function with two `Option`
+ * values.
  *
  * **Details**
  *
@@ -4030,7 +4048,8 @@ export const liftPredicate: { // Note: I intentionally avoid using the NoInfer p
  *
  * **When to use**
  *
- * Use when testing membership with a custom equality check
+ * Use when you need to test whether an `Option` contains a value using a
+ * custom equality check.
  *
  * **Details**
  *
@@ -4070,7 +4089,8 @@ export const containsWith = <A>(isEquivalent: (self: A, that: A) => boolean): {
  *
  * **When to use**
  *
- * Use when quick membership test with standard equality
+ * Use when you need a quick membership test for an `Option` value using
+ * standard equality.
  *
  * **Details**
  *
@@ -4105,7 +4125,8 @@ export const contains: {
    *
    * **When to use**
    *
-   * Use when quick membership test with standard equality
+   * Use when you need a quick membership test for an `Option` value using
+   * standard equality.
    *
    * **Details**
    *
@@ -4140,7 +4161,8 @@ export const contains: {
    *
    * **When to use**
    *
-   * Use when quick membership test with standard equality
+   * Use when you need a quick membership test for an `Option` value using
+   * standard equality.
    *
    * **Details**
    *
@@ -4377,7 +4399,8 @@ export const exists: {
  *
  * **When to use**
  *
- * Use when beginning a do notation chain by naming the first value
+ * Use when you need to start an `Option` do notation chain by naming the first
+ * value.
  *
  * **Example** (Starting do notation)
  *
@@ -4412,7 +4435,8 @@ export const bindTo: {
    *
    * **When to use**
    *
-   * Use when beginning a do notation chain by naming the first value
+   * Use when you need to start an `Option` do notation chain by naming the first
+   * value.
    *
    * **Example** (Starting do notation)
    *
@@ -4447,7 +4471,8 @@ export const bindTo: {
    *
    * **When to use**
    *
-   * Use when beginning a do notation chain by naming the first value
+   * Use when you need to start an `Option` do notation chain by naming the first
+   * value.
    *
    * **Example** (Starting do notation)
    *
@@ -4492,7 +4517,8 @@ export {
    *
    * **When to use**
    *
-   * Use when binding a derived (non-`Option`) value in a do notation pipeline
+   * Use when you need to bind a derived non-`Option` value in an `Option` do
+   * notation pipeline.
    *
    * **Example** (Adding a computed value)
    *
@@ -4525,7 +4551,7 @@ export {
  *
  * **When to use**
  *
- * Use when sequencing `Option` computations in do notation
+ * Use when you need to sequence `Option` computations in do notation.
  *
  * **Example** (Binding Option values)
  *
@@ -4557,7 +4583,7 @@ export const bind: {
    *
    * **When to use**
    *
-   * Use when sequencing `Option` computations in do notation
+   * Use when you need to sequence `Option` computations in do notation.
    *
    * **Example** (Binding Option values)
    *
@@ -4589,7 +4615,7 @@ export const bind: {
    *
    * **When to use**
    *
-   * Use when sequencing `Option` computations in do notation
+   * Use when you need to sequence `Option` computations in do notation.
    *
    * **Example** (Binding Option values)
    *
@@ -4627,7 +4653,8 @@ export const bind: {
  *
  * **When to use**
  *
- * Use when starting a do notation pipeline before adding bindings
+ * Use when you need to start an `Option` do notation pipeline before adding
+ * bindings.
  *
  * **Example** (Do notation pipeline)
  *
@@ -4660,8 +4687,8 @@ export const Do: Option<{}> = some({})
  *
  * **When to use**
  *
- * Use when writing imperative-style code that chains multiple `Option`s
- * - Readability when many sequential optional steps are involved
+ * Use when you need generator syntax for a sequence of `Option` steps that
+ * should short-circuit on `None`.
  *
  * **Details**
  *
@@ -4713,8 +4740,8 @@ export const gen: Gen.Gen<OptionTypeLambda> = (...args) => {
  *
  * **When to use**
  *
- * Use to build a reducer that falls back to the first available value
- * - Combining optional values where either side may be absent
+ * Use to build an `Option` reducer that falls back to the first available value
+ * when either side may be absent.
  *
  * **Details**
  *
@@ -4753,7 +4780,8 @@ export function makeReducer<A>(combiner: Combiner.Combiner<A>): Reducer.Reducer<
  *
  * **When to use**
  *
- * Use when operations that require both values to be present
+ * Use when you need an `Option` combiner that returns `None` unless both
+ * operands are `Some`.
  *
  * **Details**
  *
@@ -4792,8 +4820,8 @@ export function makeCombinerFailFast<A>(combiner: Combiner.Combiner<A>): Combine
  *
  * **When to use**
  *
- * Use to wrap an existing `Reducer` to work with `Option` values
- * - Reductions where any `None` should abort the entire result
+ * Use when you need to reduce `Option` values with fail-fast semantics, where
+ * any `None` aborts the entire result instead of being skipped.
  *
  * **Details**
  *