doc Constraining Return Types

Author: gfldex

doc/Type/Signature.pod

@@ -149,6 +149,31 @@ say limit-lines "a \n b \n c", Int; # "a \n b \n c"
 For explicitly indicating the normal behaviour, C<:_> can be used, but this is
 unnecessary. C<:(Num:_ $)> is the same as C<:(Num $)>.
 
+=head3 X«Constraining Return Types|-->;returns»
+
+The token C<-->> followed by a type will force a type check on successful
+execution of a routine. The return type arrow has to be placed at the end of
+the parameter list. The keyword C<returns> following a signature declaration
+has the same function. C<Nil> is considered as being defined for the type check.
+
+
+	sub foo(--> Int) { 1 };
+	sub foo() returns Int { 1 };
+	sub does-not-work(--> Int) { "" }; # throws X::TypeCheck::Return
+
+If the type constrain is a constant expression, it is used as the return value
+of the routine. Any return statement in that routine has to be argumentless.
+
+	sub foo(--> 123) { return }
+
+C<Nil> and C<Failure> are always allowed as return types, reguardless of any
+type contrain.
+
+	sub foo(--> Int) { Nil };
+	say foo.perl; # Nil
+
+Type captures and coercion types are not supported.
+
 =head2 X<Slurpy (A.K.A. Variadic) Parameters|parameter,*@;parameter,*%>
 
 An array or hash parameter can be marked as I<slurpy> by leading asterisk(s),