doc signature constraints

Author: gfldex

doc/Language/variables.pod

@@ -16,12 +16,12 @@ documentation in L<List>.
 
 =begin table
 
-    Sigil   Type constraint          Default type  Flattens  Assignment
-    =====   ===============          ============  ========  ==========
-    $       Mu (no type constraint)  Any           No        item
-    &       Callable                 Callable      No        item
-    @       Positional               Array         Yes       list
-    %       Associative              Hash          Yes       list
+    Sigil   Type constraint          	Default type  Flattens  Assignment
+    =====   ===============          	============  ========  ==========
+    $       Mu (no type constraint)  	Any           No        item
+    &       L<Callable|/type/Callable>  Callable      No        item
+    @       Positional               	Array         Yes       list
+    %       Associative              	Hash          Yes       list
 
 =end table
 

doc/Type/Callable.pod

@@ -9,6 +9,19 @@
 Role for objects which support calling them. It's used in L<Block>,
 L<Routine>, L<Sub>, L<Method>, L<Submethod> and L<Macro> types.
 
+Callables can be stored in C<&>-sigiled containers, the default type constrain
+if such a container is C<Callable>. A signature object can be used to
+force a check against the signature of the Callable to be stored into the
+congtainer.
+
+	my &a = {};
+	my &b = -> {};
+	my &c = sub () {};
+	sub foo () {};
+	my &d = &foo;
+	my &f:(Int) = sub bar (Int) {};
+	my &f:(Str) = -> Str {};
+
 =head1 Methods
 
 =head2 method assuming

doc/Type/Signature.pod

@@ -38,6 +38,16 @@ my $sig = B<:($a, $b)>;
 #          ^^^^^^^^ Standalone Signature object
 =end code
 
+Signature literals can be used to define the signature of a callback or a
+cloasure.
+
+	sub f(&c:(Int)){}
+	sub will-work(Int){}
+	sub won't-work(Str){}
+	f(&will-work);
+	f(&wont-work); # fails at runtime
+	f(-> Int { 'this works too' } );
+
 =head2 Parameter Separators
 
 A signature consists of zero or more I<L<parameters|Parameter>>, separated by comma.