Attempt to improve the documentation of routines zip, and roundrobin.

Author: bazzaar

doc/Type/List.pod6

@@ -929,59 +929,91 @@ Defined as:
 
     sub zip(+@e, :&with) returns Seq:D
 
-Zips two or more lists or other L<iterables|/type/Iterable> together by
-returning a sequence made of a list of all first elements of all lists, then a
-list of all second elements of a list etc.
+Builds a 'list of lists', returned as a sequence, from multiple input lists or 
+other L<iterables|/type/Iterable>.
 
-    say .join for zip  <a b c>, <d e f>;
-    # ad
-    # be
-    # cf
+C<zip> iterates through each of the input lists synchronously, 'Zipping' them
+together, so that elements are grouped according to their input list index, in 
+the order that the lists are provided.
+
+    say zip(<a b c>, <d e f>, <g h i>);
+    # ((a d g) (b e h) (c f i))
 
 C<zip> has an infix synonym, the C<Z> operator.
 
-    say .join for <a b c> Z <d e f>;    # same output as above
+    say <a b c> Z <d e f> Z <g h i>;                   # same output
 
-The optional C<with> parameter may be used to reduce the zipped lists. For
-example, the following multiplies each pair to get a result.
+C<zip> can provide input to a for loop :
 
-    .say for zip (1, 2, 3), (4, 5, 6), :with(&infix:<*>);
-    # 4
-    # 10
-    # 18
+    for <a b c> Z <d e f> Z <g h i> -> [$x,$y,$z] {say ($x,$y,$z).join(",")}
+    # a,d,g
+    # b,e,h
+    # c,f,i
 
-The C<Z> form can also be used to perform reduction like the C<with> parameter
-by using it as a meta-operator with the reducing operator:
+, or more succinctly :
 
-    .say for (1, 2, 3) Z* (4, 5, 6);    # same output as previous
+    say .join(",") for zip <a b c>, <d e f>, <g h i>;  # same output  
+    
+Note, that if the input lists have an unequal number of elements, then 
+C<zip> terminates once the shortest input list is exhausted, and trailing 
+elements from longer input lists are discarded.
 
-When the first input list is exhausted, no more elements are returned; so
-trailing elements from longer input lists are discarded.
+    say <a b c> Z <d e f m n o p> Z <g h i>;
+    # ((a d g) (b e h) (c f i))
 
-If you just wish to skip missing entries in shorter sublists,
-use L<roundrobin|/type/List#sub_roundrobin> instead:
+In cases where data clipping is possible, but undesired, then consider using 
+L<roundrobin|/type/List#sub_roundrobin> instead of C<zip>.
 
-=for code :skip-test
-for roundrobin(@queue1, @queue2, @queue3) -> $next {
-    ...
-}
+The optional C<with> parameter will additionally reduce the zipped lists. For
+example, the following multiplies corresponding elements together to return a
+single list of products.
+
+    .say for zip <1 2 3>, [1, 2, 3], (1, 2, 3), :with(&infix:<*>);
+    # 1
+    # 8
+    # 27
+
+The C<Z> form can also be used to perform reduction by implicitly setting the
+C<with> parameter with a meta-operator :
+
+    .say for <1 2 3> Z* [1, 2, 3] Z* (1, 2, 3);        # same output
 
 =head2 sub roundrobin
 
 Defined as:
 
     method roundrobin(List:D:) returns Seq
 
-C<roundrobin> is very similar to L<zip|/type/List#routine_zip>.  The
-difference is that C<roundrobin> will not stop on lists that run out of
-elements but simply skip any undefined value:
+Builds a 'list of lists', returned as a sequence, from multiple input lists or 
+other L<iterables|/type/Iterable>. C<roundrobin> returns an identical result to
+that of L<zip|/type/List#routine_zip>, except when the input lists have an 
+unequal number of elements.   
+
+    say roundrobin <a b c>, <d e f>, <g h i>;
+    # ((a d g) (b e h) (c f i))
+
+    say .join(",") for roundrobin([1, 2], [2, 3], [3, 4]);
+    # 1,2,3
+    # 2,3,4
+
+C<roundrobin> does not terminate once one or more of the input lists become 
+exhausted, but proceeds until all elements from all lists have been processed.
+
+    say roundrobin <a b c>, <d e f m n o p>, <g h i j>;
+    # ((a d g) (b e h) (c f i) (m j) (n) (o) (p))
 
-    my @a = 1;
-    my @b = 1..2;
-    my @c = 1..3;
-    for flat roundrobin(@a, @b, @c) -> $x { $x.say }
+    say .join(",") for roundrobin([1, 2], [2, 3, 57, 77], [3, 4, 102]);
+    # 1,2,3
+    # 2,3,4
+    # 57,102
+    # 77
+    
+Therefore no data values are lost due in the 'zipping' operation. A record of 
+which input list provided which element cannot be gleaned from the resulting 
+sequence, however. 
 
-will display the following values: C<1, 1, 1, 2, 2, 3>
+C<roundrobin> can be useful in combining messy data to the point where a manual
+post-processing step can then be undertaken.
 
 =head2 routine sum