From cfe7d5afbb7466dd45df4b5e3f7855d684493e44 Mon Sep 17 00:00:00 2001
From: Richard Feldman <oss@rtfeldman.com>
Date: Mon, 4 Oct 2021 08:39:09 -0400
Subject: [PATCH] Document List.map2 and List.map3

---
 compiler/builtins/docs/List.roc | 43 +++++++++++++++------------------
 1 file changed, 19 insertions(+), 24 deletions(-)

diff --git a/compiler/builtins/docs/List.roc b/compiler/builtins/docs/List.roc
index 65fd34d248..6418c5f31a 100644
--- a/compiler/builtins/docs/List.roc
+++ b/compiler/builtins/docs/List.roc
@@ -6,7 +6,6 @@ interface List
             get,
             set,
             append,
-            map,
             len,
             walkBackwards,
             concat,
@@ -23,9 +22,12 @@ interface List
             last,
             keepOks,
             keepErrs,
-            mapWithIndex,
+            map,
             map2,
             map3,
+            mapWithIndex,
+            mapOrDrop,
+            mapJoin,
             product,
             walkUntil,
             range,
@@ -250,6 +252,21 @@ sortDesc : List elem, (elem -> Num *) -> List elem
 ## See for example `Set.map`, `Dict.map`, and [Result.map].
 map : List before, (before -> after) -> List after
 
+## Run a transformation function on the first element of each list,
+## and use that as the first element in the returned list.
+## Repeat until a list runs out of elements.
+##
+## Some languages have a function named `zip`, which does something similar to
+## calling [List.map2] passing two lists and `Pair`:
+##
+## >>> zipped = List.map2 [ "a", "b", "c" ] [ 1, 2, 3 ] Pair
+map2 : List a, List b, (a, b -> c) -> List c
+
+## Run a transformation function on the first element of each list,
+## and use that as the first element in the returned list.
+## Repeat until a list runs out of elements.
+map3 : List a, List b, List c, (a, b, c -> d) -> List d
+
 ## This works like [List.map], except it also passes the index
 ## of the element to the conversion function.
 mapWithIndex : List before, (before, Nat -> after) -> List after
@@ -349,28 +366,6 @@ join : List (List elem) -> List elem
 ## so we're sticking with `Result` for now.
 oks : List (Result elem *) -> List elem
 
-## Iterates over the shortest of the given lists and returns a list of `Pair`
-## tags, each wrapping one of the elements in that list, along with the elements
-## in the same index in # the other lists.
-##
-## >>> List.zip [ "a1", "b1" "c1" ] [ "a2", "b2" ] [ "a3", "b3", "c3" ]
-##
-## Accepts up to 8 lists.
-##
-## > For a generalized version that returns whatever you like, instead of a `Pair`,
-## > see `zipMap`.
-zip : List a, List b -> List [ Pair a b ]*
-
-## Like `zip` but you can specify what to do with each element.
-##
-## More specifically, [repeat what zip's docs say here]
-##
-## >>> List.zipMap [ 1, 2, 3 ] [ 0, 5, 4 ] [ 2, 1 ] \num1 num2 num3 -> num1 + num2 - num3
-##
-## Accepts up to 8 lists.
-zipMap : List a, List b, (a, b -> c) -> List c
-
-
 ## Filter
 
 ## Run the given function on each element of a list, and return all the