funcitons: talk about return

Author: moritz

lib/Language/functions.pod

@@ -225,12 +225,34 @@ are as easy to use and powerful as C<map>.
 
 =head2 Routines
 
-TODO
-=comment return from sub and return from block
+Routines are code objects that conform to L<type Routine|/type/Routine>, most
+notably L<Sub|/type/Sub>, L<Method|/type/Method>, L<Regex|/type/Regex> and
+L<Submethod|/type/Submethod>.
 
-=comment Important ones: candidates, wrap, unwrap, assuming, arity, count
+They carry additional functionality in addition to what L<Block|/type/Block>
+supplies: they can come as L<multis|#Multi-dispatch>,
+you can L<wrap|/type/Routine#method warp> them, and exit early with C<return>:
+
+=begin code :allow<B>
+my $keywords = set <if for unless while for>;
+
+sub has-keyword(*@words) {
+    for @words -> $word {
+        B<return> True if $word (elem) $keywords;
+    }
+    False;
+}
 
-=comment link to Routine documentation (?)
+say has-keyword 'not', 'one', 'here';       # False
+say has-keyword 'but', 'here', 'for';       # True
+=end code
+
+Here C<return> does not just leave the block inside which it was called, but
+the whole routine. In general, blocks are transparent to C<return>, they
+attach to the outer routine.
+
+
+=comment Important ones: candidates, wrap, unwrap, assuming, arity, count
 
 =head1 Defining Operators