Attempt to document ｢$foo.bar: |@A｣ trap

See issue #602.

Author: AlexDaniel

doc/Language/traps.pod6

@@ -675,6 +675,35 @@ The nice thing about the distinction here is that it gives the developer the
 option of passing pairs as either named or positional arguments, which can be
 handy in various instances.
 
+=head2 Argument Count Limit
+
+While it is typically unnoticeable, there is a backend-dependent
+argument count limit. Any code that does flattening of arbitrarily
+sized arrays into arguments won't work if there are too many elements.
+
+=for code
+    my @a = 1 xx 9999;
+    my @b;
+    @b.push: |@a;
+    say @b.elems # OUTPUT: «9999␤»
+
+=for code
+    my @a = 1 xx 999999;
+    my @b;
+    @b.push: |@a; # OUTPUT: «Too many arguments in flattening array.␤  in block <unit> at <tmp> line 1␤␤»
+
+
+Avoid this trap by rewriting the code so that there is no
+flattening. In the example above, you can replace C<push> with
+C<append>. This way, no flattening is required because the array can
+be passed as is.
+
+=for code
+    my @a = 1 xx 999999;
+    my @b;
+    @b.append: @a;
+    say @b.elems # OUTPUT: «999999␤»
+
 =head1 Input and Output
 
 =head2 Closing Open File Handles and Pipes