Docs: better Traversable overview

gcanti · Mar 1, 2020 · 9889c42 · 9889c42
1 parent 3b96427
commit 9889c42
Show file tree

Hide file tree

Showing 2 changed files with 32 additions and 12 deletions.
diff --git a/docs/modules/Traversable.ts.md b/docs/modules/Traversable.ts.md
@@ -9,18 +9,28 @@ parent: Modules
 `Traversable` represents data structures which can be _traversed_ accumulating results and effects in some
 `Applicative` functor.
 
-`traverse` signature:
+- `traverse` runs an action for every element in a data structure, and accumulates the results.
+- `sequence` runs the actions _contained_ in a data structure, and accumulates the results.
 
-```ts
-<F>(F: Applicative<F>) => <A, B>(ta: HKT<T, A>, f: (a: A) => HKT<F, B>) => HKT<F, HKT<T, B>>
-```
+The `traverse` and `sequence` functions should be compatible in the following sense:
+
+- `traverse(A)(xs, f) = sequence(A)(A.map(xs, f))`
+- `sequence(A)(xs) = traverse(A)(xs, identity)`
+
+where `A` is an `Applicative` instance
 
-`sequence` signature:
+`Traversable` instances should also be compatible with the corresponding `Foldable` instances, in the following sense:
 
 ```ts
-<F>(F: Applicative<F>) => <A>(ta: HKT<T, HKT<F, A>>) => HKT<F, HKT<T, A>>
+import { getApplicative, make } from 'fp-ts/lib/Const'
+
+const A = getApplicative(M)
+
+foldMap(M)(xs, f) = traverse(A)(xs, a => make(f(a)))
 ```
 
+where `M` is a `Monoid` instance
+
 Added in v2.0.0
 
 ---

diff --git a/src/Traversable.ts b/src/Traversable.ts
@@ -2,18 +2,28 @@
  * `Traversable` represents data structures which can be _traversed_ accumulating results and effects in some
  * `Applicative` functor.
  *
- * `traverse` signature:
+ * - `traverse` runs an action for every element in a data structure, and accumulates the results.
+ * - `sequence` runs the actions _contained_ in a data structure, and accumulates the results.
  *
- * ```ts
- * <F>(F: Applicative<F>) => <A, B>(ta: HKT<T, A>, f: (a: A) => HKT<F, B>) => HKT<F, HKT<T, B>>
- * ```
+ * The `traverse` and `sequence` functions should be compatible in the following sense:
+ *
+ * - `traverse(A)(xs, f) = sequence(A)(A.map(xs, f))`
+ * - `sequence(A)(xs) = traverse(A)(xs, identity)`
+ *
+ * where `A` is an `Applicative` instance
  *
- * `sequence` signature:
+ * `Traversable` instances should also be compatible with the corresponding `Foldable` instances, in the following sense:
  *
  * ```ts
- * <F>(F: Applicative<F>) => <A>(ta: HKT<T, HKT<F, A>>) => HKT<F, HKT<T, A>>
+ * import { getApplicative, make } from 'fp-ts/lib/Const'
+ *
+ * const A = getApplicative(M)
+ *
+ * foldMap(M)(xs, f) = traverse(A)(xs, a => make(f(a)))
  * ```
  *
+ * where `M` is a `Monoid` instance
+ *
  * @since 2.0.0
  */
 import { Applicative, Applicative1, Applicative2, Applicative2C, Applicative3, Applicative3C } from './Applicative'