Improves documentation for shortcut, closes #2229

Author: JJ

doc/Type/Signature.pod6

@@ -643,9 +643,10 @@ X<|positional argument>
 X<|named argument>
 =head2 Positional vs. named arguments
 
-An argument can be I<positional> or I<named>. All arguments are positional,
-except slurpy hash and arguments marked with a leading colon C<:>.
-The latter is called a L<colon-pair|/type/Pair>.
+An argument can be I<positional> or I<named>. By default, arguments are
+positional, except slurpy hash and arguments marked with a leading colon C<:>.
+The latter is called a L<colon-pair|/type/Pair>. Check the following signatures
+and what they denote:
 
     $ = :($a);               # a positional argument
     $ = :(:$a);              # a named argument of name 'a'
@@ -658,15 +659,26 @@ arguments are declared.
     sub pos($x, $y) { "x=$x y=$y" }
     pos(4, 5);                          # OUTPUT: «x=4 y=5»
 
-In the case of named arguments and parameters, only the name is used for
-mapping arguments to parameters. If a fat arrow is used to construct a
-L<Pair|/type/Pair> only those with valid identifiers as keys are recognized
-as named arguments.
+In the case of named arguments and parameters, only the name is used for mapping
+arguments to parameters. If a fat arrow is used to construct a
+L<Pair|/type/Pair> only those with valid identifiers as keys are recognized as
+named arguments.
 
 =for code :allow<L>
 sub named(:$x, :$y) { "x=$x y=$y" }
 named( y => 5, x => 4);             # OUTPUT: «x=4 y=5»
 
+You can invoke the routine using a variable with the same name as the named
+argument; in that case C<:> will be used for the invocation so that the name of
+the variable is understood as the key of the argument.
+
+    sub named-shortcut( :$shortcut ) {
+        say "Looks like $shortcut"
+    }
+    named-shortcut( shortcut => "to here"); # OUTPUT: «Looks like to here␤»
+    my $shortcut = "Þor is mighty";
+    named-shortcut( :$shortcut );           # OUTPUT: «Looks like Þor is mighty␤»
+
 It is possible to have a different name for a named argument than the
 variable name: