Merge branch 'master' of github.com:perl6/doc

Author: jonathanstowe

lib/Language/concurrency.pod

@@ -371,7 +371,7 @@ will be kept (and consequently will evaluate to True in a boolean context,)
 when the channel is closed.
 
 Because looping over a channel in this manner is a common pattern there is
-a simpler fumctional syntax to do this:
+a simpler functional syntax to do this:
 
     my $channel = Channel.new;
 

lib/Language/operators.pod

@@ -265,9 +265,9 @@ In most cases, a dot may be placed before a postfix or postcircumfix:
     @a.[1, 2, 3]; # Same
 
 This can be useful for visual clarity or brevity. For example, if an object's
-attribute is a function, putting a pair of paretheses after the attribute name
-will become part of the method call. So either two pairs of paretheses must be
-used, or a dot has to come before the parentheses to seperate it from the method
+attribute is a function, putting a pair of parentheses after the attribute name
+will become part of the method call. So either two pairs of parentheses must be
+used, or a dot has to come before the parentheses to separate it from the method
 call.
 
     class Operation {

lib/Language/syntax.pod

@@ -328,11 +328,26 @@ Long forms with explicit values:
     :thing['some', 'values']    # same as  thing => ['some', 'values']
     :thing{a => 'b'}            # same as  thing => { a => 'b' }
 
-=begin comment
-
 =head3 Array literals
 
-TODO
+A pair of square brackets can surround an expression to for an
+itmized L<Array|/type/Array> literal; typically there is a comma-delimited list
+inside:
+
+    say ['a', 'b', 42].join(' ');   # a b 42
+    #   ^^^^^^^^^^^^^^ Array constructor
+
+The array constructor flattens non-itemized arrays and lists, but not itemized
+arrays themselves:
+
+    my @a = 1, 2;
+    # flattens:
+    say [@a, 3, 4].elems;       # 4
+
+    # does not flatten:
+    say [[@a], [3, 4]].elems;   # 2
+
+=begin comment
 
 =head3 Hash literals
 

lib/Type/List.pod

@@ -574,6 +574,23 @@ Combining multiple cycles and C<:partial> also works:
     say ('a'..'h').rotor(1 => 1, 3 => -1, :partial).join('|');
                                                     # a|c d e|e|g h
 
+Note that assigning the list of lists returned from C<rotor> to a variable
+will flatten to an C<Array>:
+
+    my @maybe_lol = ('a'..'h').rotor(2 => 1);
+    @maybe_lol.perl.say;   #-> ["a", "b", "d", "e", "g", "h"]<>
+
+Which probably isn't what one wanted, since the C<rotor>-ed output looks
+like this:
+
+    say ('a'..'h').rotor(2 => 1).perl; #-> (("a", "b"), ("d", "e"), ("g", "h"))
+
+To force a C<List> of C<List>s to be returned, I<bind> the output instead of
+assigning it:
+
+    my @really_lol := ('a'..'h').rotor(2 => 1);
+    @really_lol.perl.say;   #-> (("a", "b"), ("d", "e"), ("g", "h"))
+
 =head2 routine zip
 
     sub zip(List:D:, List:D:, ...) returns List:D