[Signature] explain passing of positional and named arguments; parameter aliasing and renaming

Author: moritz

lib/Signature.pod

@@ -86,6 +86,29 @@ except those marked with a leading colon C<:>, and slurpy hash parameters.
     :(*@a)              # a slurpy positional parameter
     :(*%h)              # a slurpy named parameter
 
+On the caller side, positional arguments are passed in the same order
+as the parameters were declared.
+
+    sub pos($x, $y) { "x=$x y=$y" }
+    pos(4, 5);                          # x=4 y=5
+
+In the case of named arguments and parameters, only the name is used for
+mapping arguments to parameters
+
+    sub named(:$x, :$y) { "x=$x y=$y" }
+    named( y => 5, x => 4);             # x=4 y=5
+
+It is possible to have a different name for a named parameter than the
+variable name:
+
+    sub named(:official($private) { }   # parameter name is 'official'
+
+Aliases are also possible that way:
+
+    sub paint( :color(:colour($c)) )    # 'color' and 'colour' are both OK
+    sub paint( :color(:$colour) )       # same API for the caller
+
+
 =head2 Optional and Mandatory Parameters
 
 Named parameters are optional by default, and can be made mandatory with a