docs: add example to Ord.getSemigroup

docs/modules/Eq.ts.md

@@ -79,9 +79,9 @@ import * as S from 'fp-ts/string'
 type UUID = string
 
 interface User {
-  key: UUID
-  firstName: string
-  lastName: string
+  readonly key: UUID
+  readonly firstName: string
+  readonly lastName: string
 }
 
 const eqUUID: Eq<UUID> = S.Eq

docs/modules/Ord.ts.md

@@ -88,8 +88,8 @@ import * as RA from 'fp-ts/ReadonlyArray'
 import * as S from 'fp-ts/string'
 
 interface User {
-  firstName: string
-  lastName: string
+  readonly firstName: string
+  readonly lastName: string
 }
 
 const ordLastName: Ord<string> = S.Ord
@@ -311,12 +311,58 @@ Added in v2.4.0
 
 ## getSemigroup
 
+A typical use case for the `Semigroup` instance of `Ord` is merging two or more orderings.
+
+For example the following snippet builds an `Ord` for a type `User` which
+sorts by `created` date descending, and **then** `lastName`
+
 **Signature**
 
 ```ts
 export declare const getSemigroup: <A = never>() => Semigroup<Ord<A>>
 ```
 
+**Example**
+
+```ts
+import * as D from 'fp-ts/Date'
+import { pipe } from 'fp-ts/function'
+import { contramap, getSemigroup, Ord, reverse } from 'fp-ts/Ord'
+import * as RA from 'fp-ts/ReadonlyArray'
+import * as S from 'fp-ts/string'
+
+interface User {
+  readonly id: string
+  readonly lastName: string
+  readonly created: Date
+}
+
+const ordByLastName: Ord<User> = pipe(
+  S.Ord,
+  contramap((user) => user.lastName)
+)
+
+const ordByCreated: Ord<User> = pipe(
+  D.Ord,
+  contramap((user) => user.created)
+)
+
+const ordUserByCreatedDescThenLastName = getSemigroup<User>().concat(reverse(ordByCreated), ordByLastName)
+
+assert.deepStrictEqual(
+  RA.sort(ordUserByCreatedDescThenLastName)([
+    { id: 'c', lastName: 'd', created: new Date(1973, 10, 30) },
+    { id: 'a', lastName: 'b', created: new Date(1973, 10, 30) },
+    { id: 'e', lastName: 'f', created: new Date(1980, 10, 30) },
+  ]),
+  [
+    { id: 'e', lastName: 'f', created: new Date(1980, 10, 30) },
+    { id: 'a', lastName: 'b', created: new Date(1973, 10, 30) },
+    { id: 'c', lastName: 'd', created: new Date(1973, 10, 30) },
+  ]
+)
+```
+
 Added in v2.0.0
 
 ## ~~ordBoolean~~

src/Eq.ts

@@ -109,9 +109,9 @@ const contramap_: <A, B>(fa: Eq<A>, f: (b: B) => A) => Eq<B> = (fa, f) => pipe(f
  * type UUID = string
  *
  * interface User {
- *   key: UUID
- *   firstName: string
- *   lastName: string
+ *   readonly key: UUID
+ *   readonly firstName: string
+ *   readonly lastName: string
  * }
  *
  * const eqUUID: Eq<UUID> = S.Eq

src/Ord.ts

@@ -121,8 +121,8 @@ const contramap_: <A, B>(fa: Ord<A>, f: (b: B) => A) => Ord<B> = (fa, f) => pipe
  * import * as S from 'fp-ts/string'
  *
  * interface User {
- *   firstName: string
- *   lastName: string
+ *   readonly firstName: string
+ *   readonly lastName: string
  * }
  *
  * const ordLastName: Ord<string> = S.Ord
@@ -172,6 +172,52 @@ declare module './HKT' {
 }
 
 /**
+ * A typical use case for the `Semigroup` instance of `Ord` is merging two or more orderings.
+ *
+ * For example the following snippet builds an `Ord` for a type `User` which
+ * sorts by `created` date descending, and **then** `lastName`
+ *
+ * @example
+ * import * as D from 'fp-ts/Date'
+ * import { pipe } from 'fp-ts/function'
+ * import { contramap, getSemigroup, Ord, reverse } from 'fp-ts/Ord'
+ * import * as RA from 'fp-ts/ReadonlyArray'
+ * import * as S from 'fp-ts/string'
+ *
+ * interface User {
+ *   readonly id: string
+ *   readonly lastName: string
+ *   readonly created: Date
+ * }
+ *
+ * const ordByLastName: Ord<User> = pipe(
+ *   S.Ord,
+ *   contramap((user) => user.lastName)
+ * )
+ *
+ * const ordByCreated: Ord<User> = pipe(
+ *   D.Ord,
+ *   contramap((user) => user.created)
+ * )
+ *
+ * const ordUserByCreatedDescThenLastName = getSemigroup<User>().concat(
+ *   reverse(ordByCreated),
+ *   ordByLastName
+ * )
+ *
+ * assert.deepStrictEqual(
+ *   RA.sort(ordUserByCreatedDescThenLastName)([
+ *     { id: 'c', lastName: 'd', created: new Date(1973, 10, 30) },
+ *     { id: 'a', lastName: 'b', created: new Date(1973, 10, 30) },
+ *     { id: 'e', lastName: 'f', created: new Date(1980, 10, 30) }
+ *   ]),
+ *   [
+ *     { id: 'e', lastName: 'f', created: new Date(1980, 10, 30) },
+ *     { id: 'a', lastName: 'b', created: new Date(1973, 10, 30) },
+ *     { id: 'c', lastName: 'd', created: new Date(1973, 10, 30) }
+ *   ]
+ * )
+ *
  * @category instances
  * @since 2.0.0
  */