Document zip() builtin

lib/Type/List.pod

@@ -489,4 +489,41 @@ prints
     3 1 2
     3 2 1
 
+=head2 routine zip
+
+    sub zip(List:D:, List:D:, ...) returns List:D
+
+Zip two or more lists together by interleaving their elements.  If the lists
+have different lengths, then the lists are zipped to the length of the
+shortest list; elements of the longer list(s) are discarded.
+
+In order to support parallel iteration over multiple arrays, Perl 6
+has a C<zip> function that builds a list of C<Parcel> objects from the
+elements of two or more arrays.  In ordinary list context this behaves
+as a list of C<Captures> and automatically flattens.
+
+    for zip(@names; @codes) -> $name, $zip {
+        say "Name: $name;   Zip code: $zip";
+    }
+
+C<zip> has an infix synonym, the C<Z> operator.
+
+In an explicitly multidimensional list context, however, the sequences
+turn into subarrays, and each element would then have to be unpacked
+by the signature:
+
+    for lol(zip(@names; @codes)) -> [$name, $zip] {
+        say "Name: $name;   Zip code: $zip";
+    }
+
+By default the C<zip> function reads to the end of the shortest list,
+but a short list may always be extended arbitrarily by putting C<*>
+after the final value, which replicates the final value as many times
+as necessary.  If instead of supplying a default value for short lists,
+you just wish to skip missing entries, use C<roundrobin> instead:
+
+    for roundrobin(@queue1; @queue2; @queue3) -> $next {
+        ...
+    }
+
 =end pod