doc declaration of multiple variables and destructuring

Author: gfldex

doc/Language/variables.pod6

@@ -518,6 +518,29 @@ introduce an alias into the symbol table.
 
     # Available as $M::Var here.
 
+=head2 Declaring a list of variables
+
+The declarators C<my> and C<our> take a list of variables in parentheses as argument to declare more then one variable at a time.
+
+    my (@a, $s, %h);
+
+This can be used in conjunction with X«destructureing assignment». Any
+assignment to such a list will take the number of elements provided in the left
+list and assign corresponding values from the right list to them. Any missing
+elements are left will result in undefined values according to the type of the
+variables.
+
+    my (Str $a, Str $b, Int $c) = <a b>;
+    say [$a, $b, $c].perl;
+    # OUTPUT«["a", "b", Int]␤»
+
+To destructure a list into a single value create a list literal with one value.
+
+    sub f { 1,2,3 };
+    my ($a,) = f;
+    say $a.perl;
+    # OUTPUT«1␤»
+
 =head2 The C<has> Declarator
 
 C<has> scopes attributes to instances of a class or role, and methods to