Repository: gcanti/fp-ts
Pull request #1748 (2022-08-23 12:52:07)

Flip the arguments of a curried function
I've been using this `flipC` in combination with `Reader`'s `local` to hide implementation details, based on https://andywhite.xyz/posts/2021-01-28-rte-react/#service-layers-and-implementation-hiding (e.g. https://github.com/PREreview/prereview.org/blob/35278c267c541586f7ca505b9bd9f5a634ec3e93/src/app.ts#L81).

This function dates back to @jskeate's suggestion in https://functionalprogramming.slack.com/archives/CPKPCAGP4/p1655736152988389?thread_ts=1655730853.886439&cid=CPKPCAGP4.

Another option could be to overload `flip`, though I've not tried that.

samhh: This is one of the few cases where I used a conflicting name in [fp-ts-std](https://samhh.github.io/fp-ts-std/modules/Function.ts.html#flip) - I don't think uncurried functions should get the proper name `flip` in a FP library.

Could we perhaps target a breaking change in 3.0 that rewrites `flip` to the curried version in this PR (and optionally renames uncurried `flip` to something else)? v3 includes [other curry-friendly breaking changes](https://github.com/gcanti/fp-ts/issues/1216).
thewilkybarkid: I've pushed 20268fc39144c5fc6fdca81bf1b9adfcf1d0c507 based on @samhh's suggestion to replace the existing `flip`: I've deprecated two arguments in favour of a new function `flipArgs`.

Not sure which approach you'd rather take @gcanti.

Patch:
diff --git a/docs-ts.json b/docs-ts.json
new file mode 100644
index 00000000..0967ef42
--- /dev/null
+++ b/docs-ts.json
@@ -0,0 +1,1 @@
+{}
diff --git a/docs/guides/code-conventions.md b/docs/guides/code-conventions.md
index 20f50ee7..377865ee 100644
--- a/docs/guides/code-conventions.md
+++ b/docs/guides/code-conventions.md
@@ -98,17 +98,29 @@ const getFunctor = <E>(S: Semigroup<E>): Functor2C<"Validation", E> = { ... }
 Both of these destructions result in a `Task<number>`, but in the case of `matchE` an effect (in this case in the form of a `Task`) is returned on match.
 
 ```ts
-import * as T from "fp-ts/Task";
-import * as TO from "fp-ts/TaskOption";
-import { pipe } from "fp-ts/function";
+import * as T from 'fp-ts/Task'
+import * as TO from 'fp-ts/TaskOption'
+import { pipe } from 'fp-ts/function'
 
-const value = TO.of("hello");
+const value = TO.of('hello')
 
 // T.Task<number>
-pipe(value, TO.match(() => 0, (str) => str.length));
+pipe(
+  value,
+  TO.match(
+    () => 0,
+    (str) => str.length
+  )
+)
 
 // T.Task<number>
-pipe(value, TO.matchE(() => T.of(0), (str) => T.of(str.length)));
+pipe(
+  value,
+  TO.matchE(
+    () => T.of(0),
+    (str) => T.of(str.length)
+  )
+)
 ```
 
 ### What a `K` suffix means, e.g. `fromEitherK` or `chainEitherK`
@@ -126,7 +138,7 @@ where `F` is a type constructor.
 Let's say we have the following parser
 
 ```ts
-import * as E from 'fp-ts/lib/Either'
+import * as E from 'fp-ts/Either'
 
 function parse(s: string): E.Either<Error, number> {
   const n = parseFloat(s)
@@ -137,7 +149,7 @@ function parse(s: string): E.Either<Error, number> {
 and a value of type `IOEither<Error, string>`
 
 ```ts
-import * as IE from 'fp-ts/lib/IOEither'
+import * as IE from 'fp-ts/IOEither'
 
 const input: IE.IOEither<Error, string> = IE.right('foo')
 ```
@@ -159,7 +171,7 @@ into a function
 That's what `fromEitherK` is all about
 
 ```ts
-import { pipe } from 'fp-ts/lib/pipeable'
+import { pipe } from 'fp-ts/function'
 
 pipe(input, IE.chain(IE.fromEitherK(parse)))() // left(new Error('cannot decode "foo" to number'))
 
@@ -180,9 +192,9 @@ However usually it means *T*ransformer like in "monad transformers" (e.g. `Optio
 **Example**
 
 ```ts
-import * as E from 'fp-ts/lib/Either'
-import * as TE from 'fp-ts/lib/TaskEither'
-import { pipe } from 'fp-ts/lib/pipeable'
+import * as E from 'fp-ts/Either'
+import * as TE from 'fp-ts/TaskEither'
+import { pipe } from 'fp-ts/pipeable'
 
 declare function parseString(s: string): E.Either<string, number>
 declare function fetchUser(id: number): TE.TaskEither<Error, User>
diff --git a/docs/guides/upgrade-to-v2.md b/docs/guides/upgrade-to-v2.md
index eba07d9f..019d19df 100644
--- a/docs/guides/upgrade-to-v2.md
+++ b/docs/guides/upgrade-to-v2.md
@@ -64,12 +64,12 @@ v1 (deprecated)
 {: .label .label-red .mt-5 }
 
 ```ts
-import * as O from 'fp-ts/lib/Option'
+import * as O from 'fp-ts/Option'
 
 O.some(1)
-  .map(n => n * 2)
-  .chain(n => (n === 0 ? O.none : O.some(1 / n)))
-  .filter(n => n > 1)
+  .map((n) => n * 2)
+  .chain((n) => (n === 0 ? O.none : O.some(1 / n)))
+  .filter((n) => n > 1)
   .foldL(
     () => 'ko',
     () => 'ok'
@@ -80,14 +80,14 @@ v2 (new)
 {: .label .label-green .mt-5 }
 
 ```ts
-import * as O from 'fp-ts/lib/Option'
-import { pipe } from 'fp-ts/lib/pipeable'
+import * as O from 'fp-ts/Option'
+import { pipe } from 'fp-ts/pipeable'
 
 pipe(
   O.some(1),
-  O.map(n => n * 2),
-  O.chain(n => (n === 0 ? O.none : O.some(1 / n))),
-  O.filter(n => n > 1),
+  O.map((n) => n * 2),
+  O.chain((n) => (n === 0 ? O.none : O.some(1 / n))),
+  O.filter((n) => n > 1),
   O.fold(
     () => 'ko',
     () => 'ok'
@@ -98,14 +98,14 @@ pipe(
 We recommend to use `pipe` even if you work with just one function, as it allows TypeScript to infer the types automatically. It's also easier to migrate existing code, because the argument order remains the same.
 
 ```ts
-import * as O from 'fp-ts/lib/Option'
-import { pipe } from 'fp-ts/lib/pipeable'
+import * as O from 'fp-ts/Option'
+import { pipe } from 'fp-ts/function'
 
 pipe(
   O.some(1),
   O.fold(
     () => 'ko',
-    n => `ok: ${n}`
+    (n) => `ok: ${n}`
   )
 )
 ```
@@ -120,11 +120,11 @@ v1 (deprecated)
 {: .label .label-red .mt-5 }
 
 ```ts
-import { Task } from 'fp-ts/lib/Task'
+import { Task } from 'fp-ts/Task'
 
 const deepThought = new Task<number>(() => Promise.resolve(42))
 
-deepThought.run().then(n => {
+deepThought.run().then((n) => {
   console.log(`The answer is ${n}.`)
 })
 ```
@@ -133,11 +133,11 @@ v2 (new)
 {: .label .label-green .mt-5 }
 
 ```ts
-import { Task } from 'fp-ts/lib/Task'
+import { Task } from 'fp-ts/Task'
 
 const deepThought: Task<number> = () => Promise.resolve(42)
 
-deepThought().then(n => {
+deepThought().then((n) => {
   console.log(`The answer is ${n}.`)
 })
 ```
@@ -150,7 +150,7 @@ v1 (deprecated)
 {: .label .label-red .mt-5 }
 
 ```ts
-import * as O from 'fp-ts/lib/Option'
+import * as O from 'fp-ts/Option'
 
 O.some(1).getOrElse(0) // Direct
 O.some(1).getOrElseL(() => 0) // Lazy, i.e. only run if needed
@@ -162,8 +162,8 @@ v2 (new)
 In `fp-ts@2.x` the API has been simplified, only the lazy variants have been kept with the `L` suffix removed.
 
 ```ts
-import * as O from 'fp-ts/lib/Option'
-import { pipe } from 'fp-ts/lib/pipeable'
+import * as O from 'fp-ts/Option'
+import { pipe } from 'fp-ts/function'
 
 pipe(
   O.some(1),
diff --git a/docs/modules/Either.ts.md b/docs/modules/Either.ts.md
index d404c10c..23253ca6 100644
--- a/docs/modules/Either.ts.md
+++ b/docs/modules/Either.ts.md
@@ -18,6 +18,53 @@ A common use of `Either` is as an alternative to `Option` for dealing with possi
 `None` is replaced with a `Left` which can contain useful information. `Right` takes the place of `Some`. Convention
 dictates that `Left` is used for failure and `Right` is used for success.
 
+**Example**
+
+```ts
+import * as E from 'fp-ts/Either'
+import { pipe } from 'fp-ts/function'
+
+const double = (n: number): number => n * 2
+
+export const imperative = (as: ReadonlyArray<number>): string => {
+  const head = (as: ReadonlyArray<number>): number => {
+    if (as.length === 0) {
+      throw new Error('empty array')
+    }
+    return as[0]
+  }
+  const inverse = (n: number): number => {
+    if (n === 0) {
+      throw new Error('cannot divide by zero')
+    }
+    return 1 / n
+  }
+  try {
+    return `Result is ${inverse(double(head(as)))}`
+  } catch (err) {
+    return `Error is ${err}`
+  }
+}
+
+export const functional = (as: ReadonlyArray<number>): string => {
+  const head = <A>(as: ReadonlyArray<A>): E.Either<string, A> =>
+    as.length === 0 ? E.left('empty array') : E.right(as[0])
+  const inverse = (n: number): E.Either<string, number> => (n === 0 ? E.left('cannot divide by zero') : E.right(1 / n))
+  return pipe(
+    as,
+    head,
+    E.map(double),
+    E.chain(inverse),
+    E.match(
+      (err) => `Error is ${err}`, // onLeft handler
+      (head) => `Result is ${head}` // onRight handler
+    )
+  )
+}
+
+assert.deepStrictEqual(imperative([1, 2, 3]), functional([1, 2, 3]))
+```
+
 Added in v2.0.0
 
 ---
@@ -215,6 +262,8 @@ Added in v2.0.0
 
 Less strict version of [`chainFirst`](#chainfirst)
 
+The `W` suffix (short for **W**idening) means that the error types will be merged.
+
 Derivable from `Chain`.
 
 **Signature**
@@ -633,18 +682,58 @@ Added in v2.10.0
 Identifies an associative operation on a type constructor. It is similar to `Semigroup`, except that it applies to
 types of kind `* -> *`.
 
+In case of `Either` returns the left-most non-`Left` value (or the right-most `Left` value if both values are `Left`).
+
 **Signature**
 
 ```ts
 export declare const alt: <E, A>(that: Lazy<Either<E, A>>) => (fa: Either<E, A>) => Either<E, A>
 ```
 
+**Example**
+
+```ts
+import * as E from 'fp-ts/Either'
+import { pipe } from 'fp-ts/function'
+
+assert.deepStrictEqual(
+  pipe(
+    E.left('a'),
+    E.alt(() => E.left('b'))
+  ),
+  E.left('b')
+)
+assert.deepStrictEqual(
+  pipe(
+    E.left('a'),
+    E.alt(() => E.right(2))
+  ),
+  E.right(2)
+)
+assert.deepStrictEqual(
+  pipe(
+    E.right(1),
+    E.alt(() => E.left('b'))
+  ),
+  E.right(1)
+)
+assert.deepStrictEqual(
+  pipe(
+    E.right(1),
+    E.alt(() => E.right(2))
+  ),
+  E.right(1)
+)
+```
+
 Added in v2.0.0
 
 ## altW
 
 Less strict version of [`alt`](#alt).
 
+The `W` suffix (short for **W**idening) means that the error and the return types will be merged.
+
 **Signature**
 
 ```ts
@@ -669,6 +758,8 @@ Added in v2.0.0
 
 Less strict version of [`ap`](#ap).
 
+The `W` suffix (short for **W**idening) means that the error types will be merged.
+
 **Signature**
 
 ```ts
@@ -705,12 +796,37 @@ Added in v2.0.0
 
 Less strict version of [`chain`](#chain).
 
+The `W` suffix (short for **W**idening) means that the error types will be merged.
+
 **Signature**
 
 ```ts
 export declare const chainW: <E2, A, B>(f: (a: A) => Either<E2, B>) => <E1>(ma: Either<E1, A>) => Either<E2 | E1, B>
 ```
 
+**Example**
+
+```ts
+import * as E from 'fp-ts/Either'
+import { pipe } from 'fp-ts/function'
+
+const e1: E.Either<string, number> = E.right(1)
+const e2: E.Either<number, number> = E.right(2)
+
+export const result1 = pipe(
+  // @ts-expect-error
+  e1,
+  E.chain(() => e2)
+)
+
+// merged error types -----v-------------v
+// const result2: E.Either<string | number, number>
+export const result2 = pipe(
+  e1, // no error
+  E.chainW(() => e2)
+)
+```
+
 Added in v2.6.0
 
 ## extend
@@ -1497,6 +1613,8 @@ Added in v2.8.0
 
 ## apSW
 
+The `W` suffix (short for **W**idening) means that the error types will be merged.
+
 **Signature**
 
 ```ts
diff --git a/docs/modules/EitherT.ts.md b/docs/modules/EitherT.ts.md
index 39d612cd..96716051 100644
--- a/docs/modules/EitherT.ts.md
+++ b/docs/modules/EitherT.ts.md
@@ -6,6 +6,10 @@ parent: Modules
 
 ## EitherT overview
 
+The error monad transformer. It can be used to add error handling to other monads.
+
+The `of` function yields a successful computation, while `chain` sequences two subcomputations, failing on the first error.
+
 Added in v2.0.0
 
 ---
diff --git a/docs/modules/IOEither.ts.md b/docs/modules/IOEither.ts.md
index 3992c5bb..d781398f 100644
--- a/docs/modules/IOEither.ts.md
+++ b/docs/modules/IOEither.ts.md
@@ -158,6 +158,8 @@ Added in v2.0.0
 
 Less strict version of [`alt`](#alt).
 
+The `W` suffix (short for **W**idening) means that the error and the return types will be merged.
+
 **Signature**
 
 ```ts
@@ -184,6 +186,8 @@ Added in v2.0.0
 
 Less strict version of [`ap`](#ap).
 
+The `W` suffix (short for **W**idening) means that the error types will be merged.
+
 **Signature**
 
 ```ts
@@ -253,6 +257,8 @@ Added in v2.0.0
 
 Less strict version of [`chain`](#chain).
 
+The `W` suffix (short for **W**idening) means that the error types will be merged.
+
 **Signature**
 
 ```ts
@@ -359,6 +365,8 @@ Added in v2.4.0
 
 Less strict version of [`chainEitherK`](#chaineitherk).
 
+The `W` suffix (short for **W**idening) means that the error types will be merged.
+
 **Signature**
 
 ```ts
@@ -396,6 +404,8 @@ Added in v2.12.0
 
 ## chainFirstEitherKW
 
+The `W` suffix (short for **W**idening) means that the error types will be merged.
+
 **Signature**
 
 ```ts
@@ -420,6 +430,8 @@ Added in v2.10.0
 
 Less strict version of [`chainFirst`](#chainfirst).
 
+The `W` suffix (short for **W**idening) means that the error types will be merged.
+
 Derivable from `Chain`.
 
 **Signature**
@@ -1191,6 +1203,8 @@ Added in v2.8.0
 
 ## apSW
 
+The `W` suffix (short for **W**idening) means that the error types will be merged.
+
 **Signature**
 
 ```ts
diff --git a/docs/modules/IOOption.ts.md b/docs/modules/IOOption.ts.md
index 2917c8a3..0c0a3552 100644
--- a/docs/modules/IOOption.ts.md
+++ b/docs/modules/IOOption.ts.md
@@ -121,6 +121,8 @@ Added in v2.12.0
 
 Less strict version of [`alt`](#alt).
 
+The `W` suffix (short for **W**idening) means that the return types will be merged.
+
 **Signature**
 
 ```ts
diff --git a/docs/modules/Identity.ts.md b/docs/modules/Identity.ts.md
index 7d233d31..434a6ed8 100644
--- a/docs/modules/Identity.ts.md
+++ b/docs/modules/Identity.ts.md
@@ -86,6 +86,8 @@ Added in v2.0.0
 
 Less strict version of [`alt`](#alt).
 
+The `W` suffix (short for **W**idening) means that the return types will be merged.
+
 **Signature**
 
 ```ts
diff --git a/docs/modules/Option.ts.md b/docs/modules/Option.ts.md
index 6d759a6f..92da8723 100644
--- a/docs/modules/Option.ts.md
+++ b/docs/modules/Option.ts.md
@@ -17,6 +17,52 @@ instance of `None`.
 An option could be looked at as a collection or foldable structure with either one or zero elements.
 Another way to look at `Option` is: it represents the effect of a possibly failing computation.
 
+**Example**
+
+```ts
+import * as O from 'fp-ts/Option'
+import { pipe } from 'fp-ts/function'
+
+const double = (n: number): number => n * 2
+
+export const imperative = (as: ReadonlyArray<number>): string => {
+  const head = (as: ReadonlyArray<number>): number => {
+    if (as.length === 0) {
+      throw new Error()
+    }
+    return as[0]
+  }
+  const inverse = (n: number): number => {
+    if (n === 0) {
+      throw new Error()
+    }
+    return 1 / n
+  }
+  try {
+    return `Result is ${inverse(double(head(as)))}`
+  } catch (e) {
+    return 'no result'
+  }
+}
+
+export const functional = (as: ReadonlyArray<number>): string => {
+  const head = <A>(as: ReadonlyArray<A>): O.Option<A> => (as.length === 0 ? O.none : O.some(as[0]))
+  const inverse = (n: number): O.Option<number> => (n === 0 ? O.none : O.some(1 / n))
+  return pipe(
+    as,
+    head,
+    O.map(double),
+    O.chain(inverse),
+    O.match(
+      () => 'no result', // onNone handler
+      (head) => `Result is ${head}` // onSome handler
+    )
+  )
+}
+
+assert.deepStrictEqual(imperative([1, 2, 3]), functional([1, 2, 3]))
+```
+
 Added in v2.0.0
 
 ---
@@ -511,10 +557,10 @@ import { pipe } from 'fp-ts/function'
 
 assert.deepStrictEqual(
   pipe(
-    O.some('a'),
-    O.alt(() => O.some('b'))
+    O.none,
+    O.alt(() => O.none)
   ),
-  O.some('a')
+  O.none
 )
 assert.deepStrictEqual(
   pipe(
@@ -523,6 +569,20 @@ assert.deepStrictEqual(
   ),
   O.some('b')
 )
+assert.deepStrictEqual(
+  pipe(
+    O.some('a'),
+    O.alt<string>(() => O.none)
+  ),
+  O.some('a')
+)
+assert.deepStrictEqual(
+  pipe(
+    O.some('a'),
+    O.alt(() => O.some('b'))
+  ),
+  O.some('a')
+)
 ```
 
 Added in v2.0.0
@@ -531,6 +591,8 @@ Added in v2.0.0
 
 Less strict version of [`alt`](#alt).
 
+The `W` suffix (short for **W**idening) means that the return types will be merged.
+
 **Signature**
 
 ```ts
diff --git a/docs/modules/Reader.ts.md b/docs/modules/Reader.ts.md
index 6e8e23f2..c4d8c690 100644
--- a/docs/modules/Reader.ts.md
+++ b/docs/modules/Reader.ts.md
@@ -6,6 +6,46 @@ parent: Modules
 
 ## Reader overview
 
+The `Reader` monad (also called the Environment monad). Represents a computation, which can read values from a shared environment,
+pass values from function to function, and execute sub-computations in a modified environment.
+Using `Reader` monad for such computations is often clearer and easier than using the `State` monad.
+
+In this example the `Reader` monad provides access to variable bindings. `Bindings` are a map of `number` variables.
+The variable count contains number of variables in the bindings. You can see how to run a `Reader` monad and retrieve
+data from it, how to access the `Reader` data with `ask` and `asks`.
+
+**Example**
+
+```ts
+import { pipe } from 'fp-ts/function'
+import * as O from 'fp-ts/Option'
+import * as R from 'fp-ts/Reader'
+import * as RR from 'fp-ts/ReadonlyRecord'
+
+interface Bindings extends RR.ReadonlyRecord<string, number> {}
+
+// The Reader monad, which implements this complicated check.
+const isCountCorrect: R.Reader<Bindings, boolean> = pipe(
+  R.Do,
+  R.bind('count', () => R.asks(lookupVar('count'))),
+  R.bind('bindings', () => R.ask()),
+  R.map(({ count, bindings }) => count === RR.size(bindings))
+)
+
+// The selector function to use with 'asks'.
+// Returns value of the variable with specified name.
+const lookupVar = (name: string) => (bindings: Bindings): number =>
+  pipe(
+    bindings,
+    RR.lookup(name),
+    O.getOrElse(() => 0)
+  )
+
+const sampleBindings: Bindings = { count: 3, a: 1, b: 2 }
+
+assert.deepStrictEqual(isCountCorrect(sampleBindings), true)
+```
+
 Added in v2.0.0
 
 ---
@@ -102,6 +142,8 @@ Added in v2.0.0
 
 Less strict version of [`ap`](#ap).
 
+The `W` suffix (short for **W**idening) means that the environment types will be merged.
+
 **Signature**
 
 ```ts
@@ -177,6 +219,8 @@ Added in v2.0.0
 
 Less strict version of [`chain`](#chain).
 
+The `W` suffix (short for **W**idening) means that the environment types will be merged.
+
 **Signature**
 
 ```ts
@@ -340,6 +384,8 @@ Added in v2.0.0
 
 Less strict version of [`chainFirst`](#chainfirst).
 
+The `W` suffix (short for **W**idening) means that the environment types will be merged.
+
 Derivable from `Chain`.
 
 **Signature**
@@ -399,6 +445,33 @@ Changes the value of the local context during the execution of the action `ma` (
 export declare const local: <R2, R1>(f: (r2: R2) => R1) => <A>(ma: Reader<R1, A>) => Reader<R2, A>
 ```
 
+**Example**
+
+```ts
+import { pipe } from 'fp-ts/function'
+import * as R from 'fp-ts/Reader'
+import * as string from 'fp-ts/string'
+
+const calculateContentLen: R.Reader<string, number> = pipe(
+  R.Do,
+  R.bind('content', () => R.ask<string>()),
+  R.map(({ content }) => string.size(content))
+)
+
+// Calls calculateContentLen after adding a prefix to the Reader content.
+const calculateModifiedContentLen: R.Reader<string, number> = pipe(
+  calculateContentLen,
+  R.local((s) => 'Prefix ' + s)
+)
+
+const s = '12345'
+
+assert.deepStrictEqual(
+  "Modified 's' length: " + calculateModifiedContentLen(s) + '\n' + "Original 's' length: " + calculateContentLen(s),
+  "Modified 's' length: 12\nOriginal 's' length: 5"
+)
+```
+
 Added in v2.0.0
 
 # constructors
@@ -642,6 +715,8 @@ Added in v2.8.0
 
 ## apSW
 
+The `W` suffix (short for **W**idening) means that the environment types will be merged.
+
 **Signature**
 
 ```ts
diff --git a/docs/modules/ReaderEither.ts.md b/docs/modules/ReaderEither.ts.md
index 6c6df6dc..a727db0f 100644
--- a/docs/modules/ReaderEither.ts.md
+++ b/docs/modules/ReaderEither.ts.md
@@ -148,6 +148,8 @@ Added in v2.0.0
 
 Less strict version of [`alt`](#alt).
 
+The `W` suffix (short for **W**idening) means that the environment, the error and the return types will be merged.
+
 **Signature**
 
 ```ts
@@ -178,6 +180,8 @@ Added in v2.0.0
 
 Less strict version of [`ap`](#ap).
 
+The `W` suffix (short for **W**idening) means that the environment types and the error types will be merged.
+
 **Signature**
 
 ```ts
@@ -252,6 +256,8 @@ Added in v2.0.0
 
 Less strict version of [`chain`](#chain).
 
+The `W` suffix (short for **W**idening) means that the error types will be merged.
+
 **Signature**
 
 ```ts
@@ -390,6 +396,8 @@ Added in v2.4.0
 
 Less strict version of [`chainEitherK`](#chaineitherk).
 
+The `W` suffix (short for **W**idening) means that the error types will be merged.
+
 **Signature**
 
 ```ts
@@ -433,6 +441,8 @@ Added in v2.12.0
 
 Less strict version of [`chainFirstEitherK`](#chainfirsteitherk).
 
+The `W` suffix (short for **W**idening) means that the environment types will be merged.
+
 **Signature**
 
 ```ts
@@ -459,6 +469,8 @@ Added in v2.11.0
 
 Less strict version of [`chainReaderK`](#chainreaderk).
 
+The `W` suffix (short for **W**idening) means that the environment types will be merged.
+
 **Signature**
 
 ```ts
@@ -473,6 +485,8 @@ Added in v2.11.0
 
 Less strict version of [`chainFirst`](#chainfirst)
 
+The `W` suffix (short for **W**idening) means that the environment types and the error types will be merged.
+
 Derivable from `Chain`.
 
 **Signature**
@@ -513,6 +527,8 @@ Added in v2.11.0
 
 Less strict version of [`chainReaderK`](#chainreaderk).
 
+The `W` suffix (short for **W**idening) means that the environment types will be merged.
+
 **Signature**
 
 ```ts
@@ -1248,6 +1264,8 @@ Added in v2.8.0
 
 ## apSW
 
+The `W` suffix (short for **W**idening) means that the environment types and the error types will be merged.
+
 **Signature**
 
 ```ts
diff --git a/docs/modules/ReaderT.ts.md b/docs/modules/ReaderT.ts.md
index 97a97aa9..c90a857e 100644
--- a/docs/modules/ReaderT.ts.md
+++ b/docs/modules/ReaderT.ts.md
@@ -6,6 +6,10 @@ parent: Modules
 
 ## ReaderT overview
 
+The reader monad transformer, which adds a read-only environment to the given monad.
+
+The `of` function ignores the environment, while `chain` passes the inherited environment to both subcomputations.
+
 Added in v2.0.0
 
 ---
diff --git a/docs/modules/ReaderTask.ts.md b/docs/modules/ReaderTask.ts.md
index 684a08f0..33e3692a 100644
--- a/docs/modules/ReaderTask.ts.md
+++ b/docs/modules/ReaderTask.ts.md
@@ -113,6 +113,8 @@ Added in v2.3.0
 
 Less strict version of [`ap`](#ap).
 
+The `W` suffix (short for **W**idening) means that the environment types will be merged.
+
 **Signature**
 
 ```ts
@@ -156,6 +158,8 @@ Added in v2.3.0
 
 Less strict version of [`chain`](#chain).
 
+The `W` suffix (short for **W**idening) means that the environment types will be merged.
+
 **Signature**
 
 ```ts
@@ -224,6 +228,8 @@ Added in v2.11.0
 
 Less strict version of [`asksReaderTask`](#asksreadertask).
 
+The `W` suffix (short for **W**idening) means that the environment types will be merged.
+
 **Signature**
 
 ```ts
@@ -275,6 +281,8 @@ Added in v2.11.0
 
 Less strict version of [`chainFirstReaderK`](#chainfirstreaderk).
 
+The `W` suffix (short for **W**idening) means that the environment types will be merged.
+
 **Signature**
 
 ```ts
@@ -299,6 +307,8 @@ Added in v2.10.0
 
 Less strict version of [`chainFirst`](#chainfirst).
 
+The `W` suffix (short for **W**idening) means that the environment types will be merged.
+
 Derivable from `Chain`.
 
 **Signature**
@@ -335,6 +345,8 @@ Added in v2.11.0
 
 Less strict version of [`chainReaderK`](#chainreaderk).
 
+The `W` suffix (short for **W**idening) means that the environment types will be merged.
+
 **Signature**
 
 ```ts
@@ -747,6 +759,8 @@ Added in v2.8.0
 
 ## apSW
 
+The `W` suffix (short for **W**idening) means that the environment types will be merged.
+
 **Signature**
 
 ```ts
diff --git a/docs/modules/ReaderTaskEither.ts.md b/docs/modules/ReaderTaskEither.ts.md
index 7b23ba8b..52364bb4 100644
--- a/docs/modules/ReaderTaskEither.ts.md
+++ b/docs/modules/ReaderTaskEither.ts.md
@@ -201,6 +201,8 @@ Added in v2.0.0
 
 Less strict version of [`alt`](#alt).
 
+The `W` suffix (short for **W**idening) means that the environment, the error and the return types will be merged.
+
 **Signature**
 
 ```ts
@@ -231,6 +233,8 @@ Added in v2.0.0
 
 Less strict version of [`ap`](#ap).
 
+The `W` suffix (short for **W**idening) means that the environment types and the error types will be merged.
+
 **Signature**
 
 ```ts
@@ -307,6 +311,8 @@ Added in v2.0.0
 
 Less strict version of [`chain`](#chain).
 
+The `W` suffix (short for **W**idening) means that the environment types and the error types will be merged.
+
 **Signature**
 
 ```ts
@@ -447,6 +453,8 @@ Added in v2.4.0
 
 Less strict version of [`chainEitherK`](#chaineitherk).
 
+The `W` suffix (short for **W**idening) means that the environment types and the error types will be merged.
+
 **Signature**
 
 ```ts
@@ -490,6 +498,8 @@ Added in v2.12.0
 
 Less strict version of [`chainFirstEitherK`](#chainfirsteitherk).
 
+The `W` suffix (short for **W**idening) means that the environment types and the error types will be merged.
+
 **Signature**
 
 ```ts
@@ -528,6 +538,8 @@ Added in v2.11.0
 
 Less strict version of [`chainFirstReaderEitherK`](#chainfirstreadereitherk).
 
+The `W` suffix (short for **W**idening) means that the environment types and the error types will be merged.
+
 **Signature**
 
 ```ts
@@ -554,6 +566,8 @@ Added in v2.11.0
 
 Less strict version of [`chainFirstReaderK`](#chainfirstreaderk).
 
+The `W` suffix (short for **W**idening) means that the environment types and the error types will be merged.
+
 **Signature**
 
 ```ts
@@ -580,6 +594,8 @@ Added in v2.11.0
 
 Less strict version of [`chainFirstReaderTaskK`](#chainfirstreadertaskk).
 
+The `W` suffix (short for **W**idening) means that the environment types and the error types will be merged.
+
 **Signature**
 
 ```ts
@@ -606,6 +622,8 @@ Added in v2.11.0
 
 Less strict version of [`chainFirstTaskEitherK`](#chainfirsttaskeitherk).
 
+The `W` suffix (short for **W**idening) means that the environment types and the error types will be merged.
+
 **Signature**
 
 ```ts
@@ -632,6 +650,8 @@ Added in v2.10.0
 
 Less strict version of [`chainFirst`](#chainfirst).
 
+The `W` suffix (short for **W**idening) means that the environment types and the error types will be merged.
+
 Derivable from `Chain`.
 
 **Signature**
@@ -660,6 +680,8 @@ Added in v2.4.0
 
 Less strict version of [`chainIOEitherK`](#chainioeitherk).
 
+The `W` suffix (short for **W**idening) means that the environment types and the error types will be merged.
+
 **Signature**
 
 ```ts
@@ -710,6 +732,8 @@ Added in v2.11.0
 
 Less strict version of [`chainReaderEitherK`](#chainreadereitherk).
 
+The `W` suffix (short for **W**idening) means that the environment types and the error types will be merged.
+
 **Signature**
 
 ```ts
@@ -736,6 +760,8 @@ Added in v2.11.0
 
 Less strict version of [`chainReaderK`](#chainreaderk).
 
+The `W` suffix (short for **W**idening) means that the environment types and the error types will be merged.
+
 **Signature**
 
 ```ts
@@ -762,6 +788,8 @@ Added in v2.11.0
 
 Less strict version of [`chainReaderTaskK`](#chainreadertaskk).
 
+The `W` suffix (short for **W**idening) means that the environment types and the error types will be merged.
+
 **Signature**
 
 ```ts
@@ -788,6 +816,8 @@ Added in v2.4.0
 
 Less strict version of [`chainTaskEitherK`](#chaintaskeitherk).
 
+The `W` suffix (short for **W**idening) means that the environment types and the error types will be merged.
+
 **Signature**
 
 ```ts
@@ -1841,6 +1871,8 @@ Added in v2.8.0
 
 ## apSW
 
+The `W` suffix (short for **W**idening) means that the environment types and the error types will be merged.
+
 **Signature**
 
 ```ts
diff --git a/docs/modules/StateReaderTaskEither.ts.md b/docs/modules/StateReaderTaskEither.ts.md
index aba9dfb9..4ac0919b 100644
--- a/docs/modules/StateReaderTaskEither.ts.md
+++ b/docs/modules/StateReaderTaskEither.ts.md
@@ -196,6 +196,8 @@ Added in v2.0.0
 
 Less strict version of [`ap`](#ap).
 
+The `W` suffix (short for **W**idening) means that the environment types and the error types will be merged.
+
 **Signature**
 
 ```ts
@@ -274,6 +276,8 @@ Added in v2.0.0
 
 Less strict version of [`chain`](#chain).
 
+The `W` suffix (short for **W**idening) means that the environment types and the error types will be merged.
+
 **Signature**
 
 ```ts
@@ -414,6 +418,10 @@ Added in v2.4.0
 
 Less strict version of [`chainEitherK`](#chaineitherk).
 
+The `W` suffix (short for **W**idening) means that the error types will be merged.
+
+The `W` suffix (short for **W**idening) means that the environment types and the error types will be merged.
+
 **Signature**
 
 ```ts
@@ -457,6 +465,8 @@ Added in v2.12.0
 
 Less strict version of [`chainFirstEitherK`](#chainfirsteitherk).
 
+The `W` suffix (short for **W**idening) means that the environment types and the error types will be merged.
+
 **Signature**
 
 ```ts
@@ -495,6 +505,8 @@ Added in v2.11.0
 
 Less strict version of [`chainFirstReaderK`](#chainFirstReaderK).
 
+The `W` suffix (short for **W**idening) means that the environment types and the error types will be merged.
+
 **Signature**
 
 ```ts
@@ -521,6 +533,8 @@ Added in v2.10.0
 
 Less strict version of [`chainFirst`](#chainfirst).
 
+The `W` suffix (short for **W**idening) means that the environment types and the error types will be merged.
+
 Derivable from `Chain`.
 
 **Signature**
@@ -601,6 +615,8 @@ Added in v2.11.0
 
 Less strict version of [`chainReaderK`](#chainReaderK).
 
+The `W` suffix (short for **W**idening) means that the environment types and the error types will be merged.
+
 **Signature**
 
 ```ts
@@ -1435,6 +1451,8 @@ Added in v2.8.0
 
 ## apSW
 
+The `W` suffix (short for **W**idening) means that the environment types and the error types will be merged.
+
 **Signature**
 
 ```ts
diff --git a/docs/modules/StateT.ts.md b/docs/modules/StateT.ts.md
index 02c7b757..3438cddf 100644
--- a/docs/modules/StateT.ts.md
+++ b/docs/modules/StateT.ts.md
@@ -6,6 +6,11 @@ parent: Modules
 
 ## StateT overview
 
+The state monad transformer. It can be used to add state to other monads.
+
+The `of` function leaves the state unchanged, while `chain` uses the final state of the first computation
+as the initial state of the second.
+
 Added in v2.0.0
 
 ---
diff --git a/docs/modules/TaskEither.ts.md b/docs/modules/TaskEither.ts.md
index 904ec186..386efda4 100644
--- a/docs/modules/TaskEither.ts.md
+++ b/docs/modules/TaskEither.ts.md
@@ -219,6 +219,8 @@ Added in v2.0.0
 
 Less strict version of [`alt`](#alt).
 
+The `W` suffix (short for **W**idening) means that the error and the return types will be merged.
+
 **Signature**
 
 ```ts
@@ -247,6 +249,8 @@ Added in v2.0.0
 
 Less strict version of [`ap`](#ap).
 
+The `W` suffix (short for **W**idening) means that the error types will be merged.
+
 **Signature**
 
 ```ts
@@ -316,6 +320,8 @@ Added in v2.0.0
 
 Less strict version of [`chain`](#chain).
 
+The `W` suffix (short for **W**idening) means that the error types will be merged.
+
 **Signature**
 
 ```ts
@@ -422,6 +428,8 @@ Added in v2.4.0
 
 Less strict version of [`chainEitherK`](#chaineitherk).
 
+The `W` suffix (short for **W**idening) means that the error types will be merged.
+
 **Signature**
 
 ```ts
@@ -463,6 +471,8 @@ Added in v2.12.0
 
 Less strict version of [`chainFirstEitherK`](#chainfirsteitherk).
 
+The `W` suffix (short for **W**idening) means that the error types will be merged.
+
 **Signature**
 
 ```ts
@@ -497,6 +507,8 @@ Added in v2.10.0
 
 Less strict version of [`chainFirst`](#chainfirst).
 
+The `W` suffix (short for **W**idening) means that the error types will be merged.
+
 Derivable from `Chain`.
 
 **Signature**
@@ -525,6 +537,8 @@ Added in v2.4.0
 
 Less strict version of [`chainIOEitherK`](#chainioeitherk).
 
+The `W` suffix (short for **W**idening) means that the error types will be merged.
+
 **Signature**
 
 ```ts
@@ -1534,6 +1548,8 @@ Added in v2.8.0
 
 ## apSW
 
+The `W` suffix (short for **W**idening) means that the error types will be merged.
+
 **Signature**
 
 ```ts
diff --git a/docs/modules/TaskOption.ts.md b/docs/modules/TaskOption.ts.md
index ca8d1d2f..9bd98922 100644
--- a/docs/modules/TaskOption.ts.md
+++ b/docs/modules/TaskOption.ts.md
@@ -133,6 +133,8 @@ Added in v2.10.0
 
 Less strict version of [`alt`](#alt).
 
+The `W` suffix (short for **W**idening) means that the return types will be merged.
+
 **Signature**
 
 ```ts
diff --git a/docs/modules/function.ts.md b/docs/modules/function.ts.md
index 6a72a3f4..bf004c20 100644
--- a/docs/modules/function.ts.md
+++ b/docs/modules/function.ts.md
@@ -306,14 +306,25 @@ Added in v2.0.0
 
 ## flip
 
-Flips the order of the arguments of a function of two arguments.
+Flips the arguments of a curried function.
 
 **Signature**
 
 ```ts
+export declare function flip<A, B, C>(f: (a: A) => (b: B) => C): (b: B) => (a: A) => C
 export declare function flip<A, B, C>(f: (a: A, b: B) => C): (b: B, a: A) => C
 ```
 
+**Example**
+
+```ts
+import { flip } from 'fp-ts/function'
+
+const f = (a: number) => (b: string) => a - b.length
+
+assert.strictEqual(flip(f)('aaa')(2), -1)
+```
+
 Added in v2.0.0
 
 ## flow
diff --git a/src/Either.ts b/src/Either.ts
index 6d3182c1..8c6f0ee1 100644
--- a/src/Either.ts
+++ b/src/Either.ts
@@ -11,6 +11,52 @@
  * `None` is replaced with a `Left` which can contain useful information. `Right` takes the place of `Some`. Convention
  * dictates that `Left` is used for failure and `Right` is used for success.
  *
+ *
+ * @example
+ * import * as E from 'fp-ts/Either'
+ * import { pipe } from 'fp-ts/function'
+ *
+ * const double = (n: number): number => n * 2
+ *
+ * export const imperative = (as: ReadonlyArray<number>): string => {
+ *   const head = (as: ReadonlyArray<number>): number => {
+ *     if (as.length === 0) {
+ *       throw new Error('empty array')
+ *     }
+ *     return as[0]
+ *   }
+ *   const inverse = (n: number): number => {
+ *     if (n === 0) {
+ *       throw new Error('cannot divide by zero')
+ *     }
+ *     return 1 / n
+ *   }
+ *   try {
+ *     return `Result is ${inverse(double(head(as)))}`
+ *   } catch (err) {
+ *     return `Error is ${err}`
+ *   }
+ * }
+ *
+ * export const functional = (as: ReadonlyArray<number>): string => {
+ *   const head = <A>(as: ReadonlyArray<A>): E.Either<string, A> =>
+ *     as.length === 0 ? E.left('empty array') : E.right(as[0])
+ *   const inverse = (n: number): E.Either<string, number> =>
+ *     n === 0 ? E.left('cannot divide by zero') : E.right(1 / n)
+ *   return pipe(
+ *     as,
+ *     head,
+ *     E.map(double),
+ *     E.chain(inverse),
+ *     E.match(
+ *       (err) => `Error is ${err}`, // onLeft handler
+ *       (head) => `Result is ${head}` // onRight handler
+ *     )
+ *   )
+ * }
+ *
+ * assert.deepStrictEqual(imperative([1, 2, 3]), functional([1, 2, 3]))
+ *
  * @since 2.0.0
  */
 import { Alt2, Alt2C } from './Alt'
@@ -367,6 +413,8 @@ export const Pointed: Pointed2<URI> = {
 /**
  * Less strict version of [`ap`](#ap).
  *
+ * The `W` suffix (short for **W**idening) means that the error types will be merged.
+ *
  * @category instance operations
  * @since 2.8.0
  */
@@ -406,6 +454,28 @@ export const Applicative: Applicative2<URI> = {
 /**
  * Less strict version of [`chain`](#chain).
  *
+ * The `W` suffix (short for **W**idening) means that the error types will be merged.
+ *
+ * @example
+ * import * as E from 'fp-ts/Either'
+ * import { pipe } from 'fp-ts/function'
+ *
+ * const e1: E.Either<string, number> = E.right(1)
+ * const e2: E.Either<number, number> = E.right(2)
+ *
+ * export const result1 = pipe(
+ *   // @ts-expect-error
+ *   e1,
+ *   E.chain(() => e2)
+ * )
+ *
+ * // merged error types -----v-------------v
+ * // const result2: E.Either<string | number, number>
+ * export const result2 = pipe(
+ *   e1, // no error
+ *   E.chainW(() => e2)
+ * )
+ *
  * @category instance operations
  * @since 2.6.0
  */
@@ -631,6 +701,8 @@ export const Bifunctor: Bifunctor2<URI> = {
 /**
  * Less strict version of [`alt`](#alt).
  *
+ * The `W` suffix (short for **W**idening) means that the error and the return types will be merged.
+ *
  * @category instance operations
  * @since 2.9.0
  */
@@ -642,6 +714,41 @@ export const altW: <E2, B>(that: Lazy<Either<E2, B>>) => <E1, A>(fa: Either<E1,
  * Identifies an associative operation on a type constructor. It is similar to `Semigroup`, except that it applies to
  * types of kind `* -> *`.
  *
+ * In case of `Either` returns the left-most non-`Left` value (or the right-most `Left` value if both values are `Left`).
+ *
+ * @example
+ * import * as E from 'fp-ts/Either'
+ * import { pipe } from 'fp-ts/function'
+ *
+ * assert.deepStrictEqual(
+ *   pipe(
+ *     E.left('a'),
+ *     E.alt(() => E.left('b'))
+ *   ),
+ *   E.left('b')
+ * )
+ * assert.deepStrictEqual(
+ *   pipe(
+ *     E.left('a'),
+ *     E.alt(() => E.right(2))
+ *   ),
+ *   E.right(2)
+ * )
+ * assert.deepStrictEqual(
+ *   pipe(
+ *     E.right(1),
+ *     E.alt(() => E.left('b'))
+ *   ),
+ *   E.right(1)
+ * )
+ * assert.deepStrictEqual(
+ *   pipe(
+ *     E.right(1),
+ *     E.alt(() => E.right(2))
+ *   ),
+ *   E.right(1)
+ * )
+ *
  * @category instance operations
  * @since 2.0.0
  */
@@ -964,6 +1071,8 @@ export const chainFirst: <E, A, B>(
 /**
  * Less strict version of [`chainFirst`](#chainfirst)
  *
+ * The `W` suffix (short for **W**idening) means that the error types will be merged.
+ *
  * Derivable from `Chain`.
  *
  * @category combinators
@@ -1284,6 +1393,8 @@ export const bindW: <N extends string, A, E2, B>(
 export const apS = /*#__PURE__*/ apS_(Apply)
 
 /**
+ * The `W` suffix (short for **W**idening) means that the error types will be merged.
+ *
  * @since 2.8.0
  */
 export const apSW: <A, N extends string, E2, B>(
diff --git a/src/EitherT.ts b/src/EitherT.ts
index 728fa740..3ec897f8 100644
--- a/src/EitherT.ts
+++ b/src/EitherT.ts
@@ -1,4 +1,8 @@
 /**
+ * The error monad transformer. It can be used to add error handling to other monads.
+ *
+ * The `of` function yields a successful computation, while `chain` sequences two subcomputations, failing on the first error.
+ *
  * @since 2.0.0
  */
 import { ApplicativeComposition12, ApplicativeComposition22, ApplicativeCompositionHKT2 } from './Applicative'
diff --git a/src/IOEither.ts b/src/IOEither.ts
index 18c5b1ea..40253881 100644
--- a/src/IOEither.ts
+++ b/src/IOEither.ts
@@ -349,6 +349,8 @@ export const ap: <E, A>(
 /**
  * Less strict version of [`ap`](#ap).
  *
+ * The `W` suffix (short for **W**idening) means that the error types will be merged.
+ *
  * @category Apply
  * @since 2.8.0
  */
@@ -375,6 +377,8 @@ export const chain: <E, A, B>(
 /**
  * Less strict version of [`chain`](#chain).
  *
+ * The `W` suffix (short for **W**idening) means that the error types will be merged.
+ *
  * @category Monad
  * @since 2.6.0
  */
@@ -414,6 +418,8 @@ export const alt: <E, A>(that: Lazy<IOEither<E, A>>) => (fa: IOEither<E, A>) =>
 /**
  * Less strict version of [`alt`](#alt).
  *
+ * The `W` suffix (short for **W**idening) means that the error and the return types will be merged.
+ *
  * @category Alt
  * @since 2.9.0
  */
@@ -664,6 +670,8 @@ export const chainFirst: <E, A, B>(
 /**
  * Less strict version of [`chainFirst`](#chainfirst).
  *
+ * The `W` suffix (short for **W**idening) means that the error types will be merged.
+ *
  * Derivable from `Chain`.
  *
  * @category combinators
@@ -774,6 +782,8 @@ export const chainEitherK: <E, A, B>(
 /**
  * Less strict version of [`chainEitherK`](#chaineitherk).
  *
+ * The `W` suffix (short for **W**idening) means that the error types will be merged.
+ *
  * @category combinators
  * @since 2.6.1
  */
@@ -788,6 +798,8 @@ export const chainEitherKW: <E2, A, B>(
 export const chainFirstEitherK = /*#__PURE__*/ chainFirstEitherK_(FromEither, Chain)
 
 /**
+ * The `W` suffix (short for **W**idening) means that the error types will be merged.
+ *
  * @category combinators
  * @since 2.12.0
  */
@@ -921,6 +933,8 @@ export const bindW: <N extends string, A, E2, B>(
 export const apS = /*#__PURE__*/ apS_(ApplyPar)
 
 /**
+ * The `W` suffix (short for **W**idening) means that the error types will be merged.
+ *
  * @since 2.8.0
  */
 export const apSW: <A, N extends string, E2, B>(
diff --git a/src/IOOption.ts b/src/IOOption.ts
index 0aa6bae5..f2091b81 100644
--- a/src/IOOption.ts
+++ b/src/IOOption.ts
@@ -275,6 +275,8 @@ export const alt: <A>(second: Lazy<IOOption<A>>) => (first: IOOption<A>) => IOOp
 /**
  * Less strict version of [`alt`](#alt).
  *
+ * The `W` suffix (short for **W**idening) means that the return types will be merged.
+ *
  * @category Alt
  * @since 2.12.0
  */
diff --git a/src/Identity.ts b/src/Identity.ts
index 44b3feba..c3148c0c 100644
--- a/src/Identity.ts
+++ b/src/Identity.ts
@@ -156,6 +156,8 @@ export const sequence: Traversable1<URI>['sequence'] = <F>(F: ApplicativeHKT<F>)
 /**
  * Less strict version of [`alt`](#alt).
  *
+ * The `W` suffix (short for **W**idening) means that the return types will be merged.
+ *
  * @category Alt
  * @since 2.9.0
  */
diff --git a/src/Option.ts b/src/Option.ts
index 1302d83d..cab25ac5 100644
--- a/src/Option.ts
+++ b/src/Option.ts
@@ -10,6 +10,52 @@
  * An option could be looked at as a collection or foldable structure with either one or zero elements.
  * Another way to look at `Option` is: it represents the effect of a possibly failing computation.
  *
+ *
+ * @example
+ * import * as O from 'fp-ts/Option'
+ * import { pipe } from 'fp-ts/function'
+ *
+ * const double = (n: number): number => n * 2
+ *
+ * export const imperative = (as: ReadonlyArray<number>): string => {
+ *   const head = (as: ReadonlyArray<number>): number => {
+ *     if (as.length === 0) {
+ *       throw new Error()
+ *     }
+ *     return as[0]
+ *   }
+ *   const inverse = (n: number): number => {
+ *     if (n === 0) {
+ *       throw new Error()
+ *     }
+ *     return 1 / n
+ *   }
+ *   try {
+ *     return `Result is ${inverse(double(head(as)))}`
+ *   } catch (e) {
+ *     return 'no result'
+ *   }
+ * }
+ *
+ * export const functional = (as: ReadonlyArray<number>): string => {
+ *   const head = <A>(as: ReadonlyArray<A>): O.Option<A> =>
+ *     as.length === 0 ? O.none : O.some(as[0])
+ *   const inverse = (n: number): O.Option<number> =>
+ *     n === 0 ? O.none : O.some(1 / n)
+ *   return pipe(
+ *     as,
+ *     head,
+ *     O.map(double),
+ *     O.chain(inverse),
+ *     O.match(
+ *       () => 'no result', // onNone handler
+ *       (head) => `Result is ${head}` // onSome handler
+ *     )
+ *   )
+ * }
+ *
+ * assert.deepStrictEqual(imperative([1, 2, 3]), functional([1, 2, 3]))
+ *
  * @since 2.0.0
  */
 import { Alt1 } from './Alt'
@@ -416,6 +462,8 @@ export const Foldable: Foldable1<URI> = {
 /**
  * Less strict version of [`alt`](#alt).
  *
+ * The `W` suffix (short for **W**idening) means that the return types will be merged.
+ *
  * @category instance operations
  * @since 2.9.0
  */
@@ -434,10 +482,10 @@ export const altW: <B>(that: Lazy<Option<B>>) => <A>(fa: Option<A>) => Option<A
  *
  * assert.deepStrictEqual(
  *   pipe(
- *     O.some('a'),
- *     O.alt(() => O.some('b'))
+ *     O.none,
+ *     O.alt(() => O.none)
  *   ),
- *   O.some('a')
+ *   O.none
  * )
  * assert.deepStrictEqual(
  *   pipe(
@@ -446,6 +494,20 @@ export const altW: <B>(that: Lazy<Option<B>>) => <A>(fa: Option<A>) => Option<A
  *   ),
  *   O.some('b')
  * )
+ * assert.deepStrictEqual(
+ *   pipe(
+ *     O.some('a'),
+ *     O.alt<string>(() => O.none)
+ *   ),
+ *   O.some('a')
+ * )
+ * assert.deepStrictEqual(
+ *   pipe(
+ *     O.some('a'),
+ *     O.alt(() => O.some('b'))
+ *   ),
+ *   O.some('a')
+ * )
  *
  * @category instance operations
  * @since 2.0.0
diff --git a/src/Reader.ts b/src/Reader.ts
index 226e7332..486fe149 100644
--- a/src/Reader.ts
+++ b/src/Reader.ts
@@ -1,4 +1,41 @@
 /**
+ * The `Reader` monad (also called the Environment monad). Represents a computation, which can read values from a shared environment,
+ * pass values from function to function, and execute sub-computations in a modified environment.
+ * Using `Reader` monad for such computations is often clearer and easier than using the `State` monad.
+ *
+ * In this example the `Reader` monad provides access to variable bindings. `Bindings` are a map of `number` variables.
+ * The variable count contains number of variables in the bindings. You can see how to run a `Reader` monad and retrieve
+ * data from it, how to access the `Reader` data with `ask` and `asks`.
+ *
+ * @example
+ * import { pipe } from 'fp-ts/function'
+ * import * as O from 'fp-ts/Option'
+ * import * as R from 'fp-ts/Reader'
+ * import * as RR from 'fp-ts/ReadonlyRecord'
+ *
+ * interface Bindings extends RR.ReadonlyRecord<string, number> {}
+ *
+ * // The Reader monad, which implements this complicated check.
+ * const isCountCorrect: R.Reader<Bindings, boolean> = pipe(
+ *   R.Do,
+ *   R.bind('count', () => R.asks(lookupVar('count'))),
+ *   R.bind('bindings', () => R.ask()),
+ *   R.map(({ count, bindings }) => count === RR.size(bindings))
+ * )
+ *
+ * // The selector function to use with 'asks'.
+ * // Returns value of the variable with specified name.
+ * const lookupVar = (name: string) => (bindings: Bindings): number =>
+ *   pipe(
+ *     bindings,
+ *     RR.lookup(name),
+ *     O.getOrElse(() => 0)
+ *   )
+ *
+ * const sampleBindings: Bindings = { count: 3, a: 1, b: 2 }
+ *
+ * assert.deepStrictEqual(isCountCorrect(sampleBindings), true)
+ *
  * @since 2.0.0
  */
 import { Applicative2, getApplicativeMonoid } from './Applicative'
@@ -59,6 +96,30 @@ export const asks: <R, A>(f: (r: R) => A) => Reader<R, A> = identity
  * Changes the value of the local context during the execution of the action `ma` (similar to `Contravariant`'s
  * `contramap`).
  *
+ * @example
+ * import { pipe } from 'fp-ts/function'
+ * import * as R from 'fp-ts/Reader'
+ * import * as string from 'fp-ts/string'
+ *
+ * const calculateContentLen: R.Reader<string, number> = pipe(
+ *   R.Do,
+ *   R.bind('content', () => R.ask<string>()),
+ *   R.map(({ content }) => string.size(content))
+ * )
+ *
+ * // Calls calculateContentLen after adding a prefix to the Reader content.
+ * const calculateModifiedContentLen: R.Reader<string, number> = pipe(
+ *   calculateContentLen,
+ *   R.local((s) => 'Prefix ' + s)
+ * )
+ *
+ * const s = '12345'
+ *
+ * assert.deepStrictEqual(
+ *   "Modified 's' length: " + calculateModifiedContentLen(s) + '\n' + "Original 's' length: " + calculateContentLen(s),
+ *   "Modified 's' length: 12\nOriginal 's' length: 5"
+ * )
+ *
  * @category combinators
  * @since 2.0.0
  */
@@ -110,6 +171,8 @@ export const map: <A, B>(f: (a: A) => B) => <R>(fa: Reader<R, A>) => Reader<R, B
 /**
  * Less strict version of [`ap`](#ap).
  *
+ * The `W` suffix (short for **W**idening) means that the environment types will be merged.
+ *
  * @category Apply
  * @since 2.8.0
  */
@@ -134,6 +197,8 @@ export const of: Pointed2<URI>['of'] = constant
 /**
  * Less strict version of [`chain`](#chain).
  *
+ * The `W` suffix (short for **W**idening) means that the environment types will be merged.
+ *
  * @category Monad
  * @since 2.6.0
  */
@@ -357,6 +422,8 @@ export const chainFirst = /*#__PURE__*/ chainFirst_(Chain)
 /**
  * Less strict version of [`chainFirst`](#chainfirst).
  *
+ * The `W` suffix (short for **W**idening) means that the environment types will be merged.
+ *
  * Derivable from `Chain`.
  *
  * @category combinators
@@ -449,6 +516,8 @@ export const Do: Reader<unknown, {}> = /*#__PURE__*/ of(_.emptyRecord)
 export const apS = /*#__PURE__*/ apS_(Apply)
 
 /**
+ * The `W` suffix (short for **W**idening) means that the environment types will be merged.
+ *
  * @since 2.8.0
  */
 export const apSW: <A, N extends string, R2, B>(
diff --git a/src/ReaderEither.ts b/src/ReaderEither.ts
index 127f4032..52744933 100644
--- a/src/ReaderEither.ts
+++ b/src/ReaderEither.ts
@@ -353,6 +353,8 @@ export const ap: <R, E, A>(
 /**
  * Less strict version of [`ap`](#ap).
  *
+ * The `W` suffix (short for **W**idening) means that the environment types and the error types will be merged.
+ *
  * @category Apply
  * @since 2.8.0
  */
@@ -379,6 +381,8 @@ export const chain: <R, E, A, B>(
 /**
  * Less strict version of [`chain`](#chain).
  *
+ * The `W` suffix (short for **W**idening) means that the error types will be merged.
+ *
  * @category Monad
  * @since 2.6.0
  */
@@ -418,6 +422,8 @@ export const alt: <R, E, A>(
 /**
  * Less strict version of [`alt`](#alt).
  *
+ * The `W` suffix (short for **W**idening) means that the environment, the error and the return types will be merged.
+ *
  * @category Alt
  * @since 2.9.0
  */
@@ -647,6 +653,8 @@ export const chainFirst: <R, E, A, B>(
 /**
  * Less strict version of [`chainFirst`](#chainfirst)
  *
+ * The `W` suffix (short for **W**idening) means that the environment types and the error types will be merged.
+ *
  * Derivable from `Chain`.
  *
  * @category combinators
@@ -720,6 +728,8 @@ export const chainReaderK: <A, R, B>(
 /**
  * Less strict version of [`chainReaderK`](#chainreaderk).
  *
+ * The `W` suffix (short for **W**idening) means that the environment types will be merged.
+ *
  * @category combinators
  * @since 2.11.0
  */
@@ -741,6 +751,8 @@ export const chainFirstReaderK: <A, R, B>(
 /**
  * Less strict version of [`chainReaderK`](#chainreaderk).
  *
+ * The `W` suffix (short for **W**idening) means that the environment types will be merged.
+ *
  * @category combinators
  * @since 2.11.0
  */
@@ -801,6 +813,8 @@ export const chainEitherK: <E, A, B>(
 /**
  * Less strict version of [`chainEitherK`](#chaineitherk).
  *
+ * The `W` suffix (short for **W**idening) means that the error types will be merged.
+ *
  * @category combinators
  * @since 2.6.1
  */
@@ -817,6 +831,8 @@ export const chainFirstEitherK = /*#__PURE__*/ chainFirstEitherK_(FromEither, Ch
 /**
  * Less strict version of [`chainFirstEitherK`](#chainfirsteitherk).
  *
+ * The `W` suffix (short for **W**idening) means that the environment types will be merged.
+ *
  * @category combinators
  * @since 2.12.0
  */
@@ -913,6 +929,8 @@ export const bindW: <N extends string, A, R2, E2, B>(
 export const apS = /*#__PURE__*/ apS_(Apply)
 
 /**
+ * The `W` suffix (short for **W**idening) means that the environment types and the error types will be merged.
+ *
  * @since 2.8.0
  */
 export const apSW: <A, N extends string, R2, E2, B>(
diff --git a/src/ReaderT.ts b/src/ReaderT.ts
index dbccbe81..0cfd2f78 100644
--- a/src/ReaderT.ts
+++ b/src/ReaderT.ts
@@ -1,4 +1,8 @@
 /**
+ * The reader monad transformer, which adds a read-only environment to the given monad.
+ *
+ * The `of` function ignores the environment, while `chain` passes the inherited environment to both subcomputations.
+ *
  * @since 2.0.0
  */
 import { Apply, Apply1, Apply2, Apply2C, Apply3, Apply3C, Apply4 } from './Apply'
diff --git a/src/ReaderTask.ts b/src/ReaderTask.ts
index 452258d1..12a45471 100644
--- a/src/ReaderTask.ts
+++ b/src/ReaderTask.ts
@@ -91,6 +91,8 @@ export const local: <R2, R1>(f: (r2: R2) => R1) => <A>(ma: ReaderTask<R1, A>) =>
 /**
  * Less strict version of [`asksReaderTask`](#asksreadertask).
  *
+ * The `W` suffix (short for **W**idening) means that the environment types will be merged.
+ *
  * @category combinators
  * @since 2.11.0
  */
@@ -141,6 +143,8 @@ export const ap: <R, A>(
 /**
  * Less strict version of [`ap`](#ap).
  *
+ * The `W` suffix (short for **W**idening) means that the environment types will be merged.
+ *
  * @category Apply
  * @since 2.8.0
  */
@@ -167,6 +171,8 @@ export const chain: <A, R, B>(
 /**
  * Less strict version of  [`chain`](#chain).
  *
+ * The `W` suffix (short for **W**idening) means that the environment types will be merged.
+ *
  * @category Monad
  * @since 2.6.7
  */
@@ -366,6 +372,8 @@ export const chainFirst = /*#__PURE__*/ chainFirst_(Chain)
 /**
  * Less strict version of [`chainFirst`](#chainfirst).
  *
+ * The `W` suffix (short for **W**idening) means that the environment types will be merged.
+ *
  * Derivable from `Chain`.
  *
  * @category combinators
@@ -442,6 +450,8 @@ export const chainReaderK = /*#__PURE__*/ chainReaderK_(FromReader, Chain)
 /**
  * Less strict version of [`chainReaderK`](#chainreaderk).
  *
+ * The `W` suffix (short for **W**idening) means that the environment types will be merged.
+ *
  * @category combinators
  * @since 2.11.0
  */
@@ -458,6 +468,8 @@ export const chainFirstReaderK = /*#__PURE__*/ chainFirstReaderK_(FromReader, Ch
 /**
  * Less strict version of [`chainFirstReaderK`](#chainfirstreaderk).
  *
+ * The `W` suffix (short for **W**idening) means that the environment types will be merged.
+ *
  * @category combinators
  * @since 2.11.0
  */
@@ -532,6 +544,8 @@ export const bindW: <N extends string, A, R2, B>(
 export const apS = /*#__PURE__*/ apS_(ApplyPar)
 
 /**
+ * The `W` suffix (short for **W**idening) means that the environment types will be merged.
+ *
  * @since 2.8.0
  */
 export const apSW: <A, N extends string, R2, B>(
diff --git a/src/ReaderTaskEither.ts b/src/ReaderTaskEither.ts
index 47915db3..2da45d31 100644
--- a/src/ReaderTaskEither.ts
+++ b/src/ReaderTaskEither.ts
@@ -435,6 +435,8 @@ export const fromIOEitherK = <E, A extends ReadonlyArray<unknown>, B>(
 /**
  * Less strict version of [`chainIOEitherK`](#chainioeitherk).
  *
+ * The `W` suffix (short for **W**idening) means that the environment types and the error types will be merged.
+ *
  * @category combinators
  * @since 2.6.1
  */
@@ -461,6 +463,8 @@ export const fromTaskEitherK = <E, A extends ReadonlyArray<unknown>, B>(
 /**
  * Less strict version of [`chainTaskEitherK`](#chaintaskeitherk).
  *
+ * The `W` suffix (short for **W**idening) means that the environment types and the error types will be merged.
+ *
  * @category combinators
  * @since 2.6.1
  */
@@ -479,6 +483,8 @@ export const chainTaskEitherK: <E, A, B>(
 /**
  * Less strict version of [`chainFirstTaskEitherK`](#chainfirsttaskeitherk).
  *
+ * The `W` suffix (short for **W**idening) means that the environment types and the error types will be merged.
+ *
  * @category combinators
  * @since 2.11.0
  */
@@ -505,6 +511,8 @@ export const fromReaderEitherK = <R, E, A extends ReadonlyArray<unknown>, B>(
 /**
  * Less strict version of [`chainReaderEitherK`](#chainreadereitherk).
  *
+ * The `W` suffix (short for **W**idening) means that the environment types and the error types will be merged.
+ *
  * @category combinators
  * @since 2.11.0
  */
@@ -524,6 +532,8 @@ export const chainReaderEitherK: <R, E, A, B>(
 /**
  * Less strict version of [`chainFirstReaderEitherK`](#chainfirstreadereitherk).
  *
+ * The `W` suffix (short for **W**idening) means that the environment types and the error types will be merged.
+ *
  * @category combinators
  * @since 2.11.0
  */
@@ -609,6 +619,8 @@ export const ap: <R, E, A>(
 /**
  * Less strict version of [`ap`](#ap).
  *
+ * The `W` suffix (short for **W**idening) means that the environment types and the error types will be merged.
+ *
  * @category Apply
  * @since 2.8.0
  */
@@ -635,6 +647,8 @@ export const chain: <R, E, A, B>(
 /**
  * Less strict version of [`chain`](#chain).
  *
+ * The `W` suffix (short for **W**idening) means that the environment types and the error types will be merged.
+ *
  * @category Monad
  * @since 2.6.0
  */
@@ -676,6 +690,8 @@ export const alt: <R, E, A>(
 /**
  * Less strict version of [`alt`](#alt).
  *
+ * The `W` suffix (short for **W**idening) means that the environment, the error and the return types will be merged.
+ *
  * @category Alt
  * @since 2.9.0
  */
@@ -966,6 +982,8 @@ export const chainFirst: <R, E, A, B>(
 /**
  * Less strict version of [`chainFirst`](#chainfirst).
  *
+ * The `W` suffix (short for **W**idening) means that the environment types and the error types will be merged.
+ *
  * Derivable from `Chain`.
  *
  * @category combinators
@@ -1042,6 +1060,8 @@ export const chainReaderK: <A, R, B>(
 /**
  * Less strict version of [`chainReaderK`](#chainreaderk).
  *
+ * The `W` suffix (short for **W**idening) means that the environment types and the error types will be merged.
+ *
  * @category combinators
  * @since 2.11.0
  */
@@ -1063,6 +1083,8 @@ export const chainFirstReaderK: <A, R, B>(
 /**
  * Less strict version of [`chainFirstReaderK`](#chainfirstreaderk).
  *
+ * The `W` suffix (short for **W**idening) means that the environment types and the error types will be merged.
+ *
  * @category combinators
  * @since 2.11.0
  */
@@ -1081,6 +1103,8 @@ export const fromReaderTaskK = <A extends ReadonlyArray<unknown>, R, B>(
 /**
  * Less strict version of [`chainReaderTaskK`](#chainreadertaskk).
  *
+ * The `W` suffix (short for **W**idening) means that the environment types and the error types will be merged.
+ *
  * @category combinators
  * @since 2.11.0
  */
@@ -1100,6 +1124,8 @@ export const chainReaderTaskK: <A, R, B>(
 /**
  * Less strict version of [`chainFirstReaderTaskK`](#chainfirstreadertaskk).
  *
+ * The `W` suffix (short for **W**idening) means that the environment types and the error types will be merged.
+ *
  * @category combinators
  * @since 2.11.0
  */
@@ -1156,6 +1182,8 @@ export const chainEitherK: <E, A, B>(
 /**
  * Less strict version of [`chainEitherK`](#chaineitherk).
  *
+ * The `W` suffix (short for **W**idening) means that the environment types and the error types will be merged.
+ *
  * @category combinators
  * @since 2.6.1
  */
@@ -1172,6 +1200,8 @@ export const chainFirstEitherK = /*#__PURE__*/ chainFirstEitherK_(FromEither, Ch
 /**
  * Less strict version of [`chainFirstEitherK`](#chainfirsteitherk).
  *
+ * The `W` suffix (short for **W**idening) means that the environment types and the error types will be merged.
+ *
  * @category combinators
  * @since 2.12.0
  */
@@ -1361,6 +1391,8 @@ export const bindW: <N extends string, A, R2, E2, B>(
 export const apS = /*#__PURE__*/ apS_(ApplyPar)
 
 /**
+ * The `W` suffix (short for **W**idening) means that the environment types and the error types will be merged.
+ *
  * @since 2.8.0
  */
 export const apSW: <A, N extends string, R2, E2, B>(
diff --git a/src/StateReaderTaskEither.ts b/src/StateReaderTaskEither.ts
index 85464605..26a9e90e 100644
--- a/src/StateReaderTaskEither.ts
+++ b/src/StateReaderTaskEither.ts
@@ -424,6 +424,8 @@ export const ap: <S, R, E, A>(
 /**
  * Less strict version of [`ap`](#ap).
  *
+ * The `W` suffix (short for **W**idening) means that the environment types and the error types will be merged.
+ *
  * @category Apply
  * @since 2.8.0
  */
@@ -452,6 +454,8 @@ export const chain: <S, R, E, A, B>(
 /**
  * Less strict version of [`chain`](#chain).
  *
+ * The `W` suffix (short for **W**idening) means that the environment types and the error types will be merged.
+ *
  * @category Monad
  * @since 2.6.0
  */
@@ -765,6 +769,8 @@ export const chainFirst: <S, R, E, A, B>(
 /**
  * Less strict version of [`chainFirst`](#chainfirst).
  *
+ * The `W` suffix (short for **W**idening) means that the environment types and the error types will be merged.
+ *
  * Derivable from `Chain`.
  *
  * @category combinators
@@ -844,6 +850,8 @@ export const chainReaderK: <A, R, B>(
 /**
  * Less strict version of [`chainReaderK`](#chainReaderK).
  *
+ * The `W` suffix (short for **W**idening) means that the environment types and the error types will be merged.
+ *
  * @category combinators
  * @since 2.11.0
  */
@@ -866,6 +874,8 @@ export const chainFirstReaderK: <A, R, B>(
 /**
  * Less strict version of [`chainFirstReaderK`](#chainFirstReaderK).
  *
+ * The `W` suffix (short for **W**idening) means that the environment types and the error types will be merged.
+ *
  * @category combinators
  * @since 2.11.0
  */
@@ -918,6 +928,10 @@ export const chainEitherK: <E, A, B>(
 /**
  * Less strict version of [`chainEitherK`](#chaineitherk).
  *
+ * The `W` suffix (short for **W**idening) means that the error types will be merged.
+ *
+ * The `W` suffix (short for **W**idening) means that the environment types and the error types will be merged.
+ *
  * @category combinators
  * @since 2.6.1
  */
@@ -934,6 +948,8 @@ export const chainFirstEitherK = /*#__PURE__*/ chainFirstEitherK_(FromEither, Ch
 /**
  * Less strict version of [`chainFirstEitherK`](#chainfirsteitherk).
  *
+ * The `W` suffix (short for **W**idening) means that the environment types and the error types will be merged.
+ *
  * @category combinators
  * @since 2.12.0
  */
@@ -1117,6 +1133,8 @@ export const bindW: <N extends string, A, S, R2, E2, B>(
 export const apS = /*#__PURE__*/ apS_(Apply)
 
 /**
+ * The `W` suffix (short for **W**idening) means that the environment types and the error types will be merged.
+ *
  * @since 2.8.0
  */
 export const apSW: <A, N extends string, S, R2, E2, B>(
diff --git a/src/StateT.ts b/src/StateT.ts
index 3727a768..e54d07c0 100644
--- a/src/StateT.ts
+++ b/src/StateT.ts
@@ -1,4 +1,9 @@
 /**
+ * The state monad transformer. It can be used to add state to other monads.
+ *
+ * The `of` function leaves the state unchanged, while `chain` uses the final state of the first computation
+ * as the initial state of the second.
+ *
  * @since 2.0.0
  */
 import { Chain, Chain1, Chain2, Chain2C, Chain3, Chain3C } from './Chain'
diff --git a/src/TaskEither.ts b/src/TaskEither.ts
index 6ae34c80..cc72ac20 100644
--- a/src/TaskEither.ts
+++ b/src/TaskEither.ts
@@ -437,6 +437,8 @@ export const fromIOEitherK = <E, A extends ReadonlyArray<unknown>, B>(
 /**
  * Less strict version of [`chainIOEitherK`](#chainioeitherk).
  *
+ * The `W` suffix (short for **W**idening) means that the error types will be merged.
+ *
  * @category combinators
  * @since 2.6.1
  */
@@ -521,6 +523,8 @@ export const ap: <E, A>(
 /**
  * Less strict version of [`ap`](#ap).
  *
+ * The `W` suffix (short for **W**idening) means that the error types will be merged.
+ *
  * @category Apply
  * @since 2.8.0
  */
@@ -541,6 +545,8 @@ export const chain: <E, A, B>(
 /**
  * Less strict version of [`chain`](#chain).
  *
+ * The `W` suffix (short for **W**idening) means that the error types will be merged.
+ *
  * @category Monad
  * @since 2.6.0
  */
@@ -615,6 +621,8 @@ export const alt: <E, A>(
 /**
  * Less strict version of [`alt`](#alt).
  *
+ * The `W` suffix (short for **W**idening) means that the error and the return types will be merged.
+ *
  * @category Alt
  * @since 2.9.0
  */
@@ -911,6 +919,8 @@ export const chainFirst: <E, A, B>(
 /**
  * Less strict version of [`chainFirst`](#chainfirst).
  *
+ * The `W` suffix (short for **W**idening) means that the error types will be merged.
+ *
  * Derivable from `Chain`.
  *
  * @category combinators
@@ -978,6 +988,8 @@ export const chainEitherK: <E, A, B>(
 /**
  * Less strict version of [`chainEitherK`](#chaineitherk).
  *
+ * The `W` suffix (short for **W**idening) means that the error types will be merged.
+ *
  * @category combinators
  * @since 2.6.1
  */
@@ -994,6 +1006,8 @@ export const chainFirstEitherK = /*#__PURE__*/ chainFirstEitherK_(FromEither, Ch
 /**
  * Less strict version of [`chainFirstEitherK`](#chainfirsteitherk).
  *
+ * The `W` suffix (short for **W**idening) means that the error types will be merged.
+ *
  * @category combinators
  * @since 2.12.0
  */
@@ -1236,6 +1250,8 @@ export const bindW: <N extends string, A, E2, B>(
 export const apS = /*#__PURE__*/ apS_(ApplyPar)
 
 /**
+ * The `W` suffix (short for **W**idening) means that the error types will be merged.
+ *
  * @since 2.8.0
  */
 export const apSW: <A, N extends string, E2, B>(
diff --git a/src/TaskOption.ts b/src/TaskOption.ts
index b7f42a03..50b16b5f 100644
--- a/src/TaskOption.ts
+++ b/src/TaskOption.ts
@@ -316,6 +316,8 @@ export const alt: <A>(second: Lazy<TaskOption<A>>) => (first: TaskOption<A>) =>
 /**
  * Less strict version of [`alt`](#alt).
  *
+ * The `W` suffix (short for **W**idening) means that the return types will be merged.
+ *
  * @category Alt
  * @since 2.10.0
  */
diff --git a/src/function.ts b/src/function.ts
index 3adfe596..594e27c7 100644
--- a/src/function.ts
+++ b/src/function.ts
@@ -194,12 +194,28 @@ export const constUndefined: Lazy<undefined> = /*#__PURE__*/ constant(undefined)
 export const constVoid: Lazy<void> = constUndefined
 
 /**
- * Flips the order of the arguments of a function of two arguments.
+ * Flips the arguments of a curried function.
+ *
+ * @example
+ * import { flip } from 'fp-ts/function'
+ *
+ * const f = (a: number) => (b: string) => a - b.length
+ *
+ * assert.strictEqual(flip(f)('aaa')(2), -1)
  *
  * @since 2.0.0
  */
-export function flip<A, B, C>(f: (a: A, b: B) => C): (b: B, a: A) => C {
-  return (b, a) => f(a, b)
+export function flip<A, B, C>(f: (a: A) => (b: B) => C): (b: B) => (a: A) => C
+/** @deprecated */
+export function flip<A, B, C>(f: (a: A, b: B) => C): (b: B, a: A) => C
+export function flip(f: Function): Function {
+  return (...args: Array<any>) => {
+    if (args.length > 1) {
+      return f(args[1], args[0])
+    }
+
+    return (a: any) => f(a)(args[0])
+  }
 }
 
 /**


Test patch:
diff --git a/test/function.ts b/test/function.ts
index 769c50b1..74ed439b 100644
--- a/test/function.ts
+++ b/test/function.ts
@@ -10,9 +10,13 @@ const f = (n: number) => n + 1
 const g = (n: number) => n * 2
 
 describe('function', () => {
-  it('flip', () => {
-    const f = (a: number, b: string) => a - b.length
-    U.deepStrictEqual(_.flip(f)('aaa', 2), -1)
+  test('flip', () => {
+    const f1 = (a: number) => (b: string) => a - b.length
+    const f2 = (a: number, b: string) => a - b.length
+
+    U.deepStrictEqual(_.flip(f1)('aaa')(2), -1)
+    // eslint-disable-next-line deprecation/deprecation
+    U.deepStrictEqual(_.flip(f2)('aaa', 2), -1)
   })
 
   it('not', () => {