--> is not checked at compile time

Author: TimToady

doc/Language/faq.pod

@@ -197,18 +197,26 @@ Likewise C<:U> constrains to undefined values, that is, type objects.
 
 To explicitly allow either type objects or instances, you can use C<:_>.
 
-=head2 What is the --> thing in the signature?
+=head2 What is the C<< --> >> thing in the signature?
 
---> is a return constraint checked at compile time.
+C<< --> >> is a return constraint, either a type or a definite value.
 
-Example:
+Example of a type constraint:
 
-    sub foo ( Int $a, Int $b --> Int ) {
-            return $a + $b;
+    sub divide-to-int( Int $a, Int $b --> Int ) {
+            return ($a / $b).narrow;
     }
 
-    foo(2,3.1)
-    # ===SORRY!===  ... Calling foo(Int, Rat) will never work with declared signature (Int $a, Int $b --> Int)
+    divide-to-int(3, 2)
+    # Type check failed for return value; expected Int but got Rat
+
+Example of a definite return value:
+
+    sub discard-random-number( --> 42 ) { rand }
+    say discard-random-number
+    # 42
+
+In this case the final value is thrown away because the return value is already specified.
 
 =head2 How can I extract the values from a Junction?