Add some initial docs on multis

Author: moritz

lib/Language/functions.pod

@@ -81,14 +81,9 @@ But they can also be used on their own as anonymous blocks of code.
 For details about the syntax of blocks, see the documentation for the
 L<Block> type.
 
-=head2 Multi-dispatch
-
-TODO
-=comment multi, proto, {*}, only
-
 =head2 Signatures
 
-The arguments that a function accepts are described in its I<signature>.
+The parameters that a function accepts are described in its I<signature>.
 
 =for code :allow<B>
 sub formatB<(Str $s)> { ... }
@@ -99,11 +94,39 @@ L<documentation on the C<Signature> class|Signature>.
 
 =comment capture, destructuring,
 
-=head2 Parameters
+=head2 Arguments
 
 TODO
 =comment prefix:<|>, pair-chaining, \()
 
+=head2 Multi-dispatch
+
+Perl 6 allows you to write several routines with the same name, but different
+signatures. When the routine is called by name, the runtime environment
+decides which is the best match, and calls that I<candidate>.
+
+    multi congratulate($name) {
+        say "Happy birthday, $name";
+    }
+    multi congratulate($name, $age) {
+        say "Happy {$age}th birthday, $name";
+    }
+
+    congratulate 'Larry';       # Happy birthday, Larry
+    congratulate 'Bob', 45;     # Happy 45th birthday, Bob
+
+Dispatch can happen on the number of arguments (the I<arity>), but also on the
+type:
+
+    multi as-json(Bool $d) { $d ?? 'true' !! 'false'; }
+    multi as-json(Real $d) { ~$d }
+    multi as-json(@d)      { sprintf '[%s]', @d.map(&as-json).join(', ') }
+
+    say as-json([True, 42]);    # [true, 42]
+
+=comment multi, proto, {*}, only
+
+
 =head1 Functions are First-Class Objects
 
 TODO