add info on space probs with function call format

Author: tbrowder

doc/Language/traps.pod

@@ -248,6 +248,53 @@ The loose precedence of C<..> can lead to some errors.  It is usually best to pa
     1..3.say    # says "3" (and warns about useless "..")
     (1..3).say  # says "1..3"
 
+=head1 Subroutine and method calls
+
+Subroutine and method calls can be made using one of two forms:
+
+  foo(...); # function call form, where ... represent the required arguments
+  foo ...;  # list op form, where ... represent the required arguments
+
+The function call form can cause problems for the unwary when
+whitespace is added after the function or method name and before the
+opening parenthesis.
+
+First we consider functions with zero or one parameter:
+
+  sub foo() { say 'no arg' }
+  sub bar($a) { say "one arg: $a" }
+
+Then execute each with and without a space after the name:
+
+  foo();    # okay: no arg
+  foo ();   # FAIL: Too many positionals passed; expected 0 arguments but got 1
+  bar($a);  # okay: one arg: 1
+  bar ($a); # okay: one arg: 1
+
+Now declare a function of two parameters:
+
+  sub foo($a, $b) { say "two args: $a, $b" }
+
+Execute it with and without the space after the name:
+
+  foo($a, $b);  # okay: two args: 1, 2
+  foo ($a, $b); # FAIL: Too few positionals passed; expected 2 arguments but got 1
+
+The lesson is: "be careful with spaces following sub and method names
+when using the function call format."  As a general rule, good
+practice might be to avoid the space after a function name when using
+the function call format.
+
+Note that there are clever ways to eliminate the error with the
+function call format and the space, but that is bordering on hackery
+and will not be mentioned here.  For more information, consult
+L<Functions|/language/functions#Functions>.
+
+Finally, note that, currently, when declaring the functions whitespace
+may be used between a function or method name and the parentheses
+surrounding the parameter list without problems (although that may
+change in the future).
+
 =end pod
 
 # vim: expandtab shiftwidth=4 ft=perl6