Explain P5 -> P6 difference for shift/unshift better

Author: lizmat

doc/Language/5to6-perlfunc.pod6

@@ -1116,7 +1116,7 @@ and from processes.
 Works in Perl 6, and can also be used as a method. I. e. C<my $x = pop
 @a;> and C<my $x = @a.pop;> are equivalent.
 
-The non-paramater version of C<pop> does not exist.  Also, if the array
+The non-parameter version of C<pop> does not exist.  Also, if the array
 is empty, a Failure will be returned in Perl 6, which will throw if the
 value is actually used in a significant way.
 
@@ -1492,8 +1492,25 @@ Not documented, but probably hiding in an C<IO> class somewhere.
 
 =item shift
 
-Works as a method as well as a function. C<shift @a> and C<@a.shift> are
-equivalent.
+Works in Perl 6, and can also be used as a method. I. e. C<my $x = shift
+@a;> and C<my $x = @a.shift;> are equivalent.
+
+The non-parameter version of C<shift> does not exist.  Also, if the array
+is empty, a Failure will be returned in Perl 6, which will throw if the
+value is actually used in a significant way.
+
+If you are using only defined values in your array, you can use the C<with>
+function to handle this case:
+
+    with shift @array -> $shifted {
+        say "shifted '$shifted' of the array";
+    }
+    else {
+        say "there was nothing to shift";
+    }
+
+The Perl 6 ecosystem has a module C<P5shift> which exports a C<shift>
+function that mimics the original Perl 5 behaviour as much as possible.
 
 =head2 shm*
 
@@ -1919,8 +1936,16 @@ Perl 6 version.
 
 =item unshift EXPR, LIST
 
-Available in Perl 6. Can be used as a method. C<unshift(@a, "blah")> is
-equivalent to C<@a.unshift("blah")>.
+Works as in Perl 5, as well as being available as a method:
+C<@a.unshift("foo");>. I<Note:> the flattening behaviour is different in Perl 6:
+C<@b.unshift: @a> will unshift C<@a> into C<@b> as a single element. See also the
+L<prepend method|/type/Array#method_prepend>.
+
+Also note that C<unshift> in Perl 6 returns the array to which was pushed,
+contrary to Perl 5 where it returns the new number of elements.
+
+The Perl 6 ecosystem has a module C<P5shift> which exports a C<unshift>
+function that mimics the original Perl 5 behaviour as much as possible.
 
 =head2 untie