Manually apply PR#3325

"Clarify how control flow is handled in CATCH blocks"

RIP Kaiepi++

Author: coke

doc/Language/exceptions.rakudoc

@@ -80,14 +80,18 @@ which is what C<$*ERR.say> does, getting displayed on whatever constitutes the
 standard error device in that moment, which will probably be the console by
 default.
 
-A C<CATCH> block uses smartmatching similar to how C<given/when>
-smartmatches on options, thus it's possible to catch and handle various
-categories of exceptions inside a C<when> block. And it does so because,
-within the block, C<$_> is set to the exception that has been raised.
-
-To handle all exceptions, use a C<default> statement. This example prints out
-almost the same information as the normal backtrace printer; the I<dot>
-methods apply to C<$_>, which holds the L<C<Exception>|/type/Exception> within the C<CATCH> block.
+Note that the match target is a role. To allow user defined exceptions
+to match in the same manner, they must implement the given role. Just
+existing in the same namespace will make them look alike but won't match
+in a C<CATCH> block.
+
+A C<CATCH> block places any exception thrown in its topic variable
+(C<$_>), thus it's possible to catch and handle various categories of
+exceptions inside a C<when> block. To handle all exceptions, use a
+C<default> statement. This example prints out almost the same
+information as the normal backtrace printer. Note that the I<dot>
+methods apply to C<$_>, which holds the
+L<C<Exception>|/type/Exception> within the C<CATCH> block.
 
     CATCH {
          default {
@@ -100,11 +104,20 @@ methods apply to C<$_>, which holds the L<C<Exception>|/type/Exception> within t
          }
     }
 
-Note that the match target is a role. To allow user defined exceptions to
-match in the same manner, they must implement the given role. Just existing
-in the same namespace will look alike but won't match in a C<CATCH> block.
+While this is a very common pattern, it is not strictly necessary to use
+C<default> or C<when> in a C<CATCH> block. This is done to prevent the
+control flow from reaching the end of the block where, unless the
+exception has been L<resumed|#Resuming_of_exceptions>, the exception
+will continue to be thrown.  Allowing this can be used for logging
+purposes, for instance:
+
+=for code
+# In the outermost block of a script...
+my IO::Handle:D $log = open sprintf('logs/%d-%d.txt', $*INIT-INSTANT, $*PID), :a;
+CATCH { $log.printf: "[%d] Died with %s: %s$?NL", now, .^name, .message }
+END   { $log.close }
 
-Note that the C<CATCH> block semantics apply to the B<entire> lexical scope
+The C<CATCH> block semantics apply to the B<entire> lexical scope
 in which it is defined, B<regardless> of where it is defined inside that
 lexical scope.  It is therefore advised to put any C<CATCH> block at the
 start of the lexical scope to which they apply so that the casual reader