Restore documentation of multis

All multi signatures found in the Rakudo implementation should be
documented. Parameter names can be changed to fit the documentation.

Author: dumarchie

doc/Type/Array.pod6

@@ -55,9 +55,11 @@ L<subroutine|/language/independent-routines#sub_pop>. For example:
 Defined as:
 
     multi method push(Array:D: **@values is raw --> Array:D)
+    multi method push(Array:D: \value --> Array:D)
+    multi method push(Array:D: Slip \values --> Array:D)
 
-Adds the provided values to the end of the array, and returns the modified
-array. If any argument is a C<Slip>, method C<push> will add the values
+Adds the provided value or values to the end of the array, and returns the
+modified array. If any argument is a C<Slip>, method C<push> will add the values
 produced by the argument's L<iterator|/routine/iterator>. It throws if the
 invocant array or a C<Slip> L<is lazy|/routine/is-lazy>.
 
@@ -91,15 +93,23 @@ values that are produced by a single non-slipping C<Iterable>.
 
 Defined as
 
+    multi method append(Array:D: **@values is raw --> Array:D)
+    multi method append(Array:D: \arg --> Array:D)
+
+Adds the provided values to the end of the array and returns the modified array,
+or throws if the invocant array or an argument that requires flattening L<is
+lazy|/routine/is-lazy>.
+
+In contrast with L<method push|/type/Array#method_push>, method C<append>
+adheres to the L<single argument rule|/language/functions#Slurpy_conventions>
+and is probably best thought of as:
+
     multi method append(Array:D: +values --> Array:D)
 
-Adds the provided values to the end of the array and returns the modified
-array, or throws if the invocant array or an argument that requires flattening
-L<is lazy|/routine/is-lazy>.
+This means that if you pass a B<single> argument that is a
+non-L<itemized|/language/mop#VAR> C<Iterable>, C<append> will try to flatten it.
 
-The difference with L<method push|/type/Array#method_push> is that if you append
-a B<single> non-L<itemized|/language/mop#VAR> C<Iterable>, C<append> will try to
-flatten it. For example:
+For example:
 
     my @a = <a b c>;
     my @b = <d e f>;

doc/Type/independent-routines.pod6

@@ -1200,7 +1200,7 @@ Routines that manipulate arrays and other containers.
 
 Defined as:
 
-    multi sub pop(@container)
+    multi sub pop(@container) is raw
 
 Calls method C<pop> on the C<Positional> container. That method is supposed to
 remove and return the last element, or return a L<C<Failure>|/type/Failure> if
@@ -1213,7 +1213,7 @@ for an example.
 
 Defined as:
 
-    multi sub shift(@container)
+    multi sub shift(@container) is raw
 
 Calls method C<shift> on the C<Positional> container. That method, on
 a mutable container that actually implements it (such as an
@@ -1234,26 +1234,49 @@ say shift @a; # ERROR: «Cannot shift from an empty Array[Int]␤»
 Defined as:
 
     multi sub push(\container, **@values is raw)
+    multi sub push(\container, \arg)
 
 Calls method C<push> on the container, which is supposed to add the provided
 values to the end of the container or parts thereof. See the documentation of
 the L<C<Hash> method|/routine/push#(Hash)_method_push> for an example where
 indirection via this subroutine can be helpful.
 
+The C<push> method of the container is supposed to flatten all arguments of type
+C<Slip>. Therefore, if you want to implement a conforming method for a new
+container type, it should behave as if its signature was just:
+
+    multi method push(::?CLASS:D: **@values --> ::?CLASS:D)
+
+Autovivification to an instance of the new type is L<provided by the default
+base class|/routine/append#(Any)_method_append> if the new type implements the
+C<Positional> role. If the new type is not C<Positional>, autovivification can
+be implemented by an additional multi method with a signature like
+
+    multi method push(::?CLASS:U: **@values --> ::?CLASS:D)
+
 =head2 sub append
 
 Defined as:
 
-    multi sub append(\container, +values)
+    multi sub append(\container, **@values is raw)
+    multi sub append(\container, \arg)
 
 Calls method C<append> on the container, which is supposed to add the provided
 values to the end of the container or parts thereof. Unlike method C<push>,
-method C<append> is supposed to add the values produced by the argument's
-L<iterator|/routine/iterator> if called with a B<single> non-slipping
-C<Iterable> that is not inside a C<Scalar> container.
+method C<append> should follow the L<single argument
+rule|/language/functions#Slurpy_conventions>. So if you want to implement a
+conforming method C<append> for a new container type, it should behave as if its
+signature was just:
+
+    multi method append(::?CLASS:D: +values --> ::?CLASS:D)
+
+Similar to L<routine C<push>|/routine/push#(Independent_routines)_sub_push>, you
+may need to add a multi method if you want to support autovivification:
+
+    multi method append(::?CLASS:U: +values --> ::?CLASS:D)
 
-Indirection via this subroutine can be helpful when appending to the values of a
-C<Hash>. Whereas L<method C<append>|/routine/append#(Hash)_method_append> will
+The subroutine form of C<append> can be helpful when appending to the values of
+a C<Hash>. Whereas L<method C<append>|/routine/append#(Hash)_method_append> will
 silently ignore literal pairs that are interpreted as named arguments, the
 subroutine will throw: